Authentication nodes

Social Provider Handler node

The Social Provider Handler node attempts to authenticate a user with the social identity provider selected in the Select Identity Provider node.

The node performs the following actions:

  • Validates the id_token returned by the provider to ensure its integrity, verifying the token’s signature and checking that claims such as iss (issuer) and aud (audience) match the values defined in the social provider configuration.

  • Collects relevant user profile information from the provider.

  • Transforms the profile information using the script specified in the social provider configuration.

  • Searches for a matching user account in Advanced Identity Cloud.

    It does this by retrieving the claim name from the Auth ID Key field in the social provider configuration, which defaults to sub (subject). It then compares the value of that claim from the id_token against the values stored in the aliasList attribute of existing user accounts.

Examples

Example 1: Social authentication

This example shows the Social Provider Handler and Select Identity Provider nodes in a social authentication journey.

journey social provider handler

a The Page node containing the Select Identity Provider node prompts the user to select a social identity provider or to authenticate with a username and password.

b If the user selects local authentication, the Data Store Decision node takes care of the authentication.

c If the user selects social authentication, the Social Provider Handler node does the following:

  • Routes the user to the selected social provider to authenticate there

  • Retrieves the user’s profile information, and transforms it into a format that Advanced Identity Cloud can use

  • Assesses whether the user has an existing user account in Advanced Identity Cloud

    • If the user has an existing user account, authenticates that user

    • If the user doesn’t have a user account, routes the user to another page node

    • If the user interrupts the social authentication, routes the user back to the Select Identity Provider node

d The nodes on the page node request the information required to register a new user account.

e The Create Object node creates the new user account in Advanced Identity Cloud.

Example 2: Dynamic account linking

This example shows a social authentication journey with dynamic account linking.

journey social provider handler link

a A Page node contains the Select Identity Provider node node that prompts the user to select a social identity provider or to authenticate with a username and password.

b If the user selects local authentication, the Data Store Decision node takes care of the authentication.

c If the user selects social authentication, the Social Provider Handler node does the following:

  • Routes the user to the selected social provider to authenticate there

  • Retrieves the user’s profile information, and transforms it into a format that Advanced Identity Cloud can use

  • Assesses whether the user has an existing user account in Advanced Identity Cloud

d The Identify Existing User node checks if the user exists in Advanced Identity Cloud using the Identity Attribute specified and does the following:

  • If the user exists, routes the user to the Patch Object node

  • If the user doesn’t exist, routes the user to another page node

e The Patch Object node updates the existing user to create the link.

f The nodes on the page node request the information required to register a new user account.

g The Create Object node creates the new user account in Advanced Identity Cloud.

Availability

Product Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

This node reads the user’s selected social identity provider from shared state.

Implement the Select Identity Provider node before this node to capture the social provider name.

Dependencies

  • The Social Identity Provider service must be configured with the details of at least one social identity provider.

  • The user must have selected a social identity provider in a previous node in the journey.

Configuration

Property Usage

Transformation Script (required)

The normalization script of each provider maps that provider’s attributes to a profile format Advanced Identity Cloud can use.

The transformation script then transforms the normalized social profile to a user account.

Select Normalized Profile to Managed User (default), or a custom script you’ve created to transform the profile to a managed object. Review the sample script (normalized-profile-to-managed-user.js) for a list of bindings.

Don’t use normalization scripts (<Identity provider>-profile-normalization.*) for this purpose.

Username Attribute

Platform UI

The attribute in the underlying identity service (PingIDM) that contains the username for this object.

Client Type

The client type you’re using to authenticate to the provider. Select one of the following:

  • BROWSER (default) Select this type for Ping Identity-provided user interfaces or the Ping SDK for JavaScript.

    With this setting, the node returns the Redirect callback. Find more information in RedirectCallback.

  • NATIVE Select this type for the Ping SDK for Android or iOS.

    With this setting, the node returns the Idp callback. Find more information in IdPCallback.

Store Tokens

When true, the node stores access and refresh tokens in the transient state for use by subsequent nodes in the journey.

In some cases, the social provider requires these tokens, for example, to revoke user authorization. If you choose to store tokens, you can configure a Scripted Decision node later in the journey to handle your social provider use case.

Default: false

Outputs

  • If no profile information is returned from the social provider, the journey follows the Social auth interrupted outcome.

  • If the node retrieves profile information from the social identity provider, it transforms a normalized version of the profile and stores it in objectAttributes in transient state.

  • To link existing users, the aliasList attribute is updated and saved to objectAttributes in transient state.

  • The node stores the social identity subject as the username both directly in shared state and in its objectAttributes.

  • The node also updates socialOAuthData in transient state with all existing node state, social provider data, and associated tokens.

Make sure you copy required transient data to shared state because all transient data is removed if the node is followed by an interactive page later in the journey.

Outcomes

Account exists

Social authentication succeeded, and a matching user account exists.

No account exists

Social authentication succeeded, but no matching user account exists.

To ensure existing users are dynamically linked, connect the No account exists outcome to an Identify Existing User node followed by a Patch Object node to create the link.
Social auth interrupted

The user interrupted the social authentication journey after the node requested profile information from the social identity provider. This can happen in the following situations:

  • The user clicks the Back button in their browser from the social identity provider’s login page

  • The user clicks the Cancel button on the social identity provider’s login page

  • The user re-enters the journey URL in the same browser window

    In this case, the node routes the user back to the Select Identity Provider node to select a social identity provider again.

Errors

This node doesn’t log any error or warning messages of its own.