> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Header Claims in ID Tokens

> Adding custom claims to ID tokens by configuring Authlete to include them in the JWS header available in version 2.2 and later.

## 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](/api-reference/authorization-endpoint/issue-authorization-response)
* [/backchannel/authentication/complete](/api-reference/ciba/complete-backchannel-authentication)
* [/device/complete](/api-reference/device-flow/complete-device-authorization)

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.

| Key        | Value        |
| ---------- | ------------ |
| typ        | JWT          |
| extra\_key | extra\_value |

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-reference/authorization-endpoint/process-authorization-request) API and receives a response including a value of "ticket" to be used in the next step. (details omitted)
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-reference/authorization-endpoint/issue-authorization-response)
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-reference/token-endpoint/process-token-request)
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"
}
```