PingAM Auth node reference

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 claims such as iss (issuer) and aud (audience).

  • Collects relevant profile information from the provider.

  • Transforms the profile information using a script.

  • Searches for a matching user profile in AM.

    It does this by comparing the value of the sub (subject) claim from the id_token against the values in the planet-am-user-alias-list attribute (standalone AM) or the aliasList attribute (Ping Identity Platform deployments) of existing user profiles.

Compatibility

Product Compatible?

PingOne Advanced Identity Cloud

ForgeRock Access Management (self-managed)

Ping Identity Platform (self-managed)

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)

This script is used after the configured provider’s normalization script has mapped the social identity provider’s attributes to a profile format compatible with AM. The transformation script then transforms a normalized social profile to an identity (standalone AM) or a managed object (Ping Identity Platform deployment).

In standalone AM deployments, select Normalized Profile to Identity or a custom script that transforms the profile to an identity object.

To view the scripts and bindings, refer to normalized-profile-to-identity.js.

In Ping Identity Platform deployments, select Normalized Profile to Managed User (default) or a custom script to transform the profile to a managed object.

Review the sample script (normalized-profile-to-managed-user.js) for a list of bindings.

Normalization scripts (<Identity provider>-profile-normalization.*) are not suitable for this purpose.

Username Attribute

(Ping Identity Platform deployments only.)

The attribute in IDM that contains the username for this object.

Client Type

Specify the client type you are using to authenticate to the provider.

Use the default, BROWSER, with ForgeRock-provided user interfaces or the ForgeRock SDK for JavaScript. This causes the node to return the RedirectCallback.

Select NATIVE with the ForgeRock SDKs for Android or iOS. This causes the node to return the IdPCallback.

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 iplanet-am-user-alias-list attribute (standalone AM) or the aliasList attribute (Ping Identity Platform deployments) 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 ForgeRock account exists.

No account exists

Social authentication succeeded, but no matching ForgeRock account exists.

To ensure existing users are dynamically linked, complete these additional steps:

In a standalone AM deployment:

  1. Connect the No account exists outcome to a Scripted Decision node.

  2. Write a Scripted Decision node script and use the idRepository binding’s get- and setAttribute methods to check for an existing account and add a link by updating the account-linking attribute, iplanet-am-user-alias-list.

    For multiple OIDC providers, add links to the existing list. For example:

    "iplanet-am-user-alias-list": [
    "google_IDP-123456789",
    "amazon_IDP-987654321"
],

  3. Connect the Scripted Decision node to a Provision Dynamic Account node to update the account.

In a Ping Identity Platform deployment:

  1. Connect the No account exists outcome to an Identify Existing User node.

  2. Connect the Identify Existing User node to 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.

Example

This example shows the Social Provider Handler node in a social authentication journey.

journey social provider handler

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 AM can use

  • Assesses whether the user has an existing identity in AM

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

  • If the user doesn’t have an identity, 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 identity.

e The Create Object node creates the new identity in AM.