Custom header claims in ID tokens

Preface

This article describes on how to configure Authlete to add custom claims to a JWS header of ID tokens.

This feature is available in Authlete version 2.2 and later.

Specifying custom claims

An authorization server can specify a set of custom claims to be included in a header of ID tokens on making requests to the following Authlete APIs. idtHeaderParams is the request parameter to pass the claims in JSON format.

• /auth/authorization/issue
• /backchannel/authentication/complete
• /device/complete

Authlete creates an ID token including the custom claims in its header and sends it back to the authorization server.

Examples

This section shows example instructions on how to create ID tokens that includes custom claims in authorization code flow.

Preparing custom claims

Let’s assume that the following custom claims are to be included in a header of ID tokens.

A JSON formatted value to be specified to an idtHeaderParams parameter would be as follows.

{
    "typ": "JWT",
    "extra_key": "extra_value"
}

Processing an authentication request

A client (OIDC relying party) makes an authentication request that includes scope=openid and response_type=code. The request is sent to an authorization server (OIDC identity provider) via a user agent.

The authorizations server then forwards content of the authentication request to Authlete’s  /auth/authorization API and receives a value of ticket to be used in the next request to Authlete. (details omitted)

The authorization server authenticates an end user and asks consent as needed, and make a request to Authlete’s /auth/authorization/issue API. In this request, the server uses the idtHeaderParams parameter to specify the custom claims.

The following is an example using curl. (folded for readability)

• Request

curl -s -X POST .../auth/authorization/issue
 -u $apiKey:$apiSecret
 -H 'Content-type: application/json'
 -d '{"subject":"...",
      "ticket": "...",
      "idtHeaderParams":
        "{\"typ\":\"JWT\",
          \"extra_key\":\"extra_value\"}"
     }'

• Response

{
    "type": "authorizationIssueResponse",
    "resultCode": "A040001",
    "resultMessage": "[A040001] The authorization request was processed successfully.",
    "accessTokenDuration": 0,
    "accessTokenExpiresAt": 0,
    "action": "LOCATION",
    "authorizationCode": "eOEh...3eSc",
    "responseContent": "https://...?code=eOEh...3eSc"
}

On receiving the response above, the authorizations server sends back an authorization code (eOEh…3eSc) to the client via the user agent (Web browser).

Processing a token request

On receiving the authorization code, the client sends a token request including the code to the authorization server. The server forwards content of the token request to Authlete’s   /auth/token API and receives a token response.

The following is an example using curl. (folded for readability)

• Request

curl -s -X POST .../auth/token \
     -u $apiKey:$apiSecret \
     -H 'Content-type: application/json' \
     -d '{"clientId":"...",
          "clientSecret":"...",
          "parameters":
            "redirect_uri=https://...
            &grant_type=authorization_code
            &code=eOEh...3eSc"}'

• Response

{
  "type": "tokenResponse",
  "resultCode": "A050001",
  "resultMessage":
    "[A050001] The token request (grant_type=authorization_code) was
     processed successfully.",
  "accessToken": "9Myh...sYMs",
  "action": "OK",
  "grantType": "AUTHORIZATION_CODE",
  "idToken":
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImV4dHJ
     hX2tleSI6ImV4dHJhX3ZhbHVlIn0.
     eyJzdWIiOiJ0ZXN0dXNlcjAxIiwiYXVkIjpbIjI4MzA
     0NTE3OTYwODU5NDAiXSwiaXNzIjoiaHR0cHM6Ly9hcy
     5leGFtcGxlLmNvbSIsImV4cCI6MTU5OTcyNjA0MCwia
     WF0IjoxNTk5NjM5NjQwfQ.
     -jo-A-SXjP4JlBSc24vKkO6FVf3MQJ6eN-XzPAraiZ4",
  "refreshToken": "SlEl...cWoY",
  "responseContent":
    "{\"access_token\":\"9Myh...sYMs\",
      \"refresh_token\":\"lEl...cWoY\",
      \"scope\":\"openid\",
      \"id_token\":
        \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImV4dHJ
          hX2tleSI6ImV4dHJhX3ZhbHVlIn0.
          eyJzdWIiOiJ0ZXN0dXNlcjAxIiwiYXVkIjpbIjI4MzA
          0NTE3OTYwODU5NDAiXSwiaXNzIjoiaHR0cHM6Ly9hcy
          5leGFtcGxlLmNvbSIsImV4cCI6MTU5OTcyNjA0MCwia
          WF0IjoxNTk5NjM5NjQwfQ.
          -jo-A-SXjP4JlBSc24vKkO6FVf3MQJ6eN-XzPAraiZ4\",
      \"token_type\":\"Bearer\",
      \"expires_in\":86400}",
  "scopes": [
    "openid"
  ],
  ...
}

Authlete has added the custom claims in a JWS header of the ID token (eyJh…aiZ4) in this response. You can find them by decoding the header part as follows.

{
    "alg": "HS256",
    "typ": "JWT",
    "extra_key": "extra_value"

}