SAML 2.0


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.

SAML API operations

The SAML endpoints support the following operations:

SAML data model

Property Description
acsUrls A string that specifies the Assertion Consumer Service URLs. The first URL in the list is used as default (there must be at least one URL). This is a required property.
assertionDuration An integer that specifies the assertion validity duration in seconds. This is a required property.
description A string that provides a description of the resource.
enabled A boolean that specifies whether the application is enabled. The default is FALSE if this value is not set.
icon.id A string that specifies the icon resource’s unique identifier.
icon.href A string that specifies the URL to the icon resource.
id A string that specifies the resource’s unique identifier.
loginPageUrl A string that specifies the URL of the authentication flow UI that this application uses to interact with the end-user through the authentication flow. If a URL is not specified, the default PingOne hosted UI is used.
name A string that specifies the name of SAML attribute and should be unique within an environment. Note that saml_subject is a reserved case-insensitive name that indicates the mapping to be used for the subject in the assertion. This is a required property.
protocol A string that specifies the protocol used by the application. This value determines the set of additional protocol specific properties, links, and embedded resources associated with the resource. Options are OPENID_CONNECT and SAML.
sloEndpoint A string that specifies the logout endpoint URL. This is a required property.
sloResponseEndpoint A string that specifies the endpoint URL to submit the logout response. If a value is not provided, the sloEndpoint property value is used to submit SLO response.
spEntityId A string that specifies the service provider entity ID used to lookup the application. This is a required property and is unique within the environment.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
400 The request was invalid.
401 You weren’t authenticated to perform this operation.
404 The specified object doesn’t exist.

Endpoint examples

Get SAML metadata

You can use the GET /{environmentId}/saml20/metadata/{applicationId} operation to retrieve SAML metadata for the application specified by its ID in the request URL.

curl -X GET \
  'https://auth.pingone.com/{environmentId}/saml20/metadata/{applicationId}'

