OpenID Connect/OAuth 2


OpenID Connect/OAuth 2 protocol

PingOne for Customers integrates with applications that use standards-compliant protocols by taking on the role of an OpenID Connect provider and OAuth 2 authorization server. In this capacity, PingOne provides the framework for connected applications to access protected HTTP resources. For more information about OpenID Connect and OAuth 2, see the OpenID Connect 1.0 spec and the OAuth 2.0 Authorization Framework RFC6749.

The PingOne authorization endpoint /{environmentId}/as/authorize is used to interact with the resource owner and obtain an authorization grant.

OpenID Connect/OAuth 2 API endpoints

The OpenID Connect/OAuth 2 endpoints support the following operations:

For hands-on experience with the OpenID Connect/OAuth 2 API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You weren’t authenticated to perform this operation.
403 You do not have permissions or are not licensed to make this request.
404 The requested resource was not found.

Endpoint examples

Authorization request with a code grant

The authorization endpoint is used to interact with the end user and obtain an authorization grant. The following sample shows the GET /{environmentId}/as/authorize operation. The request URL includes the response_type parameter with a value of code, which designates that this authorization request, if successful, returns an authorization code that is exchanged for an access token.

https://auth.pingone.com/{environmentID}/as/authorize?response_type=code&client_id={appID}&redirect_uri=https://example.com&scope=openid%20profile%20email&acr_values=Single_Factor&prompt=login'/example.com&scope=p1:read:user&acr_values=Single_Factor&prompt=login'

Supported parameters for an authorization request are:

Property Description
acr_values A string that designates whether the authentication request includes steps for a single-factor or multi-factor authentication flow. The value specified must be the name of a sign-on policy for which the application has a sign-on policy assignment. This is a required property.
client_id A string that specifies the application’s UUID.
max_age A string that specifies the maximum amount of time allowed since the user last authenticated. If the max_age value is exceeded, the user must re-authenticate.
nonce A string that is 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.
prompt A string that specifies whether the user is prompted to login for re-authentication. The prompt parameter can be used as a way to check for existing authentication, verifying that the user is still present for the current session. For prompt=none, the user is never prompted to login to re-authenticate, which can result in an error if authentication is required. For prompt=login, if time since last login is greater than the max-age, then the current session is stashed away in the flow state and treated in the flow as if there was no previous existing session. When the flow completes, if the flow’s user is the same as the user from the stashed away session, the stashed away session is updated with the new flow data and persisted (preserving the existing session ID). If the flow’s user is not the same as the user from the stashed away session, the stashed away session is deleted (logout) and the new session is persisted.
redirect_uri A string that specifies the URL that specifies the return entry point of the application. This is a required property.
response_type A string that specifies the code or token type returned by an authorization request. Options are token, id_token, and code. This is a required property.
scope A string that specifies permissions that determine the resources that the application can access. This parameter is not required, but it is needed to specify accessible resources.
state A string that specifies an optional parameter that is used to maintain state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri query parameter.

Note: The acr_values parameter values are sign-on policy names and should be listed in order of preference. Only scopes from one resource access grant can be minted in an access token (except for scopes for the OpenID Connect platform resource).

Authorization request using POST

The authorization endpoint is used in a POST request. The POST request accepts all the same parameters as the GET request. Both initiate an authorization request. Note that for the POST request, parameters and their values are Form Serialized by adding the parameter names and values to the entity body of the HTTP request and specifying the Content-Type: application/x-www-form-urlencoded request header.

The following sample shows the POST /{environmentId}/as/authorize operation. The request includes a response_type parameter with a value of token, which designates that this authorization request, if successful, returns an access token.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/as/authorize' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'response_type=token&client_id={appID}&redirect_uri=https://example.com&scope=openid profile p1:read:user'

Obtain an access token

The token endpoint is used by the client to obtain an access token by presenting its authorization grant. Note that authentication requirements to this endpoint are configured by the application’s tokenEndpointAuthMethod property. For authorization_code and client_credentials grants, the application calls the POST /{environmentId}/as/token endpoint to acquire the access token.

For an authorization_code grant type, the request looks like this:

curl -X POST \
  'https://auth.pingone.com/{environmentId}/as/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code={authCode}&redirect_uri=https://example.com'

