Access token validators can use token resource lookup methods to search a datastore and retrieve the subject's profile data for use in policy decisions.
Most access tokens include a subject, which identifies the user who granted access to the
application using the token. Token resource lookup methods use the access token subject
value, which is usually a string identifier such as a GUID or username, to perform a
search in an external datastore, such as a PingDirectory
Server or an API providing user data. For this reason, the datastore or API must be
accessible to PingAuthorize Server; and in most
cases, it should be the same datastore or API used by the authorization server that
issues the access tokens. After the lookup completes, the token subject's user
attributes get passed into the policy request's
allowing policies to make decisions based on some aspect of the user.
Using a token resource lookup method is optional. If your policies don't need user profile information, you don't need to configure token resource lookup methods.
PingAuthorize Server provides the following types of token resource lookup methods:
SCIM token resource lookup methods
System for Cross-domain Identity Management (SCIM) token resource lookup methods use PingAuthorize Server's SCIM subsystem to retrieve a token subject's attributes.
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
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
A SCIM token resource lookup method retrieves the token subject's attributes using
the combination of the
match-filter configuration properties.
The SCIM resource type that represents users that can be access token subjects.
A SCIM 2 filter expression that matches a SCIM resource based on one or more access token claims.
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 performs a SCIM search using the filter
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
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 PingAuthorize Server deployments where SCIM is not otherwise needed. For example, you could use a third-party token resource lookup method to connect a PingAuthorize 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.