Social Provider Handler node

The Social Provider Handler node attempts to authenticate a user with an identity provider they select in the Select Identity Provider node. The Social Provider Handler node collects relevant profile information from the provider, transforms the profile information into the appropriate attributes, and returns the user to the journey.

Compatibility

Product	Compatible?
ForgeRock Identity Cloud	Yes
ForgeRock Access Management (self-managed)	Yes
ForgeRock Identity Platform (self-managed)	Yes

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)

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

The transformation script then transforms the normalized social profile to an identity (standalone AM) or a managed object (ForgeRock Identity Platform deployment).

Select Normalized Profile to Identity or a custom script that transforms the profile to an identity object.

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

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.

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

Username Attribute

(ForgeRock Identity Platform deployments only.)

The attribute in IDM 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 ForgeRock-provided user interfaces or the ForgeRock SDK for JavaScript.

With this setting, the node returns the RedirectCallback.
NATIVE Select this type for the ForgeRock SDKs for Android or iOS.

With this setting, the node returns 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 in AM, 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:

Connect the No account exists outcome to a Scripted Decision node.
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"
],
```
Connect the Scripted Decision node to a Provision Dynamic Account node to update the account. 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.

Example

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

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.

AM 7.5.0