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.

In the authorization and authentication API sample requests shown in this document, the {{authPath}} variable in the sample requests represents the regional domain for the PingOne authorization and authentication server. This variable stands for https://auth.pingone.com for the North America region, https://auth.pingone.ca for the Canada region, https://auth.pingone.eu for the European Union region, and https://auth.pingone.asia for the Asia-Pacific region.

The PingOne Authentication API includes the following entities.

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.

• 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.

For more information, see OpenID Connect/OAuth 2 and 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 making calls to specific actions required by the authentication workflow.

For more information, see Flows and PingOne flow states.

SAML 2.0

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.

OAuth 2 and OpenID Connect

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.

SAML 2.0 protocol

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:

• spEntityId

  A string that specifies the service provider’s entity ID.

• acsUrls

  A string that specifies the assertion consumer service URLs.

• assertionDuration

  An integer that specifies the maximum amount of time that an assertion is valid.

• sloEndpoint

  A string that specifies the SAML single logout endpoint URL.

• sloResponseEndpoint

  A string that specifies the SAML single logout response URL. This property is optional.

SAML authentication requests

A SAML authentication request uses the following authentication flow:

1. The client (browser) initiates a login action to access a protected resource.
2. The identity provider issues an <AuthnRequest> message to be delivered by the user agent to the SAML service endpoint using either HTTP Redirect or HTTP POST.
3. The SAML service validates the request and creates an authentication flow with the flow orchestration service.
4. The SAML service indicates user interaction is required to perform the authentication flow.
5. The browser is redirected to the PingOne hosted authentication UI or the per application configured URL of a custom UI, passing in the environmentId and flowSessionId query 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.
6. The browser is redirected to the resume endpoint of the SAML service.
7. The SAML service retrieves and deletes the authentication flow from the flow orchestration service.
8. The SAML service generates the appropriate tokens and issues a <Response> message delivered by the user agent to the identity provider using HTTP POST.

The following is a sample SAML assertion generated for an authentication <AuthnRequest> request:

<samlp:AuthnRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="identifier_1"
    Version="2.0"
    IssueInstant="2004-12-05T09:21:59">
    <saml:Issuer>https://sp.example.com/SAML2</saml:Issuer>
  </samlp:AuthnRequest>

The following is a sample SAML assertion response:

<samlp:Response
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="identifier_2"
    InResponseTo="identifier_1"
    Version="2.0"
    IssueInstant="2004-12-05T09:22:05"
    Destination="https://sp.example.com/SAML2/SSO/POST">
    <saml:Issuer>https://auth.pingone.com/{envId}</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"
      ID="identifier_4"
      Version="2.0"
      IssueInstant="2004-12-05T09:22:05">
      <saml:Issuer>https://auth.pingone.com/{envId}</saml:Issuer>
      <!-- a POSTed assertion MUST be signed -->
      <ds:Signature
        xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature>
      <saml:Subject>
        <saml:NameID
          Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
          3f7b3dcf-1674-4ecd-92c8-1544f346baf8
        </saml:NameID>
        <saml:SubjectConfirmation
          Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
          <saml:SubjectConfirmationData
            InResponseTo="identifier_1"
            Recipient="https://sp.example.com/SAML2/SSO/POST"
            NotOnOrAfter="2004-12-05T09:27:05"/>
        </saml:SubjectConfirmation>
      </saml:Subject>
      <saml:Conditions
        NotBefore="2004-12-05T09:17:05"
        NotOnOrAfter="2004-12-05T09:27:05">
        <saml:AudienceRestriction>
          <saml:Audience>https://sp.example.com/SAML2</saml:Audience>
        </saml:AudienceRestriction>
      </saml:Conditions>
      <saml:AuthnStatement
        AuthnInstant="2004-12-05T09:22:00"
        SessionIndex="identifier_3">
        <saml:AuthnContext>
          <saml:AuthnContextClassRef>
            urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
         </saml:AuthnContextClassRef>
        </saml:AuthnContext>
      </saml:AuthnStatement>
    </saml:Assertion>
  </samlp:Response>

For more information about the SAML service, and for details about the single logout flow, see SAML 2.0.