Managing Identity Matchers

Using Virtual Data Sources in the Runtime Request

Using Virtual Data Sources in the Runtime request provides a versatile and efficient way to handle Identity Attributes. This allows users to have more granular control over their Identities by determining which Identity Template, User ID, and Identity Attributes to use for the Authorization request.

Identity Matchers

Identity Matchers are key components for determining the Identity Template based on a defined virtual source, like a JWT claim or Header property. They allow for fine-tuned control over Template assignment and matching.

The Identity Template Matcher uses a flexible JSONPath syntax for Identity Template matching, which allows you to determine which one is used for the Authorization decision calculation based on a received JWT or header. Similarly, the Identity ID Mapper is employed to map a source claim or header property value to be used as the Identity ID for Authorization calculation. Check out the detailed valid JSONPath Structures and Examples section for more information.

A common use case would be to use an Identity Token received from an IDP, where the issuer can be used with the Identity Template Matcher by matching the iss claim value and the token subject, sub claim value to be used as the source of the User ID.

To ensure an effective Identity Template verification, it is crucial to maintain uniqueness in the defined matcher source and value. This helps avoid ambiguity and ensures accurate identification of the identity Template. Ensure that you have matched the JSONPath to the Matcher Value to validate against the Identity Template. The Template is used only if the match is valid. If you do not have a Scope set up yet, see the guide on how to set one up here.

To set up an Identity Matcher:

1. In the Identity Workspace, click on the Settings icon.
2. Click on the Details tile.
3. On the top-right of the Details screen, click Edit to modify the relevant fields.
4. Click Save.

Note: This Mapper is currently defined in the UserID attribute JSONPath in the Identity Attributes screen.

JSONPath for Identity Attributes

The Identity Attribute Mapper is utilized to map Attributes within the JWT or header to corresponding Identity Attributes. It plays a role in aligning incoming data with the Identity Template structure.

Each Identity Attribute possesses the capability to utilize JSONPath, a language designed for searching paths within JSON structures. This feature allows users to specify a JSONPath to navigate to a particular property within a JSON document, essentially providing the address of the desired property.

Users can utilize JSONPath to define attributes sources within the Authorization header JWT, any other header JWT, or any other general header. This flexibility is used to extract and define attributes from JSON structures, such as JWTs or headers, to be utilized within the Identity resolution and Authorization processes. It supports more flexible options for Attribute extraction, providing greater customization and adaptability. Check out the detailed valid JSONPath Structures and Examples section for more information.

It's important to note that the default behavior for Identity Attributes is retained. If an Identity Attribute is included as part of the request, it takes precedence over the JSONPath Mapper. If a JSONPath mapper is not defined and the value is not located, the Attribute will be retrieved from an external source.

Note: There is no precedence for Identity Template and ID matching and mapping. In a Request Flow, the PDP will expect to receive values in the request body, while in a Matcher Flow, the PDP expects to match a valid template and Identity ID based on the matchers and mappers.

To set a JSONPath:

1. In the Identity Workspace, click on the Settings icon.
2. Click on the Identity Attributes tile.
3. In the sidebar, click on Identity Attributes to set a JSONPath.
4. Select the relevant Identity Attribute.
5. On the top-right, click Edit.
6. Input the Identity ID Mapper in the JSONPath field.
7. Click Save.

JWT Validation

It is possible to perform JWT validation to ensure the integrity and authenticity of the tokens in the request. Ensure that the signature, expiration, and additional optional claims are valid to prevent invalid JWTs.

The JWT validation is optional for the Identity Template matching and for Identity Attributes mapping. Each can be toggled based on the customer’s preference in accordance to their organization’s guidelines, the reliability of the JWT issuer, and their security preferences. Be aware that JWT validation can slightly increase overall performance due to the validation process.

To perform JWT Validation:

1. In the Identity Workspace, click on the Settings icon.
2. In the Identity Template Settings, enable the relevant JWT Validation toggles.
3. Click Save.

It is important to note that in case if the same JWT is used for different matchers/mappers, validation will take place only once. That is also the case when the Authorization JWT is used both for PDP Authentication and for Template matching and/or Attribute value extraction.

Enabling JWT validations toggles requires users to set up JWT validation settings in the Identity Workspace Settings, which contains the Identity Template Matcher, Identity ID Mapper, and all other Identity Attributes Mappers. Users can set up multiple validation setting blocks in the event where different JWKs need to be set up.

To modify the JWT Validation Settings:

1. In the Identity Workspace, click on the Settings icon.
2. Enable one or both toggles.
3. Click JWT Settings.
4. Input a JWKs URL. This URL is exposed by your IDP or other JWT Issuer, which will be used to fetch keys for the JWT signature validation.
5. Input a Key Refresh Interval (1-24 hours).
6. Input a Validation Claim Key and Value (optional). This field can always be updated. This is used as an extra validation step by checking for a Claim Key in your Authorization JWT and match its value.

Note: The Validation Claim Key and Value are verified after the JWKs URL and JWT expiration are validated first. Any value could be used as a claim value if you only wish to validate the existence of the claim regardless of its value.

JSONPath Structure and Examples

$.request.headers.Authorization.JWT.iss // Fetches the issuer claim from Authorization JWT 

$.request.headers.x-user.JWT.user.type // Fetches the type claim under the user from a JWT sent through an x-user header

$.request.headers.Authorization.JWT.sub // Fetches the subject claim from Authorization JWT 

$.request.headers.x-identity.JWT.uid // Fetches the uid claim from x-identity JWT

$.request.headers.x-user-type // Fetches the value of x-user-type header 

$.request.headers.x-user.type // Fetches the value of type property of the x-user header

$.request.headers.x-user.type // Fetches the value of type property of the x-user header

$.request.headers.x-user.type // Fetches the value of type property of the x-user header