Advanced Identity Cloud

SAML2 Authentication node

The SAML2 Authentication node integrates SAML 2.0 single sign-on into an authentication flow.

Use this node when deploying SAML 2.0 SSO in integrated mode (SP-initiated SSO only). This node doesn’t support single logout (SLO).

Implement the Write Federation Information node after this node in the journey to link the remote account to a local account.

Compatibility

Product Compatible?

Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Dependencies

This node requires the following configuration in PingOne Advanced Identity Cloud:

Inputs

This node sends a SAML Request and processes the incoming SAML assertion.

Configuration

Property Usage

IdP Entity ID

The name of the remote IdP.

SP MetaAlias

The local alias for the SP in the format /Realm Name/SP Name.

Allow IdP to Create NameID

Enable this option if you want the IdP to create a new identifier for the authenticating user if none exists.

Learn more in AllowCreate in the SAML Version 2.0 specification.

Default: Enabled

Comparison Type

The comparison method to evaluate authentication context classes or statements.

This value overrides the value in the SP configuration:

PingAM Under Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context > Comparison Type.

Advanced Identity Cloud Under Native Consoles > Access Management > Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context > Comparison Type.

Valid comparison methods are exact, minimum, maximum, or better.

Learn more about comparison methods in Element <RequestedAuthnContext> in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

Default: minimum

Authentication Context Class Reference

(Optional) Set one or more URIs for authentication context classes to be included in the SAML request.

Authentication context classes are unique identifiers for an authentication mechanism. The SAML 2.0 protocol supports a standard set of authentication context classes, defined in Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0.

You can specify your own authentication context classes in addition to the standard ones.

Any authentication context class you specify here must be supported for the SP. To add authentication context classes to the SP:

  1. In the AM admin console, go to Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content.

  2. In the Authentication Context section, add the authentication context classes.

Authentication Context Supported by the SP

Use the | character to separate multiple authentication context classes, for example:

urn:oasis:names:tc:SAML:2.0:ac:classes:Password|urn:oasis:names:tc:SAML:2.0:ac:classes:TimesyncToken

Authentication Context Declaration Reference

(Optional) One or more URIs that identify authentication context declarations.

Use the | character to separate multiple URIs.

Learn more in the section on the <RequestedAuthnContext> element in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

Request Binding

The format of the authentication request that the SP sends to the IdP.

Valid values are HTTP-Redirect and HTTP-POST.

Default: HTTP-Redirect

Response Binding

The format of the response that the IdP sends to the SP.

Valid values are HTTP-POST and HTTP-Artifact.

Default: HTTP-Artifact

Force IdP Authentication

Indicate whether the IdP should force authentication or if it can reuse existing security contexts.

Default: Disabled

Passive Authentication

Indicate whether the IdP should use passive authentication.

When this setting is enabled, the IdP can only use authentication methods that don’t require user interaction, such as authenticating with an X.509 certificate.

Default: Disabled

NameID Format

The SAML name ID format that’s requested in the SAML authentication request. Valid values are:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Default: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

Outputs

This node updates the shared state with the SAML 2.0 assertion data as follows:

  • It adds a userInfo key with two child keys: attributes and userNames.

  • The attributes object contains a map of SAML 2.0 attributes, each of which is stored as an array.

  • The attributes object also stores the SAML 2.0 identity attributes sun-fm-saml2-nameid-info and sun-fm-saml2-nameid-infokey.

    These attributes are required by the Write Federation Information node.

  • The userNames object contains the user’s UUID.

Example node state after node processing 
{
    "realm" : "/",
    "authLevel" : 0,
    "username" : "22fe07c3-ac8b-4e84-9016-b55f1c009924",
    "userInfo" : {
      "attributes" : {
        "uid" : [ "bjensen" ],
        "mail" : [ "bjensen@example.com" ],
        "sun-fm-saml2-nameid-info" : [ "serviceprovider2|identityprovider1|sAdI2i7LT2YL0rbJC/QqsRt5SABV|identityprovider1|urn:oasis:names:tc:SAML:2.0:nameid-format:persistent|null|serviceprovider2|SPRole|false" ],
        "sun-fm-saml2-nameid-infokey" : [ "serviceprovider2|identityprovider1|sAdI2i7LT2YL0rbJC/QqsRt5SABV" ]
      },
      "userNames" : {
        "username" : [ "22fe07c3-ac8b-4e84-9016-b55f1c009924" ],
        "uid" : [ "22fe07c3-ac8b-4e84-9016-b55f1c009924" ]
      }
    },
    "emailAddress" : "bjensen@example.com"
  }
javascript

You can use a script to read the SAML 2.0 attributes, for example:

nodeState.get("userInfo").get("attributes").get("uid").get(0)
javascript

The updated shared state depends on the node outcome:

  • If the outcome is Account exists, the shared state is updated with nodeState.userNames as follows:

    userNames={username=[bjensen], uid=[bjensen]}}
    javascript

  • If the outcome is No account exists, the shared state is updated with nodeState.userNames as follows:

    userNames={username=[null], uid=[null]}}
    javascript

  • If the mail attribute exists in the attributes map, the shared state is updated with nodeState.emailAddress.

  • If the RelayState attribute exists in the attributes map, the shared state is updated with nodeState.successUrl.

  • The username is added to the shared state, regardless of outcome.

The node also sets the following session properties:

  • SessionIndex: the session index

  • NameID: the NameID of the Assertion XML

  • isTransient: if the NameId is urn:oasis:names:tc:SAML:2.0:nameid-format:transient

  • cacheKey: for internal use only

Outcomes

Account exists

The node found a user account that matches the federated account.

No account exists

Any other case.

Errors

This node can log the following errors:

Message Notes

Unable to complete SAML2 authentication, IDP descriptor not found for entity with id: ID

The node was unable to find the remote IdP descriptor.

Unable to complete SAML2 authentication, SP descriptor not found for entity with id: ID

The node was unable to find the SP descriptor.

Unable to retrieve SAML2 state from SFO

The node was unable to retrieve the SAML 2.0 state from the second-factor authentication.

Unable to complete SAML2 authentication, response data not found

The node was unable to read the SAML 2.0 response data.

Failed to remove data for responseKey starting with keyname

The node was unable to remove the SAML 2.0 response data.

AuthConsumer endpoint reported error code: code

The AuthConsumer endpoint (Assertion Consumer Service URL) on the SP reported an error.

Example

Read the following sections for examples that show this node in a SAML 2.0 authentication journey:

PingAM SSO and SLO in integrated mode.

Advanced Identity Cloud Configure Advanced Identity Cloud for integrated mode.