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.

Use Cases

• Test a SAML application connection

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>

Request model

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 system with a username and password and is presented with an application catalog that displays icons representing 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 about creating DaVinci flows and flow policies, see Getting Started with DaVinci. For information on designating a DaVinci flow as a PingOne flow, see Setting a trigger type on the flow.

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, see 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, see 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.

SAML data model {#saml-data-model}

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, see 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, see Control access to applications through roles and groups.

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Response codes