Configuring token introspection for MCP

Configure live OAuth 2.0 token introspection (RFC 7662) for the Data Fabric MCP server to verify token active status and enforce immediate session revocation across all MCP endpoints.

The Data Fabric Model Context Protocol (MCP) server supports live OAuth 2.0 Token Introspection ([RFC 7662] (https://datatracker.ietf.org/doc/html/rfc7662)) to validate bearer access tokens against the identity provider (Keycloak).

By default, standard JSON Web Token (JWT) verification operates statelessly (offline)—validating only the cryptographic signature and token expiration timestamp (exp). While efficient, offline validation allows a token to remain usable for its full lifetime (typically up to two hours), even if the user logs out or an administrator explicitly revokes the token.

Token introspection closes this security gap by querying Keycloak in near-real-time to confirm that the session and token remain active.

NOTE
Token introspection is enforced at the Data Access Gateway layer (JWTAuthHandler) and governs all MCP endpoints.

How token introspection works

When a client or AI assistant makes an MCP request, the gateway validates the bearer token through a two-stage evaluation.
  1. Initial offline validation:
    • The gateway performs standard verification on the incoming JWT (signature authenticity, issuer, audience, and expiration).
    • Forged, malformed, or expired tokens are rejected immediately with HTTP 401 Unauthorized without calling Keycloak.
  2. Cache check:
    • The gateway checks an in-memory cache for an existing introspection status for the token.
    • If a valid, non-expired cache entry exists and indicates the token is active, the request is allowed immediately.
  3. Identity provider introspection:
    • If no cache entry exists (or the entry has expired), the gateway sends an RFC 7662 introspection request to Keycloak's introspection endpoint (discovered automatically via the realm's OIDC discovery document).
    • The gateway authenticates against Keycloak using its configured confidential client credentials.
  4. Result processing and caching:
    • Active - If Keycloak responds with {"active": true}, the active status is cached for the configured Time-to-Live (TTL) duration, and the request proceeds to downstream services.
    • Inactive / Revoked - If Keycloak responds with {"active": false}, the gateway immediately rejects the request with HTTP 401 Unauthorized.

Security and operational characteristics

  • Mitigating Revocation and Logout Latency:

    When a user logs out or an admin terminates a session in Keycloak, access is revoked across all MCP endpoints as soon as the local introspection cache expires (within 60 seconds by default). Setting the cache TTL to 0 enables immediate revocation checks on every incoming request.

  • Fail-Closed Enforcement:

    If the Keycloak introspection endpoint is unreachable, network timeouts occur, client authentication fails, or Keycloak returns any non-200 HTTP response, the gateway strictly fails closed. The request is denied with an HTTP 401 Unauthorized error. Downstream services and tools are never invoked under an unverified identity.

  • Active Sessions:

    Introspection applies continuously to ongoing MCP sessions. A client with an established connection cannot continue issuing tool calls once its token has been invalidated in Keycloak and the cache TTL has elapsed.

Configuration reference

Configure token introspection properties in mcp-server.conf:

Property Type Default Description
mcp.http.auth.introspection.enabled Boolean true Enables or disables live RFC 7662 token introspection against Keycloak. When set to false, the gateway relies solely on offline JWT signature and expiration verification.
mcp.http.auth.introspection.cache-ttl-ms Long 60000 (60 seconds) The duration in milliseconds to cache introspection results (active / inactive) per token. • Default: 60000 (60 seconds) • Set to 0 to disable caching and query Keycloak on every incoming request. • Higher values reduce load on Keycloak but increase the maximum delay before a revoked token takes effect.

Configuration example

mcp {
  http {
    auth {
      introspection {
        enabled = true
        cache-ttl-ms = 60000
      }
    }
  }
}