What is the PingOne for Customers Authentication API?
The PingOne for Customers Authentication API provides services to configure and run authentication workflows. An authentication workflow can be configured to include local authentication actions (login), multi-factor authentication actions, and other external actions. The Authentication API includes the flow orchestration and action services needed to configure an authentication workflow.
PingOne Authentication API model
The PingOne Authentication API includes the following entities.
The PingOne authorization server (
as) service configures the authorization grants that are used to authenticate users and provide access to resources. This service includes the following entities:
Queries PingOne (or an external resource owner) to get an authorization grant.
Continues the processing of an authorization request after the completion of an authentication flow.
Returns claims about the authenticated user resource.
Obtains an access token by presenting its authorization grant or a refresh token.
The JSON Web Key (jwks) is a JSON representation of the cryptographic key.
The discovery endpoint, used in multi-tenant configurations to support multiple issuers per host.
The end session endpoint called by the flow orchestration service to initiate the logout flow.
The PingOne flow orchestration service configures the steps required to authenticate the application or user that initiated the authentication request. The service is responsible for initiating the authentication session and includes the step service, which calls specific actions required by the authentication workflow.
For authentication requests, the flow orchestration service calls the session service to create a new session. The session token is associated with the current session and is set in a cookie. For every call in the authentication flow, the authentication service checks that the session token cookie contains the current token for the session.
OAuth 2 and OpenID Connect services
The PingOne for Customers Authentication API supports OAuth 2 and OpenID Connect services, which authorize clients for data access and allow clients to obtain a user’s authentication state.
The OAuth 2 framework defines several methods by which a client can obtain authorization to access protected resources using an access token. The access token represents authorization granted to the client for a set of scopes. Scopes are string identifiers understood by both the authorization server and the resource server to represent the specific boundaries of access. The client can use the access token as a credential for accessing data on a resource server.
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, and 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"
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:
This grant type is used by web applications. The authorization request generates an authentication code that is exchanged for an access token.
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.
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.
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
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:
Returns an authorization code. If the grant type is
response_typeattribute must have the
CODEvalue. The authorization code returned by the request is exchanged for an access token to complete the authorization flow.
Returns an access token. If the grant type is
response_typeattribute can specify the
TOKENvalue to return an access token.
Returns a JSON Web Token (JWT). If the grant type is
response_typeattribute can specify the
ID_TOKENvalue to return a JWT containing a set of claims that represent the authentication state of an end user.
tokenEndpointAuthMethod attribute must not be set to a value of
NONE for a
client_credentials grant type. Also, the
offline_access scope is valid only for the
refresh_token grant type. When configuring an internal client (as shown in the example above), the grant type must be
client_credentials, and the
response_type must have a value of
The PingOne Authentication API includes the following public endpoints:
This is the authentication endpoint called to request the bearer token for authenticating PingOne API requests. For example, the following URL identifies the endpoint to submit a
client_credentialsrequest to the authorization server to acquire an access token: