AM 7.3.1

Social Provider Handler node

Takes the provider selection from the Select Identity Provider node and attempts to authenticate the user. This node collects relevant profile information from the provider and returns the user to the flow, transforming the profile information into the appropriate attributes.

Compatibility

Product Compatible?

ForgeRock Identity Cloud

Yes

ForgeRock Access Management (self-managed)

Yes

ForgeRock 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)

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.

Select Normalized Profile to Identity, or your own script that you have created to transform the profile to an identity object.

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

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

Username Attribute

ForgeRock Identity Platform deployments only.

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

  • When the node attempts to authenticate the user through the social provider, it sets expectProfileInformation to true in the node state. If no profile information is returned, the journey follows the Social auth interrupted outcome.

  • If the node retrieves the profile information from the social identity provider, performs the required transformations, and locates a matching identity, it puts the identity into the node state to authenticate the user.

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.
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 for authentication.

  • 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.