Token resource lookup methods work by taking the access token subject, which is usually a string identifier such as a GUID or username, and using that subject value to perform a search in a data store or API providing user data. For this reason, the data store or API must be accessible to PingDataGovernance Server; and in most cases, it should be the same data store or API used by the authorization server that issues the access tokens.

Note:

Using a token resource lookup method is optional. If your policies do not need user profile information, you do not need to configure token resource lookup methods.

PingDataGovernance Server provides the following types of token resource lookup methods:

SCIM token resource lookup methods

SCIM token resource lookup methods use PingDataGovernance Server's SCIM subsystem to retrieve a token subject's attributes.

Note:

Before you create a SCIM token resource lookup method, you must configure SCIM. See SCIM configuration basics.

To configure a SCIM token resource lookup method, you need to know the name of the access token claim that the authorization server uses for the subject identifier (typically, sub). You also need to know which user attribute is used as the subject identifier by the authorization server when it issues access token. If you have configured a mapping SCIM resource type, then the attribute name used by the authorization server and the attribute name in your SCIM schema might differ.

A SCIM token resource lookup method retrieves the token subject's attributes using the combination of the scim-resource-type and match-filter configuration properties.

Property Description
scim-resource-type The SCIM resource type that represents users that can be access token subjects.
match-filter A SCIM 2 filter expression that matches a SCIM resource based on one or more access token claims.

The match-filter value must be a valid SCIM 2 filter expression that uniquely matches a single resource. The filter expression can include one or more variables that refer to claims found in the access token. These variables are indicated by enclosing a token claim name in percent (%) characters. When the token resource lookup method is invoked, the variable is filled in with the actual value from the access token claim.

For example, if a match filter has the value id eq "%sub%" and an access token contains a sub claim with the value 8ac3d8b5-4f17-33fa-a4b4-854599ed9a89, then the token resource lookup method will perform a SCIM search using the filter id eq "8ac3d8b5-4f17-33fa-a4b4-854599ed9a89".

The following example shows how to create a SCIM token resource lookup method using dsconfig. It assumes that a SCIM resource type called Users and an access token validator called JWT Access Token Validator already exist.

dsconfig create-token-resource-lookup-method
  --validator-name "JWT Access Token Validator" \
  --method-name "User by uid" \
  --type scim \
  --set evaluation-order-index:10 \
  --set scim-resource-type:Users \
  --set 'match-filter:uid eq "%sub%"'

Third-party token resource lookup methods

A third-party token resource lookup method is a custom implementation of a token resource lookup method that you write using the Server SDK. A third-party token resource lookup method can be useful for PingDataGovernance Server deployments where SCIM is not otherwise needed. For example, you could use a third-party token resource lookup method to connect a PingDataGovernance Server to a system that stores user data in a cloud directory.

For more information about writing custom server extensions, see the Server SDK documentation.