Introspection

• The OAuth Token Introspection protocol defines a mechanism for a protected resource to actively query an Authorization Server about the state of the token.

• The Introspection request is an HTTP request to the Authorization Server's Introspection endpoint.

  • The Introspection specification does not mandate how the protected resource needs to authenticate itself, only that it does so. In the examples below, the protected resource authenticates itself using an ID and secret in the form of the HTTP Basic request header.

    • POST /introspect HTTP/1.1
      Host: localhost:9001
      Accept: application/json
      Content-type: application/x-www-form-encoded
      Authorization: Basic cHJvdGVjdGVkLXJlc291cmNlLTE6cHJvdGVjdGVkLXJlc291cmNlLXNlY3JldC0x
      
      token=987tghjkiu6trfghjuytrghj

    • HTTP 200 OK
      Content-type: application/json
      
      {
        "active": true,
        "scope": "foo bar baz",
        "client_id": "oauth-client-1",
        "username": "alice",
        "iss": "http://localhost:9001/",
        "sub": "alice",
        "aud": "http://localhost:/9002/",
        "iat": 1440538696,
        "exp": 1440538996,
      }

• The Introspection specification defines several claims including the active claim which tells the protected resource whether the current token is active.

  • The active claim is the only claim required to be returned.

• To combat the overhead of increased network traffic that occurs when Introspection calls are invoked, the protected resource can cache the results.

  • However ensure the cache is short-lived.