For a client_credentials grant type, the request looks like this:

curl -X POST \
  'https://auth.pingone.com/{environmentId}/as/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id={applicationID}&client_secret={secret}'

Supported parameters for the token request are:

Property Description
client_id A string that specifies the application’s UUID.
client_secret A string that specifies the the application’s client secret. This property is required only if the application’s tokenEndpointAuthMethod property is set to CLIENT_SECRET_POST.
code A string that specifies the authorization code returned by the authorization server. This property is required only if the grant_type is set to authorization_code.
grant_type A string that specifies the grant type of the token request. Options are authorization_code, implicit, and client_credentials.
redirect_uri A string that specifies the URL used as the return entry point of the application. This is a required property only if the grant_type is set to authorization_code.

UserInfo endpoint

The UserInfo Endpoint is an OAuth 2.0 protected resource that returns claims about the authenticated end user. Note that the /{environmentId}/as/userinfo request takes an access token in the Authorization header to get the claims about the user.

curl -X GET \
  'https://auth.pingone.com/{environmentId}/as/userinfo' \
  -H 'Authorization: Bearer token'

You can also use the POST /{environmentId}/as/userinfo operation to obtain a userinfo authorization grant. The following sample shows the request:

curl -X POST \
  'https://auth.pingone.com/{environmentId}/as/userinfo' \
  -H 'Authorization: Bearer token'

Userinfo authorization requests

A userinfo authorization request is used with applications associated with the openid resource. This type of request takes an access token in the Authorization header to get the claims about the user.

The value for the Authorization header is the bearer token returned by the following authorization request:

https://auth.pingone.com/{environmentId}/as/authorize?client_id={applicationId}&redirect_uri=https://example.com&response_type=token&scope=openid profile email address&acr_values=Single_Factor

In the authorization request, the scope attribute must specify the openid value, which includes the sub claim (the user ID) in the response data. Additional OpenID Connect scopes such as profile, address, phone and email can also be included to add more user claims to the response.

The response data for a request that includes the openid, profile, email, and address scopes looks like this:

{
    "family_name": "Doe",
    "address": {
        "country": "US",
        "postal_code": "78750",
        "region": "TX",
        "locality": "Austin",
        "street_address": "123 Happy Street"
    },
    "given_name": "John",
    "email": "jdoe@example.com",
    "preferred_username": "jdoe",
    "updated_at": 1535377850,
    "name": "John Doe",
    "middle_name": "J",
    "sub": "0986b513-ae1f-4312-8d8d-a31eb79133ad"
}

Grants and scopes with userinfo

The access token used with the /{environmentId}/as/userinfo endpoint must be generated by an implicit or authorization_code grant type. In addition, the authorization request used to generate the access token must include the openid scope. The authorization request can also include any other OpenID Connect scopes (as shown in the sample above) to return additional user claims. PingOne user scopes such as p1:reset:userPassword are not applicable to userinfo authorization requests and applications associated with the openid resource.

Note: Access tokens generated from a client_credentials grant type return an ACCESS_FAILED message when used with the /{environmentId}/as/userinfo endpoint. Tokens from a client_credentials grant use administrator permissions granted through role assignments.

Get jwks

The GET /{environmentId}/as/jwks endpoint returns the JSON Web Key Set [JWK] document. This document contains the signing keys that can be used to validate JWT signatures.

curl -X GET \
  'https://auth.pingone.com/{environmentId}/as/jwks'

The response data looks like this:

{
    "keys": [
        {
            "kty": "RSA",
            "e": "AQAB",
            "use": "sig",
            "x5t": "Za6ddv8nZnWoqvY6z61fiP8QwEo",
            "kid": "default",
            "x5c": [
                "MIIDLDCCAhSgAwIBAgIGAWW17v5GMA0GCSqG..."
            ],
            "n": "jgQ8twHSmSlT28I7iTi4-IsA3jgfhGPx0pIC27LTDf0..."
        }
    ]
}

