Authentication APIs Overview


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.

API Model

Authorization server

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:

  • authorize

    Queries PingOne (or an external resource owner) to get an authorization grant.

  • resume

    Continues the processing of an authorization request after the completion of an authentication flow.

  • userinfo

    Returns claims about the authenticated user resource.

  • token

    Obtains an access token by presenting its authorization grant or a refresh token.

  • jwks

    The JSON Web Key (jwks) is a JSON representation of the cryptographic key.

  • .well-known/openid-configuration

    The discovery endpoint, used in multi-tenant configurations to support multiple issuers per host.

  • signoff

    The end session endpoint called by the flow orchestration service to initiate the logout flow.

Note: For more information, see Authorization server service and Activity - Application authorization and authentication.

Flows

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.

Note: For more information, see Flow orchestration service, Activity - Using PingOne authentication flows, and Activity - Configure a custom authentication user interface.

Sessions

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.

Note: For more information, see Sessions service.

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

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"

Note: For more information about access tokens and scopes, see Activity - Configure access to PingOne services using scopes.

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 authentication code that is exchanged for an access token.

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.

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.

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.

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.

Note: The 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 TOKEN.

API endpoints

The PingOne Authentication API includes the following public endpoints:

  • auth.pingone.com

    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_credentials request to the authorization server to acquire an access token: https://auth.pingone.com/as/token.