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.

JWT Response for OAuth Token Introspection feature has been available since Authlete 3.0.

Introduction

Below is a diagram that roughly illustrates 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.eyJpc3MiOiJodHRwczovL2F1dGhsZXRlLmNvbSIsImF1ZCI6Imh0dHBzOi8vcnMuZXhhbXBsZS5jb20iLCJpYXQiOjE3MDAxMjgzMTYsInRva2Vu_X2ludHJvc3BlY3Rpb24iOiJ7XCJhY3RpdmVcIjp0cnVlLFwic2NvcGVcIjpcImVtYWlsXCIsXCJjbGllbnRfaWRcIjpcIjM2Mzk1NzE4NjNcIixcInRva2Vu_X3R5cGVcIjpcIkJlYXJlclwiLFwiZXhwXCI6MTcwMTEyODI5NixcInN1YlwiOlwiam9oblwiLFwiYXVkXCI6W1wiaHR0cHM6Ly9ycy5leGFtcGxlLmNvbVwiXSxcImlzc1wiOlwiaHR0cHM6Ly9hdXRobGV0ZS5jb21cIn0ifQ.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\"}"
}