The following parameters are shown for each key associated with the specified environment:

  • kty

    The is the key type, which identifies the cryptographic algorithm family used with the key. Options are RSA.

  • e

    This is the RSA public exponent parameter, which is used in the RSA Key blinding operation.

  • kid

    This is the key ID parameter, which is used to match a corresponding kid key value in the JWT token to validate the requestor and grant access to the specified API endpoint.

  • use

    This is the public key use parameter, which identifies the intended use of the public key. Options are sig (signature) and enc (encryption).

  • n

    This is the RSA modulus parameter, which is used in the RSA Key blinding operation.

  • x5t

    This is an X.509 certificate SHA-1 thumbprint parameter, which is a base64url-encoded SHA-1 thumbprint of the DER encoding of an X.509 certificate.

  • x5c

    This is an X.509 certificate chain parameter, which is a chain of one or more PKIX certificates.

Get signoff

The GET /{environmentId}/as/signoff endpoint is called to initiate end user logout. The Cookie request header specifies the current session token.

curl -X GET \
  'https://auth.pingone.com/{environmentID}/as/signoff?id_token_hint={idToken}' \
  -H 'Cookie: ST=<sessionToken>'

The request URL includes the id_token_hint parameter, which is a required attribute that specifies the ID token passed to the logout endpoint as a hint about the user’s current authenticated session.

Supported parameters for the signoff request are:

Property Description
id_token_hint A string that specifies the previously issued ID token, which is used to indicate the identity of the user, which is passed to the logout endpoint as a hint about the user’s current authenticated session with the client.
post_logout_redirect_uri A string that specifies an optional parameter that specifies the URL to which the browser is redirected after a logout has been performed.
state A string that specifies an optional parameter that is used to maintain state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri query parameter.

The signature of ID token provided in the id_token_hint attribute must be verified. The application identified by the ID token must exist and must not be disabled. The user identified by the ID token must be the user identified by the current session.

If a post_logout_redirect_uri parameter is provided and it does not match one of the postLogoutRedirectUri values of any application in the specified environment, this condition is handled as an un-redirectable error.

Obtain OpenID provider configuration information

The following sample shows the discovery endpoint, GET /{environmentID}/as/.well-known/openid-configuration, which returns the OpenID Connect provider metadata document for the issuer, https://auth.pingone.com.

curl -X GET \
  'https://auth.pingone.com/{environmentID}/as/.well-known/openid-configuration' \
  -H 'Content-Type: application/json'

The response is a set of claims about the OpenID provider’s configuration, including all necessary endpoints and public key location information.

{
    "issuer": "https://auth.pingone.com/e3493291-6c8c-491d-beb5-dfa098f48c5a/as",
    "authorization_endpoint": "https://auth.pingone.com/e3493291-6c8c-491d-beb5-dfa098f48c5a/as/authorize",
    "token_endpoint": "https://auth.pingone.com/e3493291-6c8c-491d-beb5-dfa098f48c5a/as/token",
    "userinfo_endpoint": "https://auth.pingone.com/e3493291-6c8c-491d-beb5-dfa098f48c5a/as/userinfo",
    "jwks_uri": "https://auth.pingone.com/e3493291-6c8c-491d-beb5-dfa098f48c5a/as/jwks",
    "end_session_endpoint": "https://auth.pingone.com/e3493291-6c8c-491d-beb5-dfa098f48c5a/as/signoff",
    "scopes_supported": [
        "openid",
        "profile",
        "email",
        "address",
        "phone"
    ],
    "response_types_supported": [
        "code",
        "id_token",
        "token id_token"
    ],
    "response_modes_supported": [
        "fragment",
        "query"
    ],
    "grant_types_supported": [
        "authorization_code",
        "implicit",
        "client_credentials"
    ],
    "subject_types_supported": [
        "public"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256"
    ],
    "userinfo_signing_alg_values_supported": [
        "none"
    ],
    "request_object_signing_alg_values_supported": [
        "none"
    ],
    "token_endpoint_auth_methods_supported": [
        "client_secret_basic",
        "client_secret_post"
    ],
    "claim_types_supported": [
        "normal"
    ],
    "claims_supported": [
        "sub",
        "iss",
        "auth_time",
        "acr",
        "name",
        "given_name",
        "family_name",
        "middle_name",
        "preferred_username",
        "profile",
        "picture",
        "zoneinfo",
        "phone_number",
        "updated_at",
        "address",
        "email",
        "locale"
    ],
    "claims_parameter_supported": false,
    "request_parameter_supported": false,
    "request_uri_parameter_supported": false
}