--- 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: auth-node-ref version: 8.1 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 revdate: 2026-08-18T00:00:00Z keywords: ["Nodes & Trees", "Journeys", "Authentication", "Social Authentication", "Scripts"] page_aliases: ["auth-node-social-provider-handler.adoc"] section_ids: examples: Examples availability: Availability inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs callbacks: Callbacks outcomes: Outcomes errors: Errors --- # 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/8.1/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/8.1/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/8.1/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. ## Examples This example shows the Social Provider Handler and Select Identity Provider nodes in a social authentication journey. ![journey social provider handler](_images/journey-social-provider-handler.png) a The [Page node](page.html) containing the [Select Identity Provider node](select-identity-provider.html) 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 user account in AM * If the user has an existing user account, authenticates that user * If the user doesn't have a user account, 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 user account. e The [Create Object node](create-object.html) creates the new user account in AM. ## 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 AM can use.The *transformation* script then transforms the normalized social profile to a user account.Select `Normalized Profile to Identity` (AM), `Normalized Profile to Managed User` (Ping Identity Platform), or a custom script you've created to transform the profile to an identity object. Review the sample script ([normalized-profile-to-identity.js](https://docs.pingidentity.com/pingam/8.1/am-scripting/sample-scripts.html#normalized-profile-to-identity-js) or [normalized-profile-to-managed-user.js](https://docs.pingidentity.com/pingam/8.1/am-scripting/sample-scripts.html#normalized-profile-to-managed-user-js)) for a list of bindings.You can use either the next-generation script type (`Social Provider Handler Node`) or the legacy script type (`Social Identity Provider Profile Transformation`) to create a custom script. Don't use normalization scripts (\-profile-normalization.\*) for this purpose. | | Username Attribute | The attribute in the underlying identity service 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 Ping Identity-provided user interfaces or the Ping SDK for JavaScript. With this setting, the node returns the `RedirectCallback`. - `NATIVE` Select this type for the Ping SDK for Android or iOS. With this setting, the node returns the `IdPCallback`. | | Store Tokens | Select this option to store access and refresh tokens in the transient state for use by subsequent nodes in the journey.Sometimes, the social provider requires these tokens, for example, to revoke user authorization. If you choose to store tokens, you can configure a [Scripted Decision node](scripted-decision.html) later in the journey to handle your social provider use case.Default: `Not enabled` | | Detect Connection Time Out | Select this option to detect if the connection to the social identity provider has timed out. If the connection times out, the node follows the `Time Out` outcome.Default: `Not enabled` | | Subject Attribute | The attribute in the underlying identity store that's used to search for an existing user. This attribute is only used in AM standalone deployments that use an identity store other than PingDS.Default: `iplanet-am-user-alias-list` | ## 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. | ## Callbacks The node sends either a `RedirectCallback` or an `IdPCallback`, depending on the selected client type. Learn more in [Supported callbacks](https://docs.pingidentity.com/pingam/8.1/am-authentication/callbacks-supported.html). ## Outcomes * `Account exists` Social authentication succeeded, and a matching user account exists. * `No account exists` Social authentication succeeded, but no matching user account exists. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * Standalone AM: 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. * 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. * `Time Out` The connection to the social identity provider has timed out. ## Errors If the connection to the social identity provider times out, the node logs a `Connection closed during social login callback` warning.