The PingOne 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.
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.
For more information, see OpenID Connect/OAuth 2 and Application authorization and authentication.
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.
For more information, see Flows and PingOne flow states.
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.
For more information, see SAML 2.0.
OpenID Connect is an authentication protocol that PingOne connected applications can use to authenticate users and get user data through claims. PingOne can also act as an OAuth 2 authorization server to authorize clients to access protected resources using access tokens. For example, PingOne uses OAuth 2 to protect access to PingOne 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.
For more information about access tokens, see Access tokens.
The PingOne 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.
A SAML authorization request uses the following authorization flow:
<AuthnRequest>message to be delivered by the user agent to the SAML service endpoint using either
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.
resumeendpoint of the SAML service.
<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.