--- title: Social Provider Handler node description: The Social Provider Handler node attempts to authenticate a user with the social identity provider selected in the Select Identity Provider node. component: auth-node-ref version: 7.4 page_id: auth-node-ref::social-provider-handler canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/social-provider-handler.html llms_txt: https://docs.pingidentity.com/auth-node-ref/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Nodes & Trees", "Journeys", "Authentication", "Social Authentication", "Scripts"] page_aliases: ["auth-node-social-provider-handler.adoc"] superseded_by: https://docs.pingidentity.com/auth-node-ref/latest/social-provider-handler.html section_ids: compatibility: Compatibility inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs outcomes: Outcomes example: Example --- # 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](select-identity-provider.html). 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](https://docs.pingidentity.com/pingam/7.4/am-authentication/social-idp-client-reference.html). * Collects relevant user profile information from the provider. * Transforms the profile information using the script specified in the [social provider configuration](https://docs.pingidentity.com/pingam/7.4/am-authentication/social-idp-client-reference.html). * Searches for a matching user account in AM. It does this by retrieving the claim name from the Auth ID Key field in the [social provider configuration](https://docs.pingidentity.com/pingam/7.4/am-authentication/social-idp-client-reference.html), which defaults to `sub` (subject). It then compares the value of that claim from the `id_token` against the values stored in the `iplanet-am-user-alias-list` attribute (standalone AM) or the `aliasList` attribute (Ping Identity Platform deployments) of existing user accounts. ## Compatibility | Product | Compatible? | | ------------------------------------------ | --------------------- | | PingOne Advanced Identity Cloud | [icon: check, set=fa] | | ForgeRock Access Management (self-managed) | [icon: check, set=fa] | | Ping Identity Platform (self-managed) | [icon: check, set=fa] | ## Inputs This node reads the user's selected social identity provider from shared state. Implement the [Select Identity Provider node](select-identity-provider.html) 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](https://docs.pingidentity.com/pingam/7.4/am-scripting/sample-scripts.html#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](https://docs.pingidentity.com/pingam/7.4/am-scripting/sample-scripts.html#normalized-profile-to-managed-user-js)) for a list of bindings.Normalization scripts (`-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](https://docs.pingidentity.com/pingam/7.4/am-authentication/authn-supported-callbacks.html#RedirectCallback).Select `NATIVE` with the ForgeRock SDKs for Android or iOS. This causes the node to return the [IdPCallback](https://docs.pingidentity.com/pingam/7.4/am-authentication/authn-supported-callbacks.html#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 user account exists. * `No account exists` Social authentication succeeded, but no matching user 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](scripted-decision.html). 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](am-only/provision-dynamic-account.html) to update the account.*In a Ping Identity Platform deployment*:1) Connect the `No account exists` outcome to an [Identify Existing User node](identify-existing-user.html). 2) Connect the [Identify Existing User node](identify-existing-user.html) to a [Patch Object node](patch-object.html) 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](select-identity-provider.html) 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](_images/journey-social-provider-handler.png) a A [Page node](page.html) contains the [Select Identity Provider node](select-identity-provider.html) 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](data-store-decision.html) 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](select-identity-provider.html) d The nodes on the page node request the information required to *register* a new identity. e The [Create Object node](create-object.html) creates the new identity in AM.