JWT Response for OAuth Token Introspection

Overview

This provides describes overview of JWT Response for OAuth Token Introspection and instructions on how to configure services and resource servers to enable the feature.



Introduction

Below is a diagram that roughly illustrates token introspection flow in JWT Response for OAuth Token Introspection.
Token Introspection Flow in JWT Response for OAuth Token Introspection


1. Introspection Request

First, the resource server sends an introspection request to the authorization server including an HTTP Accept header set to "application/token-introspection+jwt". The header value indicates that the resource server is requesting a JWT introspection response from the authorization server.

2. Authenticate Resource Server

Once the introspection request is accepted, the authorization server must authenticate the resource server. If the authentication succeeds, the authorization server then retrieves the necessary information about the resource server (e.g. the resource server's URI, the sign algorithm for JWT introspection responses, etc), which is required for signing/encrypting introspection responses. 

3. Request to Authlete /auth/introspection/standard API 

Then, the authorization server calls Authlete /auth/introspection/standard API including the resource server's information obtained in step 2. 

4. Response from Authlete /auth/introspection/standard API 

If the request is valid, Authlete returns an API response including a JWT introspection response. The authorization server is then expected to return this response to the resource server.

5. JWT Introspection Response

After receiving a successful API response from Authlete, the authorization server returns the JWT introspection response, contained in the Authlete API response, back to the resource server.

Service configuration

Configure your service (authorization server) as below.
Property
Description
JWK Set
NOTE: This configuration is only required if "JWK Set" is used.

Set a JWK set containing at least one sign key for JWT introspection responses.
JWK Set Endpoint URI
NOTE: This configuration is only required if "JWK Set Endpoint URI" is used.

Set a URI that starts with https. The URI needs to point to a JWK set containing at least one sign key for JWT introspection responses.

Resource server information

Below is information about your resource server that your authorization server needs to pass to Authlete at runtime after authenticating it.
Property
Description
resource server URI

Required. The URI of the resource server making the introspection request.
JWS alg algorithm
Optional. The JWS alg algorithm for signing the introspection response. This parameter corresponds to introspection_signed_response_alg defined in "6. Client Metadata" of "JWT Response for OAuth Token Introspection". 

The default value is RS256.
JWE alg algorithm
Optional. The JWE alg algorithm for encrypting the introspection response. This parameter corresponds to introspection_encrypted_response_alg defined in "6. Client Metadata" of "JWT Response for OAuth Token Introspection". 

If the this property is specified, Authlete generates a JWT introspection response encrypted with the algorithm specified by this property and the algorithm specified by the JWE enc algorithm.
JWE enc algorithm
Optional. The JWE enc algorithm for encrypting the introspection response. This parameter corresponds to introspection_encrypted_response_enc defined in "6. Client Metadata" of "JWT Response for OAuth Token Introspection". 

The default is A128CBC_HS256.

API call test

In this section, we simulate API calls that the authorization server sends to Authlete on access token introspection.

Suppose the resource server sends an introspection request to the authorization server, requesting a JWT introspection response. The request would look as follows.

POST /introspect HTTP/1.1
Host: as.example.com
Authorization: Basic cnMwOnJzMC1zZWNyZXQ=
Accept: application/token-introspection+jwt
Content-Type: application/x-www-form-urlencoded

token=NfCAjOqr8De1p6Lq6Xiq3c___FASYbyDmo6nb0bL_W8

After receiving the introspection request, the authorization server must authenticate the resource server somehow and get the resource server's information. Here, we also assume that the authorization server has successfully authenticated the resource server and obtained "https://rs.example.com" as the resource server URI and  "ES256" as the JWS alg algorithm for introspection responses.

Then, the authorization server sends a request to Authlete "/auth/introspection/standard" API including the resource server's information. The following curl command is an example of an API call to Authlete "/auth/introspection/standard" API.
NOTE: We also need to send the value of the HTTP Accept Header in the original introspection request.

curl -v -X POST http://localhost:4430/api/3528497207/auth/introspection/standard \
-H "Authorization: Bearer WXHkoQCYic2zYQdeQDvHfyLy5SZ6i69x0SKTRv4svTg" \
-H "Content-Type:application/json" \
-d '{ "parameters": "token=NfCAjOqr8De1p6Lq6Xiq3c___FASYbyDmo6nb0bL_W8", "httpAcceptHeader": "application/token-introspection+jwt", "rsUri": "https://rs.example.com", "introspectionSignAlg": "ES256" }'

If the request has been successfully processed at Authlete, the authorization server gets a response as shown below.

{
  "resultCode": "A145001",
  "resultMessage": "[A145001] Introspection was performed successfully (type=access_token, active=true).",
  "action": "JWT",
  "responseContent": "eyJhbGciOiJFUzI1NiIsInR5cCI6InRva2VuLWludHJvc3BlY3Rpb24rand0In0.eyJpc3MiOiJodHRwczovL2F1dGhsZXRlLmNvbSIsImF1ZCI6Imh0dHBzOi8vcnMuZXhhbXBsZS5jb20iLCJpYXQiOjE3MDAxMjgzMTYsInRva2VuX2ludHJvc3BlY3Rpb24iOiJ7XCJhY3RpdmVcIjp0cnVlLFwic2NvcGVcIjpcImVtYWlsXCIsXCJjbGllbnRfaWRcIjpcIjM2Mzk1NzE4NjNcIixcInRva2VuX3R5cGVcIjpcIkJlYXJlclwiLFwiZXhwXCI6MTcwMTEyODI5NixcInN1YlwiOlwiam9oblwiLFwiYXVkXCI6W1wiaHR0cHM6Ly9ycy5leGFtcGxlLmNvbVwiXSxcImlzc1wiOlwiaHR0cHM6Ly9hdXRobGV0ZS5jb21cIn0ifQ.l_BZfoqEQsX3CSC2OOpdIt1vOUT5vcZb9kTL2H6EW9latqqtrNi9ZjiXZ7-Jbfsdv388el9oFAPszKfFMMR9LQ"
}

The "responseContent" property in the response contains a JWT, which is to be returned to the resource server as an introspection response. The payload of the JWT is as follows.

{
  "iss": "https://authlete.com",
  "aud": "https://rs.example.com",
  "iat": 1700128316,
  "token_introspection": "{\"active\":true,\"scope\":\"email\",\"client_id\":\"3639571863\",\"token_type\":\"Bearer\",\"exp\":1701128296,\"sub\":\"john\",\"aud\":[\"https://rs.example.com\"],\"iss\":\"https://authlete.com\"}"
}
How did we do with this article?