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.
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.
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:
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.
A SAML authentication request uses the following authentication flow:
<AuthnRequest>
message to be delivered by the user agent to the SAML service endpoint using either HTTP Redirect
or HTTP POST
.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.resume
endpoint of the SAML service.<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.