PingAccess

Creating JWT identity mappings

To make user attributes available in a signed JSON Web Token (JWT) 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.

About this task

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:

{
  "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.
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 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 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 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 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 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 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.