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.
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 making calls to specific actions required by the authentication workflow.
The SAML service provides support for the SAML protocol to authorize clients and allow clients to obtain a requestor’s authentication state. The SAML service implements functions to initiate SAML 2.0 single sign-on and single logout authentication flows.
OAuth 2 and OpenID Connect
OpenID Connect is an authentication protocol that PingOne for Customers connected applications can use to authenticate users and get user data through claims. PingOne for Customers can also act as an OAuth 2 authorization server to authorize clients to access protected resources using access tokens. For example, PingOne for Customers uses OAuth 2 to protect access to PingOne for Customers management APIs.
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"
Note: For more information about access tokens and scopes, see Access services.
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 authorization 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 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
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.
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.
id_token(OpenID Connect ID token)
If the request contains the
id_tokenresponse type and the
openidscope, 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
profilescope to add additional user claims to the ID token.
tokenEndpointAuthMethod attribute must not be set to a value of
none for a
client_credentials 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
SAML 2.0 protocol
The PingOne for Customers Authentication API also supports the SAML protocol to authorize clients for data access and allow clients to obtain a requestor’s authentication state. SAML 2.0 uses security tokens, which contain assertions about the requestor, to pass authentication and authorization information about the requestor between the identity provider and the resource provider.
Application connections configured in PingOne that use the SAML protocol must define the following SAML settings in the application connection request:
A string that specifies the service provider’s entity ID.
A string that specifies the assertion consumer service URLs.
An integer that specifies the maximum amount of time that an assertion is valid.
A string that specifies the SAML single logout endpoint URL.
A string that specifies the SAML single logout response URL. This property is optional.
SAML authorization requests
A SAML authorization request uses the following authorization flow:
- The client (browser) initiates a login action to access a protected resource.
- The identity provider issues an
<AuthnRequest>message to be delivered by the user agent to the SAML service endpoint using either
- The SAML service validates the request and creates an authentication flow with the flow orchestration service. The flow orchestration service creates a new session and assigns a session token that is set in the cookie in the next step. The newly created flow is associated with this session.
- The SAML service indicates user interaction is required to perform the authentication flow.
- The browser is redirected to the PingOne hosted authentication UI or the per application configured URL of a custom UI, passing in the
flowSessionIdquery parameters. The authentication UI uses flow orchestration and action services endpoints to complete the authentication flow. The authentication API checks on every call to ensure that the session token cookie contains the current token for the session associated with the flow. On successful completion of the flow, a new session token is generated for the session and set in the cookie.
- The browser is redirected to the
resumeendpoint of the SAML service.
- The SAML service retrieves and deletes the authentication flow from the flow orchestration service.
- The SAML service generates the appropriate tokens and issues a
<Response>message delivered by the user agent to the identity provider using
The following is a sample SAML assertion generated for an authorization
<urn:AuthnRequest ID="hf783f3849f3fh3f34fh8h" IssueInstant="2018-10-12T12:10:14.921-07:00" Version="2.0" xmlns:urn="urn:oasis:names:tc:SAML:2.0:protocol"> <urn1:Issuer xmlns:urn1="urn:oasis:names:tc:SAML:2.0:assertion">ServiceProvider_7d0a3bfe-3298-47e3-ba42-4a88653b5f5c</urn1:Issuer> </urn:AuthnRequest>
The following is a sample SAML authorization assertion response:
<samlp:Response Destination="https://sp.com/acs" ID="id-628d6ecf-bd0b-4be4-89eb-4979c5d49d28" InResponseTo="hf783f3849f3fh3f34fh8h" IssueInstant="2018-10-22T17:16:19.972Z" Version="2.0" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"> <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">https://auth.pingone.com/912588d4-0d58-4cff-8e3b-cf9b7325b9f7</saml:Issuer> <samlp:Status> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> </samlp:Status> <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"> <saml:Subject> <saml:NameID>50ba0cd5-8403-4eff-b030-1a80cfea9c75</saml:NameID> <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:1.0:cm:bearer"> <saml:SubjectConfirmationData InResponseTo="hf783f3849f3fh3f34fh8h" NotOnOrAfter="2018-10-22T17:31:19.877Z" Recipient="https://sp.com/acs"/> </saml:SubjectConfirmation> </saml:Subject> <saml:Conditions NotOnOrAfter="2018-10-22T18:56:20.049Z"> <saml:AudienceRestriction> <saml:Audience>ServiceProvider_7d0a3bfe-3298-47e3-ba42-4a88653b5f5c</saml:Audience> </saml:AudienceRestriction> </saml:Conditions> <saml:AuthnStatement AuthnInstant="2018-10-22T17:16:19.854Z" SessionIndex="c578e632-c61e-461c-96cb-fdf90d630657" SessionNotOnOrAfter="2018-10-22T17:31:19.877Z"> <saml:AuthnContext> <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef> </saml:AuthnContext> </saml:AuthnStatement> <saml:AttributeStatement> <saml:Attribute Name="saml_subject" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">50ba0cd5-8403-4eff-b030-1a80cfea9c75</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="username" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">samluser</saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> </saml:Assertion> </samlp:Response>
For more information about the SAML service, and for details about the single logout flow, see SAML 2.0.