OAuth 2.0 Token Introspection
Extracted elements (28)
Inactive or unauthorized tokens return HTTP 200 with 'active': false rather than an HTTP error code to avoid disclosing authorization server state to third parties — an attacker cannot distinguish a revoked token from a non-existent one from the response alone.
The location of the introspection endpoint is intentionally out of scope to allow flexibility in deployment; protected resources may discover it via service documentation, configuration, or future discovery mechanisms rather than a fixed path.
The specification notes that for proof-of-possession tokens, introspection can be used to retrieve the key information associated with a token identifier, enabling the protected resource to validate the cryptographic proof without being aware of the token's full contents — a use case deferred to a future extension.
Token introspection was designed because OAuth 2.0 tokens are opaque to clients and resource servers, yet protected resources need token metadata (validity, scopes, authorization context) to make access decisions. Prior approaches required structured tokens (JWT) or proprietary inter-service mechanisms; this specification provides a standard protocol.
A query for an inactive, unknown, or unauthorized token is not treated as an error; the server returns HTTP 200 with 'active': false. HTTP error codes (401) are reserved for cases where the caller's own credentials are invalid.
New introspection response field names that match claims registered in the 'JSON Web Token Claims' registry (RFC 7519) SHOULD have comparable definitions and semantics, ensuring alignment between introspection responses and JWT claims.
The authorization server MAY respond differently to different protected resources making the same introspection request — for example, by limiting which scopes are disclosed to each protected resource to prevent information leakage about the larger token network.
If the introspection call is properly authorized but the token is not active, does not exist, or the protected resource is not allowed to introspect it, the authorization server MUST return an introspection response with the 'active' field set to 'false'.
If the introspection response contains the 'exp' parameter, the response MUST NOT be cached beyond the time indicated therein.
Response names intended to be used across domains MUST be registered in the 'OAuth Token Introspection Response' registry defined in Section 3.1.
The authorization server MUST perform all applicable checks against a token's state, including expiration, not-before time, revocation, signature validation, and audience restriction, before responding to an introspection request.
The introspection endpoint MUST be protected by a transport-layer security mechanism. The server MUST support TLS 1.2 and the client or protected resource MUST perform a TLS/SSL server certificate check as specified in RFC 6125.
The 'token' parameter is REQUIRED in the introspection request. If the server is unable to locate the token using a provided token_type_hint, it MUST extend its search across all of its supported token types.
To avoid disclosing the internal state of the authorization server, an introspection response for an inactive token SHOULD NOT contain any additional claims beyond the required 'active' claim set to 'false'.
To prevent token scanning attacks, the introspection endpoint MUST require some form of authorization to access it, such as client authentication or a separate OAuth 2.0 access token. The authorization server SHOULD require protected resources to be specifically authorized to call the endpoint.
When the introspection response may contain privacy-sensitive information such as user identifiers, measures MUST be taken to prevent disclosure of this information to unintended parties, such as transmitting user identifiers as opaque service-specific strings.
If a protected resource sends additional client context (such as the client's IP address) to the authorization server via extensions to this specification, such information could carry additional privacy implications that the extension must address.
Introspection responses may contain privacy-sensitive information such as user identifiers. To minimize exposure, user identifiers SHOULD be transmitted as opaque service-specific strings, and the server MAY return different identifiers to different protected resources.
The 'active' field is the only REQUIRED field in the introspection response; it is a boolean indicator of whether the presented token is currently active. All other response fields are OPTIONAL and provide contextual metadata about the token.
The introspection endpoint is an OAuth 2.0 endpoint that accepts a token parameter and returns a JSON document representing the meta-information surrounding the token, including whether the token is currently active. The definition of 'active' is implementation-dependent but typically means issued by this server, not expired, and not revoked.
The introspection request requires a 'token' parameter (the string value of the token) and optionally a 'token_type_hint' parameter (a hint about the token type to help the server optimize lookup). Values for token_type_hint are defined in the 'OAuth Token Type Hints' registry from RFC 7009.
The introspection response is a JSON object with a required 'active' boolean field and optional fields including 'scope', 'client_id', 'username', 'token_type', 'exp', 'iat', 'nbf', 'sub', 'aud', 'iss', and 'jti'. Implementations MAY extend the structure with service-specific top-level members.
This specification establishes the 'OAuth Token Introspection Response' registry, using Specification Required policy with a two-week review period on [email protected]. Initial entries include: active, username, client_id, scope, token_type, exp, iat, nbf, sub, aud, iss, and jti.
Caching introspection responses improves performance but creates a window where a revoked token could still be accepted at the protected resource. Highly sensitive environments should disable caching entirely; if the 'exp' claim is present, the cache MUST NOT be retained past that time.
To prevent access token values from appearing in server-side logs, an authorization server MAY disallow HTTP GET on the introspection endpoint and require HTTP POST instead.
Without throttling and authentication, the introspection endpoint could be used by an attacker to poll a series of possible token values to fish for a valid token. Authentication of callers and specific authorization to use the endpoint are the primary mitigations.
Introspection requests are HTTP POST with Content-Type 'application/x-www-form-urlencoded'. Responses are JSON objects with Content-Type 'application/json'. The token value is sent as a form-encoded parameter named 'token'.
Timestamp fields 'exp', 'iat', and 'nbf' are integer values measured in seconds since January 1 1970 UTC (Unix epoch), following the JWT (RFC 7519) definition. The 'scope' field is a space-separated string of scope values.