--- title: Creating JWT identity mappings description: To make user attributes available in a signed JSON Web Token (JWT) sent to the application using a header, create a JWT identity mapping. component: pingaccess version: 9.0 page_id: pingaccess:pingaccess_user_interface_reference_guide:pa_creating_jwt_identity_mappings canonical_url: https://docs.pingidentity.com/pingaccess/9.0/pingaccess_user_interface_reference_guide/pa_creating_jwt_identity_mappings.html revdate: April 7, 2025 section_ids: before-you-begin: Before you begin about-this-task: About this task steps: Steps --- # Creating JWT identity mappings To make user attributes available in a signed JSON Web Token (JWT) *(tooltip: \
\

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 \RFC 7519\.\

\
)* sent to the application using a header, create a JWT identity mapping. ## Before you begin Define the JWT issuer and signing configuration in [Configuring auth token management](pa_configuring_auth_token_management.html). ## About this task > **Collapse: Configuring JWT identity mappings** > > When configuring identity mappings, PingAccess supports dot notation to maintain session token structure. 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 | > > | | | > | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | | Backend sites can use the JWKS (JSON Web Key Set) endpoint available at `/pa/authtoken/JWKS` to validate the JWT signature. Learn more about the endpoint in [OpenID Connect endpoints](../reference_guides/pa_oidc_endpoints.html). | > **Collapse: Configuring custom JWT claim values** > > Custom claim values can be: > > * Claims obtained from the user identity > > * Dot expressions > > * Literal values such as a string, boolean, integer, or array > > | | | > | - | ---------------------------------------------------------------------------------------------------------------------- | > | | Use a literal value when you don't expect an identity mapping to be present for the user, such as for anonymous users. | > > To define multiple values for a claim, separate the values with a dot. For example, `value1.value2`. > > To separate multiple dot expressions, you must use a `/` character to escape any subsequent values. For example, `pi/.pa/.rat`. ## Steps 1. Click **Access**, then go to **Identity Mappings > Identity Mappings**. 2. Click **[icon: plus, set=fa]Add Identity Mapping**. 3. In the **Name** field, enter a unique name for the mapping. 4. In the **Type** list, select **JSON Web Token (JWT)**. 5. To map the identity JWT as a bearer token in the Authorization request header, select **Map as Bearer Token**. If you select this option, the JWT token replaces any existing tokens and the **Header Name** field isn't usable in this identity mapping configuration. 6. In the **Header Name** field, enter the name of the header you want to use when sending the signed JWT to the target application. Configure the actual header name over the HTTP protocol, and don't use an environment variable interpreted format. For example, if you're using the `User-Agent` header to identify browser types, enter it as `User-Agent`, not `HTTP_USER_AGENT`. 7. In the **Audience** field, enter the audience you want to set as the `aud` claim in the signed JWT. 8. In the **JWT Claim Mapping** section, select a list type: * Inclusion List Uses only the attributes you specify. * Exclusion List Uses all attributes except for the ones you specify. 9. If you selected **Inclusion List**, configure a **JWT Claim Mapping**: 1. Click **[icon: plus, set=fa]Add Row**. 2. In the **User Attribute Name** field, enter or select the name of the attribute to retrieve from the user web session, such as `sub_jwk`. 3. In the **JWT Claim Name** field, enter the name of the JWT claim to contain the attribute value. 4. Click **[icon: plus, set=fa]Add Row** and repeat as necessary. 5. Select which included attribute to use as the **Subject**. 10. If you selected **Exclusion List**: 1. In the **Excluded Attributes** field, enter the names of any attributes that you don't want to collect from the user web session. 2. In the **Subject Attribute Name** field, enter or select the name of an included attribute you want to use 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. 1. If you are performing Certificate to JWT Claim Mapping, in the **Client Certificate Chain Max Depth** field, enter the maximum number of certificates from the client certificate chain included in the JWT claim array. 12. To configure advanced settings, click **Show Advanced**. 1. (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. 2. In the **Custom JWT Claims** section, configure any custom claims you want to add to the JWT token: 1. Click **[icon: plus, set=fa]Add Row**. 2. In the **Name** field, enter the name of the JWT claim to contain the attribute value. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you configure a custom JWT claim with a claim name that you've already used in the inclusion or exclusion list, the following applies:- Custom claims don't override attributes in the **Exclusion List**. - If a claim in the **Inclusion List** results in a null value, PingAccess uses the custom value instead. - If the **Inclusion List** overrides the custom value, PingAccess logs a debug message indicating that the custom value wasn't used. | 3. In the **Value** field, enter the name of the attribute you want to retrieve from the user web session. 4. Click **[icon: plus, set=fa]Add Row** and repeat as necessary. 3. To create a JWT containing only the custom claims defined in step 12b when identity information is unavailable, select **Create JWT for Anonymous Users**. This checkbox enables you to use JWT identity mapping to send context that might not require a user identity. 4. In the **Type Header Value** field, enter a value to use as the `typ` header in the JWT, indicating what type of JWT it is. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To comply with [IETF RFC 9068 - JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens](https://datatracker.ietf.org/doc/rfc9068/) when using a JWT access token, enter the recommended value of `at+jwt`. If `application/at+jwt` is required, you can use this value instead. | 13. Click **Save**.