PingAuthorize

Access token validators

Access token validators verify the tokens that client applications submit when they request access to protected resource.

Specifically, access token validators translate an access token into a data structure that constitutes part of the input for policy processing.

To authenticate to PingAuthorize Server’s HTTP services, clients use OAuth 2 bearer token authentication to present an access token in the HTTP Authorization request header:

"Authorization": "Bearer  <access-token>"

PingAuthorize does not support the use of query parameters for token validation.

To process the incoming access tokens, PingAuthorize Server uses access token validators, which determine whether to accept an access token and translate it into a set of properties, called claims.

Most access tokens identify a user, also called the token owner, as its subject (SAML). Access token validators can retrieve the token owner’s attributes from the datastore using a related component called a token resource lookup method. The user data obtained by a token resource lookup method is sent to the policy decision point (PDP) so that policies can determine whether to authorize the request.

For more information about the types of access tokens PingAuthorize can validate, see Access token validator types.

For information about validating a JSON Web Token (JWT) in policy instead of using a validator, see Conditions.

About access token validator processing

Each access token validator possesses an evaluation order index, an integer that determines its processing priority. Lower values are processed before higher values.

The following image shows the validation process when using an access token validator with the System for Cross-domain Identity Management (SCIM) token resource lookup method.

Diagram of the access token validation flow for a SCIM lookup between , the authorization server, and the directory server

  1. If an inbound HTTP request contains an access token, PingAuthorize sends the token to the access token validator with the lowest evaluation order index.

  2. The access token validator validates the access token.

    Validation logic varies by access token validator type, but the validator generally verifies the following information:

    • A trusted source issued the token.

    • The token is not expired.

      If the token is valid, its active flag is set to true. The flag and other access token claims are added to the HttpRequest.AccessToken attribute of the policy request.

  3. If the access token contains a subject, the access token validator sets the user_token flag to true and uses a token resource lookup method to fetch the token owner through SCIM.

    A token resource lookup defines a SCIM filter that locates the token owner. If the lookup succeeds, the resulting SCIM object is added to the policy request as the TokenOwner attribute.

    For deployments that don’t use SCIM, token owner attributes can be retrieved from other user store types by writing a token resource lookup method extension with the Server SDK. For more information, see User profile availability in policies.

  4. If the access token validator is unable to validate the access token, it passes the token to the access token validator with the next lowest evaluation order index, and the previous two steps are repeated.

  5. HTTP request processing continues, and the policy request is sent to the PDP.

  6. Policies inspect the HttpRequest.AccessToken and TokenOwner attributes to make access control decisions.

Access tokens issued using the OAuth 2 client credentials grant type are issued directly to a client and do not contain a subject. An access token validator always sets the HttpRequest.AccessToken.user_token flag to false for such tokens, which are called application tokens, in contrast to tokens with subjects, which are called user tokens. Because authorization policies often grant a broad level of access for application tokens, you should configure such policies to always check the HttpRequest.AccessToken.user_token flag.

Access token validators determine whether PingAuthorize Server accepts an access token and uses it to provide key information for access-control decisions, but they are neither the sole nor the primary means of managing access. The responsibility for request authorization falls upon the PDP and its policies. This approach allows an organization to tailor access-control logic to its specific needs.