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) issuer and signing configuration in the Configuring auth token management 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:
{
"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 Backend sites can use the JWKS (JSON Web Key Set) endpoint that PingAccess engines provide at |
Steps
-
Click Access and then go to Identity Mappings → Identity Mappings.
-
Click Add Identity Mapping.
-
In the Name field, enter a name for the mapping.
-
In the Type list, select JWT Identity Mapping.
-
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.
-
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 asUser-Agent
, notHTTP_USER_AGENT
. -
In the Audience field, enter the audience to be set as the
aud
claim in the signed JWT in the Audience field. -
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.
-
If you selected an inclusion list, configure the inclusion list:
-
In the User Attribute Name field, enter or select the name of the attribute to retrieve from the user web session, such as
sub
. -
In the JWT Claim Name field, enter the name of the JWT claim to contain the attribute value.
-
Select which included attribute is used as the Subject.
-
-
If you selected an exclusion list, configure the exclusion list:
-
Enter the names of the attributes to exclude.
-
Select which included attribute is used as the Subject.
-
-
Optional: In the Client Certificate Chain JWT Claim Name field, enter the name of the JWT claim to contain the client certificate chain array.
-
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.
-
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.
-
Click Save.