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.

Resource server information

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

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\"}"
}