PingOne Platform APIs

SAML 2.0

The SAML endpoints are used by SAML applications to initiate sign-on and signoff operations. The SAML service implements functions to initiate SAML 2.0 single sign-on and single logout authentication flows.

Workflows

SAML 2.0 protocol

The SAML protocol allows 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.

SAML SSO authentication requests

A SAML SSO 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>
[source]

SAML AuthnRequest data model

The following data model describes the supported attributes for a SAML <AuthnRequest> request. In the sample requests presented in this section, we include a SAMLRequest query parameter to pass in the encoded SAML <AuthnRequest> information. For additional details, refer to Security Assertion Markup Language (SAML) V2.0 Technical Overview.

Property Type Required? Mutable? Description

id

String

Required

Read only

The value of the ID attribute in the request. The InResponseTo attribute in the corresponding response must match this value.

version

Number

Required

Mutable

The value should be set to 2.0.

IssueInstant

Date

Required

Read only

The time (in UTC) that the request was issued.

destination

String

Required

Mutable

A URI reference indicating the address to which this request has been sent. It is required if the <AuthnRequest> request is signed, optional otherwise. If submitted, it should match the location at which the message was received.

consent

String

Optional

Mutable

A string that specifies whether or not (and under what conditions) consent has been obtained from a principal in the sending of this request.

ForceAuthn

Boolean

Optional

Mutable

A boolean that when set to true specifies that the identity provider must authenticate the presenter directly rather than rely on a previous security context. If a value is not provided, the default value is false.

IsPassive

Boolean

Optional

Mutable

A boolean that when set to true specifies that the identity provider and the user agent itself must not visibly take control of the user interface from the requester and interact with the presenter in a noticeable fashion. If a value is not provided, the default value is false.

AssertionConsumerServiceIndex

String

Optional

Mutable

This value specifies the location to which the <Response> message should be returned to the requester. It applies only to profiles in which the requester is different from the presenter. If omitted, then the identity provider must return the <Response> message to the default location associated with the requester for the profile of use.

AssertionConsumerServiceURL

String

Optional

Mutable

This value specifies the location to which the <Response> message must be returned to the requester. This attribute is mutually exclusive with the AssertionConsumerServiceIndex attribute and is typically accompanied by the ProtocolBinding attribute.

ProtocolBinding

String

Optional

Mutable

A URI reference that identifies a SAML protocol binding used when returning the <Response> message. This attribute is mutually exclusive with the AssertionConsumerServiceIndex attribute and is typically accompanied by the AssertionConsumerServiceURL attribute.

ProviderName

String

Optional

Mutable

This value specifies the human-readable name of the requester. It is used only for logging purposes, if available and if needed.

<saml:Issuer>

String

Required

Mutable

This value specifies the service provider (9)SP) Entity ID. It identifies the entity that generated the request message. This should be treated as the client_id.

<ds:Signature>

Object

Optional

Mutable

An XML Signature that authenticates the requester and provides message integrity.

<RequestedAuthnContext>

Object

Optional

Mutable

A value that specifies the requirements, if any, that the requester places on the authentication context that applies to the responding provider’s authentication of the presenter.

<saml:Subject>

Object

Optional

Mutable

A value that specifies the requested subject that names the actual identity about which it wishes to receive an assertion.

<NameIDPolicy>

Object

Optional

Mutable

A value that specifies the constraints on the name identifier to be used to represent the requested subject.

<saml:Conditions>

Object

Optional

Mutable

A value that specifies the SAML conditions the requester expects to limit the validity and/or use of the resulting assertion (or assertions).

<Scoping>

Object

Optional

Mutable

A value that specifies a set of identity providers trusted by the requester to authenticate the presenter, as well as limitations and context related to proxying of the <AuthnRequest> message to subsequent identity providers by the responder.

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>

IdP-Initiated SSO

IdP-initiated SSO allows users to authenticate through their identity provider, which then issues and signs SAML assertions to service providers. This allows users to access multiple applications and services with a single authentication.

