PingAccess

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 /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 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.