RFC 7662 / START HERE
Token introspection, before the details
OAuth 2.0 Token Introspection means asking the authorization server about a token’s current state.
A protected API can send a token to an authorized introspection endpoint and receive JSON saying whether it is active, along with optional context such as permissions and expiration. The API uses that information to make its access decision.
The idea in one picture
API submits token
Issuer checks state
API applies permissions
A simplified picture of the idea; the chapters explain the actual mechanisms.
Why it exists
A token may be an opaque string or contain structured information. The API still needs reliable, current state from the system that issued it, including revocation and resource restrictions. RFC7662 defines that query instead of requiring a proprietary shared database.
A familiar example
A fictional calendar API asks whether a presented token is active and has read permission. Even active true does not grant write access. Cached replies may be stale after revocation, so the API must choose its cache policy carefully.
Helpful background
You can start here without reading another RFC. If these ideas are unfamiliar, these short introductions may help.
What you’ll learn next
Begin with chapter one, or choose a topic.
- The API asks about a presented tokenA resource server receiving a token can ask the authorization server for its current state and metadata. The caller of introspection is the protected resource, not the original OAuth client.→
- Perform all applicable state checksThe authorization server must evaluate the token’s actual state. Reading a token’s claims without validating applicable conditions is not introspection success.→
- Read JSON metadata with its actual typesThe response is an application/json object. active is a required JSON Boolean; most other fields are optional context and must be interpreted with their specified types.→
- Inactive results differ from unauthorized callsA validly authorized inspection that finds no usable token is different from a caller that is not allowed to use introspection at all.→
- Bound cache use and account for revocationCaching can reduce introspection traffic, but the cached state can become stale if a token is revoked before the cache is refreshed.→
- Limit disclosure and authenticate the endpointToken metadata may identify people and reveal other services. The authorization server can tailor the response to the protected resource and avoid unnecessary disclosures.→
This introduction explains RFC 7662 (2015). Read the original RFC ↗