The response data looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor entityID="https://auth.pingone.com/261bad1e-364b-405b-8d5d-96e915e3cb83" ID="DUp57Bcq-y4RtkrRLyYj2fYxtqR" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
    <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>
                        MIIDgTCCAmmgAwIBAgIGAWd/ROmGMA0GCSqGSIb3DQEBCwUAMIGFMUYwRAYDVQQD
                        DD1EZWZhdWx0LVRlc3QgRW52aXJvbm1lbnQgMmIxZmZjODAtMjg1Zi00NTEwLWEw
                        MGEtNjdkYjVjZjM4YmNhMRYwFAYDVQQLDA1QaW5nIElkZW50aXR5MRYwFAYDVQQK
                        DA1QaW5nIElkZW50aXR5MQswCQYDVQQGEwJVUzAeFw0xODEyMDUxNjQ4MDFaFw0x
                        OTEyMDUxNjQ4MDFaMH0xPjA8BgNVBAMMNVRlc3QgRW52aXJvbm1lbnQgMmIxZmZj
                        ODAtMjg1Zi00NTEwLWEwMGEtNjdkYjVjZjM4YmNhMRYwFAYDVQQLDA1QaW5nIElk
                        ZW50aXR5MRYwFAYDVQQKDA1QaW5nIElkZW50aXR5MQswCQYDVQQGEwJVUzCCASIw
                        DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKJNhgUw5szr8UHoHlvPxcWJ7ifk
                        FSrM0TAAmF4q8DWIjIluq3knYT5obM9/fbJyf4awBNh06biHAeH2giPINtHc1vSD
                        XC39VYaGx4eemkWJ7yX5n3at2M+blPO83tBRI0IrAVyLhvVln9KJmcv5e7Ov8GHV
                        5UlJOU8doX2eAJG9Hj+h917JV+E+Lhda89rLOFx3Mm8gYu1coUdquPK6l8H953Qx
                        CCzHBf3/JOocEqb84wXHHVE4BTloukNBF/i5jWC8yzpGw8e891Bw34OxODbO2jQV
                        u0L/wfOqSUsGcUAm1j9M22VcIkclTHioVU0ATwvyszazpx5SsuK/ZPUteqcCAwEA
                        ATANBgkqhkiG9w0BAQsFAAOCAQEAP8HQi0GqpZgY3J7PXHbHKGCK8qbZiY/x8ImV
                        snB95iwh3kngg/BIj8je1euU3iztxOS/ljWGKh5RCQJ71K22ixSiGqwolQo5cBp5
                        cGfyl5jpuKS01NRrxJ9RARfBZvqjAFJqEx6+/B5shwY5m/Z+fmKBkFV1Zku6vDGA
                        1D6Iv13CyV0AoheR1eYT+71skBYYxChnxLXOuaCyvPGBzS7IQM3P9eoNQBDB9k26
                        l0MunmjyuzSO220YHPRY0FuC5EHCjZ/2FB50Eg/FxCyUyM2rwUCnmr3OJfDtGvlV
                        VLhVsarzjEp/LGDxf39Zd5OV6j4HcP6CRxzNd8MIXU5Iwt7flw==
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:SingleLogoutService Location="https://auth.pingone.com/261bad1e-364b-405b-8d5d-96e915e3cb83/saml20/idp/slo" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
        <md:SingleLogoutService Location="https://auth.pingone.com/261bad1e-364b-405b-8d5d-96e915e3cb83/saml20/idp/slo" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
        <md:SingleSignOnService Location="https://auth.pingone.com/261bad1e-364b-405b-8d5d-96e915e3cb83/saml20/idp/sso" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
        <md:SingleSignOnService Location="https://auth.pingone.com/261bad1e-364b-405b-8d5d-96e915e3cb83/saml20/idp/sso" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.account.secondsUntilUnlock" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.account.warnings" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.accountId" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.address.countryCode" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.address.locality" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.address.postalCode" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.address.region" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.address.streetAddress" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.createdAt" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.email" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.enabled" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.externalId" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.id" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.lifecycle.status" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.locale" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.mfaEnabled" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.mobilePhone" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.name.family" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.name.formatted" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.name.given" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.name.honorificPrefix" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.name.honorificSuffix" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.name.middle" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.nickname" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.photo.href" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.preferredLanguage" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.primaryPhone" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.timezone" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.title" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.type" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.updatedAt" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="user.username" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"/>
    </md:IDPSSODescriptor>
</md:EntityDescriptor>

SAML SSO using GET

For information about the authorization flow for a SAML authorization request, see SAML authorization requests.

The GET /{environmentId}/saml20/idp/sso operation initiates the SAML single sign-on action through a GET request. In the request URL, the SAMLRequest parameter contains the encoded SAML authorization request information.

curl -X GET \
  'https://auth.pingone.com/{environmentId}/saml20/idp/sso?SAMLRequest=<AuthnRequest>'

SAML SSO using POST

You can also initiate the authentication session the SAML single sign-on action through a POST request. The following sample shows the POST /{environmentId}/saml20/idp/sso operation to start the sign-on flow:

curl -X POST \
  'https://auth.pingone.com/{environmentId}/saml20/idp/sso?SAMLRequest=<AuthnRequest>' \
  -H "Content-type: application/json"

The request URL includes the SAMLRequest parameter to pass in the encoded SAML authorization request information.

SAML SLO using GET

A SAML single logout 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.

The GET /{environmentId}/saml20/idp/slo operation initiates the SAML single logout action through a GET request. In the request URL, the SAMLRequest parameter contains the encoded SAML logout request information.

curl -X GET \
  'https://auth.pingone.com/{environmentId}/saml20/idp/slo?SAMLRequest=<LogoutRequest>'

SAML SLO using POST

You can also initiate the authentication session the SAML single logout action through a POST request. The following sample shows the POST /{environmentId}/saml20/idp/sso operation to start the logout flow:

curl -X POST \
  'https://auth.pingone.com/{environmentId}/saml20/idp/sso?SAMLRequest=<LogoutRequest>' \
  -H "Content-type: application/json"

The request URL includes the SAMLRequest parameter to pass in the encoded SAML logout request information.