Access tokens


Introduction

Access tokens are credential strings that represent authorization to access a protected resource. Client applications obtain access tokens by making OAuth 2 or OpenID Connect requests to an authorization server; resource servers require clients to authenticate using access tokens.

Access tokens are obtained from the token endpoint (when using the client credentials grant type) or from the authorization endpoint (when using the implicit grant type). Access tokens are typically granted on behalf of a specific authenticated user. (Tokens granted directly to applications are called application tokens.)

Clients present access tokens when making requests to a resource server (for example, the PingOne for Customers API endpoints) using bearer token authentication as described by RFC 7650. Here is a sample request using an access token:

curl -X GET "https://api.pingone.com/v1/environments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6InRlc3QifQ.eyJzY29wZSI6IiIsImNsaWVudF9pZCI6ImlkZW50aXR5LWRpcmVjdG9yeS1zeW50aGV0aWMtdGVzdGluZyIsImlzcyI6ImF1dGgtc3RhZ2luZy5waW5nb25lLmNvbSIsImF1ZCI6ImFwaS1zdGFnaW5nLnBpbmdvbmUuY29tIiwiYWNjIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwiZW52aXJvbm1lbnRfaWQiOiIiLCJvcmciOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJvcmdhbml6YXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJlbnYiOiIiLCJleHAiOjE1MzAxMTc1Nzl9.OTGQethw-flgnf0oslpQOmW9YdExf6ZpsqpmRtBTeD5gpKGFmaSeHguFMVpR94GSjb27OEPzCY8qpU_OkoaQGH9FiysdgvFFVNVzHOb80e0MgP47ean1Rtk3lHmIWHg1ihp3Kt7vq9fO0OwekmfshejyaLYLX2g4seWFZKbs7ICIaSufYuGTsLLQFixiK7b0tM-lcjZUmLglPlzdGEYQgg13ZWho02rFVjwRrfOVkQRCLuhkk2Pz2eeblQgWBlzMi_zbHnRhqRnrHyX2PwoPZ9qHh3aqz6yNgGinUwSrE3J1slnx8uPeP88obYcX4QXTXOCf7su2rinbexOsNu4Puw"

Grant types

OAuth 2 and OpenID Connect define the authorization grant types by which a client application obtains an authorization grant in the form of an access token. PingOne supports the following grant types:

Authorization code

This grant type is used by web applications. The authorization request generates an authorization code that is exchanged for an access token. For more information, see Authorization request with a code grant.

Implicit

This grant type is intended for use by mobile applications or client-side web applications with no server-side component. The implicit grant type is for applications that cannot guarantee the confidentiality of the client secret.

In this flow, the client makes a request to the server’s authorization endpoint. If the request contains the id_token response type and the openid scope, then it is considered an authentication (OpenID Connect) request, and an ID token is issued. For more information, see Native and single-page applications.

Client credentials

This grant type is made directly to the token endpoint and is used to request an access token for either:

  • Resources owned by the client rather than any specific end user.
  • Resources belonging to multiple end users.

The client uses HTTP basic authentication with its client ID and client secret to authenticate itself to the token endpoint and must specify a Content-Type of application/x-www-form-urlencoded. For more information, see Obtain an access token.

Refresh token

This grant type is used by applications to exchange a refresh token for an expired access token. It gives applications the ability to acquire a valid access token without additional interaction. For more information, see Obtain an access token.

Response types

The authorization request must specify a response_type attribute, which determines whether an access token, an authorization code, or a JSON Web Token is returned by the authorization server. The following is the list of the OAuth 2.0 response types supported by the PingOne authorization server:

  • code

    Returns an authorization code. If the grant type is authorization_code, the response_type attribute must have the code value. The authorization code returned by the request is exchanged for an access token to complete the authorization flow.

  • token

    Returns an access token. If the grant type is implicit or client_credentials, the response_type attribute can specify the token value to return an access token.

  • id_token

    Returns a JSON Web Token (JWT). If the grant type is implicit, the response_type attribute can specify the id_token value to return a JWT containing a set of claims that represent the authentication state of an end user.

  • id_token (OpenID Connect ID token)

    If the request contains the id_token response type and the openid scope, then it is considered an authentication (OpenID Connect) request, and an ID token is issued. The ID token includes the ID of the user; this request can also include the profile scope to add additional user claims to the ID token.

Access token claims

All access tokens in PingOne are JWTs signed using the RS256 signing algorithm. The following section lists the supported claims for each token type.

Token claims

For access tokens, the JWT header must contain the ID of the signing key as the kid claim.

Claim Description
sub A string that specifies the authenticated user ID. This claim is not present for client_credentials tokens.
client_id A string that specifies the application that requested this token.
aud A string that lists of names of resources that this token is intended for. The resource of an application’s resource access grant is included if one or more scopes from the grant is requested and granted.
scope A string that specifies the space-separated list of scope names associated with this token (in the format described in Section 3.3 of OAuth 2.0 RFC6749.
iss A string that specifies the per-environment issue URI: https://auth.pingidentity.com/<environmentId>/as.
iat An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token was originally issued, as defined in JWT RFC7519.
exp An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token will expire, as defined in JWT RFC7519.
env A string that specifies the environment ID of the authenticated user or application. This claim is not present when the resource’s audience property does not include the PingOne platform API resource.
org A string that specifies the organization ID of the authenticated user or application. This claim is not present when resource’s audience property does not include the PingOne platform API resource.

ID_Token claims

ID tokens are signed with the same key as the access token. The JWT header must contain the ID of the signing key as the kid claim.

Claim Description
sub A string that specifies the authenticated user ID.
aud A string that lists of names of resources that this token is intended for. The resource of an application’s resource access grant is included if one or more scopes from the grant is requested and granted.
iss A string that specifies the per-environment issue URI: https://auth.pingidentity.com/<environmentId>/as.
iat An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token was originally issued, as defined in JWT RFC7519.
exp An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token will expire, as defined in JWT RFC7519.
auth_time A string that specifies the time when the user authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the current date and time.
nonce A string that specifies the value used to associate a client session with an id_token, and to mitigate replay attacks. The value is passed through unmodified from the authentication request to the ID token.

Refresh token claims

Refresh tokens are signed with the same key as the access token. The JWT header must contain the ID of the signing key as the kid claim. The contents of the JWT must to be relied upon as a contract since it is internal only and subject to change. Some fields are included in the JWT, whereas others are persisted.

Claim Description
sub A string that specifies the authenticated user ID.
sid A string that specifies the ID of the session associated with the refresh token.
scope A string that specifies the space-separated list of scope names associated with this token (in the format described in Section 3.3 of OAuth 2.0 RFC6749).
jti A string that specifies the JWT ID of the refresh token (as defined in Section 4.1.7 of the JWT spec), which is rotated whenever the refresh token is exchanged.
auth_time A string that specifies the time at which authentication completed when the original ID token was created. This claim is present only if an ID token was minted.
acr A string that specifies the name of the sign-on policy that was completed when the original authentication was performed. This claim is present only if an ID token was minted.
amr A string array that specifies the methods associated with the authenticators used when the original authentication was performed. This claim is present only if an ID token was minted.

Access token customization

PingOne lets you customize the content of access tokens by adding custom resource attributes and their values to the token. You can use the access token customization APIs to convey additional information about the user to applications. For more information, see Resource attributes.