---
title: Creating JWT identity mappings
description: To make user attributes available in a signed JSON web token (JWT) sent to the application in a header, create a JWT identity mapping.
component: pingaccess
version: 8.1
page_id: pingaccess:pingaccess_user_interface_reference_guide:pa_creating_jwt_identity_mappings
canonical_url: https://docs.pingidentity.com/pingaccess/9.1/pingaccess_user_interface_reference_guide/pa_creating_jwt_identity_mappings.html
llms_txt: https://docs.pingidentity.com/pingaccess/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: July 22, 2024
superseded_by: https://docs.pingidentity.com/pingaccess/9.1/pingaccess_user_interface_reference_guide/pa_creating_jwt_identity_mappings.html
section_ids:
  about-this-task: About this task
  steps: Steps
---

# Creating JWT identity mappings

To make user attributes available in a signed JSON web token (JWT) sent to the application in a header, create a JWT identity mapping.

## About this task

Define the JSON Web Token (JWT) *(tooltip: \<div class="paragraph">
\<p>An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \<a href="https\://datatracker.ietf.org/doc/html/rfc7519">RFC 7519\</a>.\</p>
\</div>)* issuer and signing configuration in the [Configuring auth token management](pa_configuring_auth_token_management.html) procedure.

When configuring identity mappings, the dot notation is supported so that session token structure can be maintained. For example, if the session token contains the following entry:

```json
{
  "address": {
     "line1": "123 Any St",
     "line2": "Apt 123",
     "city": "Anytown",
     "state": "CO",
     "zip": "12345"
   }
}
```

You can define an identity mapping using the entries in the following table to maintain the structure of the target JWT.

| User attribute name | JWT claim name |
| ------------------- | -------------- |
| address.line1       | address.line1  |
| address.line2       | address.line2  |
| address.city        | address.city   |
| address.state       | address.state  |
| address.zip         | address.zip    |

|   |                                                                                                                                                                                                                                                                                                         |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | PingAccess engines provide a JWKS (JSON Web Key Set) endpoint at `/pa/authtoken/JWKS` that backend sites can use to validate the signature of the JWT.Backend sites can use the JWKS (JSON Web Key Set) endpoint that PingAccess engines provide at `/pa/authtoken/JWKS` to validate the JWT signature. |

## Steps

1. Click **Access** and then go to **Identity Mappings > Identity Mappings**.

2. Click **[icon: plus, set=fa]Add Identity Mapping**.

3. In the **Name** field, enter a name for the mapping.

4. In the **Type** list, select **JWT Identity Mapping**.

5. Select **Map as Bearer Token** to map the identity JWT as a bearer token in the Authorization request header field.

   This token replaces any existing Authorization request header field. The **Header Name** field is disabled if this option is selected.

6. In the **Header Name** field, enter the name of the header to use when sending the signed JWT to the target application.

   The HTTP header you specify here is the actual header name over the HTTP protocol, not an environment variable interpreted format. For example, enter the `User-Agent` browser type identifying header as `User-Agent`, not `HTTP_USER_AGENT`.

7. In the **Audience** field, enter the audience to be set as the `aud` claim in the signed JWT in the **Audience** field.

8. In the **Attributes** section, select a list type.

   An inclusion list includes only the specified attributes, and an exclusion list includes all attributes not specified.

9. If you selected an inclusion list, configure the inclusion list:

   1. In the **User Attribute Name** field, enter or select the name of the attribute to retrieve from the user web session, such as `sub`.

   2. In the **JWT Claim Name** field, enter the name of the JWT claim to contain the attribute value.

   3. Select which included attribute is used as the **Subject**.

10. If you selected an exclusion list, configure the exclusion list:

    1. Enter the names of the attributes to exclude.

    2. Select which included attribute is used as the **Subject**.

11. **Optional:** In the **Client Certificate Chain JWT Claim Name** field, enter the name of the JWT claim to contain the client certificate chain array.

12. If you are performing Certificate to JWT Claim Mapping, in the **Client Certificate Max Depth** field, specify the maximum number of certificates from the client certificate chain included in the JWT claim array.

13. **Optional:** To use a cached signed JWT for repeated requests for a given user, click **Show Advanced** and select **Cache JWT**.

    If user attributes change or the key used to sign the JWT changes, a new JWT will be created even if JWT caching is enabled.

14. Click **Save**.