Token Introspection

The primary function is to determine if an access token is active, expired, revoked, or otherwise invalid. This prevents the use of stolen or stale tokens. The authorization server returns a boolean active claim.

• Core Security Check: The resource server must not trust the token's presence alone.
• Real-Time Validation: Unlike offline JWT validation, this provides a real-time check against the authoritative source of truth.

Beyond a simple yes/no, introspection returns a JSON object with the token's metadata. This includes standardized and custom claims essential for authorization.

• Standard Claims: scope, client_id, username, exp (expiration), iat (issued at), sub (subject).
• Custom Claims: Authorization servers can add domain-specific claims (e.g., department, permissions).
• Use Case: A resource server uses the scope claim to enforce fine-grained access control before processing an API request.

The introspection request is made by the resource server (API backend), not the client application. This maintains the OAuth 2.0 separation of concerns.

• Client Obligation: The client simply presents the bearer token.
• Server Responsibility: The resource server is responsible for validating it via the introspection endpoint.
• Architecture: This pattern centralizes token logic at the authorization server, simplifying resource server code.

The introspection endpoint itself is a protected resource. The resource server must authenticate to the authorization server using its own credentials, typically via HTTP Basic Auth with a client ID/secret or via mTLS.

• Security Rationale: Prevents unauthorized parties from querying token metadata, which could leak sensitive information.
• Confidential Client: The resource server acts as a confidential OAuth 2.0 client for the introspection call.

Introspection is often used alongside or instead of offline JWT validation. It is essential for tokens that are reference tokens (opaque strings) but can also be used for JWTs when immediate revocation checks are required.

• Opaque Tokens: Mandatory for validation, as the token string itself holds no usable data.
• JWTs with Revocation: Allows for immediate token invalidation, which is not possible with stateless JWT validation alone.
• Trade-off: Introduces a network dependency and latency versus the offline speed of JWT signature checks.

RFC 7662 defines a predictable JSON response format, ensuring interoperability between authorization servers and resource servers from different vendors.

• Required active Claim: A boolean indicating token validity.
• Conditional Claims: Metadata like scope is only included if the token is active and the claim is applicable.
• Example Response: {"active": true, "client_id": "s6BhdRkqt3", "scope": "read write", "exp": 1735689600}

Token introspection is an extension of the OAuth 2.0 authorization framework defined in RFC 6749. OAuth 2.0 provides the foundational model for delegated access, where:

• A client application requests access to a user's resources.
• An authorization server issues tokens after user consent.
• A resource server validates these tokens to grant access. Introspection allows the resource server to query the authorization server directly for token state, enhancing security beyond simple bearer token presentation.

A Bearer Token (RFC 6750) is the most common type of access token used in OAuth 2.0. It is a cryptographically signed credential that grants the 'bearer' access to a protected resource. Key characteristics include:

• Presented in the Authorization: Bearer <token> HTTP header.
• The resource server must validate its signature, expiration, and scope. Token introspection is the primary mechanism for a resource server to validate an opaque bearer token (one that is not self-contained like a JWT) by calling the authorization server's introspection endpoint.

A JSON Web Token (JWT, RFC 7519) is a compact, self-contained token format that encodes claims in a JSON object. For validation:

• A self-contained JWT can be validated locally by the resource server using a public key (JWK) to verify its signature, eliminating the need for an introspection call for each request.
• Introspection is still used when tokens are revoked before expiry, as the revocation state is not encoded in the JWT itself. The introspection endpoint provides the definitive active/inactive status.

The Authorization Server is the OAuth 2.0 component that issues access tokens and, crucially, hosts the token introspection endpoint (/introspect). Its responsibilities include:

• Authenticating clients and resource owners.
• Obtaining authorization consent.
• Issuing, tracking, and validating the lifecycle of all tokens.
• Responding to introspection requests with a JSON object detailing the token's active state, client ID, scopes, and expiration.

The Resource Server (or API server) hosts the protected endpoints that clients wish to access. It is the component that consumes access tokens and must validate them. Its interaction with token introspection involves:

• Receiving a request with a bearer token.
• Calling the authorization server's introspection endpoint with the token to verify it is active and to retrieve its metadata.
• Granting or denying access based on the introspection response (e.g., checking active: true and valid scopes).

Token Revocation (RFC 7009) is the process of invalidating an access or refresh token before its natural expiration. It is the complementary action to token introspection. Key points:

• A client or admin calls the revocation endpoint to invalidate a token.
• Subsequent introspection calls for that token will return active: false.
• This provides immediate access termination for security responses, unlike waiting for token expiry. Introspection is necessary because a revoked bearer token remains cryptographically valid until it expires.