--- title: Social Provider Handler node description: Configure the Social Provider Handler node to authenticate users with a selected social identity provider, validate tokens, and match accounts in PingAM. component: platform version: 7.5 page_id: platform:auth-node-ref:social-provider-handler canonical_url: https://docs.pingidentity.com/platform/7.5/auth-node-ref/social-provider-handler.html llms_txt: https://docs.pingidentity.com/platform/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"] section_ids: availability: Availability 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.5/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.5/am-authentication/social-idp-client-reference.html). * Searches for a matching user account in Ping Identity Platform. 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.5/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. ## 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](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)* | The *normalization* script of each provider maps that provider's attributes to a profile format Ping Identity Platform can use.The *transformation* script then transforms the normalized social profile to a user account.In standalone AM deployments, 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](https://docs.pingidentity.com/pingam/7.5/am-scripting/sample-scripts.html#normalized-profile-to-identity-js)) for a list of bindings.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.5/am-scripting/sample-scripts.html#normalized-profile-to-managed-user-js)) for a list of bindings. Don't use normalization scripts (\-profile-normalization.\*) for this purpose. | | Username Attribute | ( This property is available only in the Ping Identity Platform admin UI. )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](https://docs.pingidentity.com/pingam/7.5/am-authentication/authn-supported-callbacks.html#RedirectCallback). - `NATIVE` Select this type for the ForgeRock SDKs for Android or iOS. With this setting, the node returns the [IdPCallback](https://docs.pingidentity.com/pingam/7.5/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. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | *In standalone AM deployments*, to ensure existing users are dynamically linked, complete these additional steps: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 Ping Identity Platform deployments*, to ensure existing users are dynamically linked, connect the `No account exists` outcome to an [Identify Existing User node](identify-existing-user.html) followed by 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 Ping Identity Platform can use * Assesses whether the user has an existing identity in Ping Identity Platform * 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 Ping Identity Platform.