IdP-Initiated SSO uses the following flow:

  1. A user signs on to their IdP system. This can be with a username and password, or other method determined by the authentication policy. The user is then presented with an application catalog that displays the web-based applications and services they can access.

  2. The user clicks an icon to access one of those applications or services.

  3. The IdP creates and signs an SAML assertion that includes information about the user’s identity, along with any other attribute information that the IdP and SP agreed to share to authenticate users.

  4. The IdP either sends the assertion to the SP through a browser or sends a reference to the assertion that the SP can use to securely retrieve the assertion.

  5. The SP validates the signature to ensure that the SAML assertion really came from its trusted IdP and that none of the values in the assertion have been modified. It also extracts the identity, attribute, and authorization information it needs to determine whether access should be granted and which privileges the user will have.

  6. Users access the application or service.

IdP-Initiated SSO has the following benefits:

  • The user gains access to catalog of applications and services with a single authentication.

  • The authentication flow is more secure because user credentials are never transmitted between IdP and SP.

  • The authentication flow is simpler because it eliminates a redirect step from SP to IdP.

You can start the IdP-Initiated SSO authentication session using the Get Identity Provider Initiated SSO request.

SAML SLO logout requests

A SAML single logout (SLO) operation uses the following flow:

  1. The user initiates logout.

  2. The session participant initiates single logout by sending a <LogoutRequest> message to the identity provider that sent the corresponding <AuthnRequest> authentication assertion.

  3. The SAML service validates the request. It then calls the end session endpoint of the flow orchestration service and passes through the cookie header. The flow orchestration service deletes the session identified by the session cookie and includes a Set-Cookie in the response to immediately expire the session cookie.

  4. The identity provider uses the contents of the <LogoutRequest> message to determine the session(s) being terminated.

  5. The identity provider issues a <LogoutResponse> message to the original requesting session participant.

DaVinci flows with SAML applications

The following workflow outlines the interaction between PingOne applications and DaVinci flows and flow policies.

  1. PingOne applications support a configuration option to assign DaVinci flow policies to the application. For information on designating a DaVinci flow as a PingOne flow, refer to PingOne Initiated Flows.

  2. The SAML SSO service retrieves the application configuration data. Based on the configuration, the application can use either a PingOne sign-on policy or a DaVinci flow policy to determine the sign-on workflow. To assign DaVinci flow policies to applications, refer to Application Flow Policy Assignments.

  3. For DaVinci flow policy use cases, the DaVinci widget renders the sign-on flow page. For more information about DaVinci widgets, refer to Launching a flow with the widget in the PingOne admin documentation.

  4. The DaVinci widget manages the flow, and after the flow completes, the PingOne SSO Connector creates a session and passes control back to the protocol service.

  5. The SAML SSO service processes the response, performs attribute mapping using user attributes from the PingOne directory, creates a SAMLResponse, and sends it to the SAML application.

  6. The application continues its normal flow, calling the PingOne token endpoint to obtain the tokens.

To get information about the DaVinci flow policies available for assignment to an application, refer to Flow Policies.

Application access control conditions

You can configure SAML applications for access control by setting the accessControl properties on the application. For more information about accessControl properties, refer to Application Operations. When accessControl properties are set for an application, the user must meet the requirements specified by these application properties. If the user attempts to authenticate, then the application’s accessControl conditions are evaluated before creating an assertion.

An assertion is created if the user meets the the application’s access control conditions. If the conditions are not met, then an authorization failed error is returned with the top level code urn:oasis:names:tc:SAML:2.0:status:Responder and the second level code urn:oasis:names:tc:SAML:2.0:status:RequestDenied. If access is denied, a USER.ACCESS_DENIED event is published; otherwise, a USER.ACCESS_ALLOWED event is published.

For more information, refer to Control access to applications through roles and groups.

SAML events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Code Message

200

Successful operation.

201

Successfully created.

400

The request could not be completed. .

401

You weren’t authenticated to perform this operation.

404

The requested resource was not found.