Overview


What is the PingOne for Customers Authentication API?

The PingOne for Customers Authentication API provides services to configure and execute authentication workflows. An authentication workflow may be configured to include local authentication actions (login), multi-factor authentication actions, and other external actions. The Authentication API includes the flow orchestration and the action (step) services needed to configure an authentication workflow for accessing PingOne services.

PingOne Authentication API model

The PingOne Authentication API includes the following entities.

API Model

Flows (authentication flow orchestration)

The PingOne for Customers Authentication API uses flows to configure the steps required to authorize the application or user who initiated the authentication request. It is also responsible for initiating the authentication session.

Steps

A step in the flow orchestration service is a specific action executed in the authentication process flow.

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 may 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 may use the access token as a credential for accessing data on a resource server.

Access tokens

Access tokens are credential strings representing 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 them.

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 application tokens.)

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

curl -X GET "https://api.pingone.com/v1/environments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer eyJraWQi..."

Grant types

OAuth 2 and OpenID Connect define the grant types, which are request flows by which a client application obtains an authorization grant in the form of an access token.

Implicit grant type

This authorization flow 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.

Client credentials grant type

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. The following parameters are provided in the body of the request using form-urlencoding.

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 required to authenticate PingOne API requests. For example, the following URL identifies the endpoint to submit a client_credentials or an implicit request to the authentication service to acquire an access token: https://auth.pingone.com/as/token.oauth2.