Social authentication

AM supports delegated authentication through third-party identity providers, such as Facebook, and Google. This lets users log in to AM using their social provider credentials.

These topics describe the high-level steps to configure social authentication.

AM supports social identity providers that are OAuth 2.0 or OIDC 1.0-compliant. A number of social identity providers are configured by default:

Default social identity provider configurations
Identity provider	Specification
Amazon	OAuth 2.0
Apple	OIDC
Facebook	OAuth 2.0
Google	OIDC
Instagram	OAuth 2.0
itsme⁽¹⁾	OIDC
LINE (Browser)	OIDC
LINE (Native)	OIDC
LinkedIn (Legacy) ⁽²⁾	OAuth 2.0
LinkedIn	OIDC
Microsoft	OAuth 2.0
Salesforce	OAuth 2.0
Twitter	OAuth 2.0
VK (Vkontakte)	OAuth 2.0
WeChat	OAuth 2.0
WordPress	OAuth 2.0
Yahoo	OIDC

⁽¹⁾ To integrate with itsme, you must obtain an Organization Validation (OV) certificate.

You must also configure it in the container where AM runs, or in the reverse proxy offloading SSL.

⁽²⁾ The OAuth 2.0 version of the profile is deprecated by LinkedIn.

You can add providers that aren’t configured by default, as long as these providers have a solution implemented using either OAuth 2.0, or OpenID Connect.

Add identity providers

Register a service in the identity provider, and keep the provider’s documentation within reach. You will use it during this procedure.

To register a service in a provider, you must at least create a client ID and add the redirect URL to AM.

Redirect URLs

A redirect URL is a path in AM to which the identity provider redirects the user on successful authentication. For example, https://platform.example.com:8443/am.

Depending on the social identity provider and on your environment, you might need to make changes to the redirect URL later.

Configure the same redirect URL in the identity provider service and in the AM client.

Some providers require that you enable a specific setting or API in their service:

Google: Enable the Gmail API in the Google Cloud Platform.
Apple: You must have access to the Apple Development Program (Enterprise program is not eligible), and you must enable Sign In With Apple in the Apple Developer site.
Twitter: You must have an Elevated Developer Twitter Account to obtain a token, and you must set up an application at https://developer.twitter.com/en/portal/dashboard.

LINE

You must apply for permission for your LINE channel to access a user’s email address using OIDC:

In the LINE Developers console, enable Email address permission.
Agree to the terms and conditions, and follow the steps to complete the application.
The console displays Applied when your application is accepted.

If you don’t have email permission, the registration will fail with an Invalid Attribute Syntax error.

In the AM admin UI, go to Realms > Realm Name > Services.
Check if the Social Identity Provider Service appears in the list of services configured for the realm.

If it does not, click Add a Service, select Social Identity Provider Service from the drop-down list, and click Create.
Ensure the Enabled switch is on.
Go to the Secondary Configurations tab.

AM includes scripts and configurations for several common identity providers.
In the Add a Secondary Configuration drop-down list, select the required identity provider.

If the required provider isn’t available, select one of the following to add a custom identity provider client:
- Client Configuration for providers that implement the OAuth2 specification
- Client Configuration for providers that implement the OpenID Connect specification

Provide the details of the service you registered with the social provider, such as the Client ID, the Client Secret, the Scope Delimiter (usually an empty space), and the Redirect URL.

For OAuth 2.0 social identity providers, store the client secret in a secret store for greater security.

Use the Client Secret Label Identifier to create a dynamic secret label to map to an alias for the secret.

Learn more about secrets in Map and rotate secrets.

Redirect URLs

A redirect URL is a path in AM to which the identity provider redirects the user on successful authentication. For example, https://platform.example.com:8443/am.

Depending on the social identity provider and on your environment, you might need to make changes to the redirect URL later.

Configure the same redirect URL in the identity provider service and in the AM client.

Don’t worry if you are missing some details; you can edit the configuration later after saving the client profile for the first time.

Click Create your changes to access all the configuration fields for the client.

Provide the client’s advanced configuration details and edit any required configuration details if needed.

Where do I find the required identity provider information?

Refer to the provider’s documentation.

Providers must specify their integration needs in their documentation, as well as their API endpoints.

For example, providers usually have different scopes that you can configure depending on your service’s needs.

Financial-grade providers usually also require additional security-related configuration, such as acr values, PKCE-related settings, and more.

Keep their documentation close while configuring the client profile.
Visit the provider’s .well-known endpoint.

OAuth 2.0/OpenID Connect-compliant providers will display much of the information you need to configure the identity provider client in their .well-known endpoint. For example, the endpoint should expose their endpoint URLs, and the signing and encryption algorithms they support.

AM provides default configuration for the supported social identity providers based on each provider’s requirements. Providers sometimes change their requirements over time, so you must make sure the settings for the provider haven’t changed.

The important preconfigured fields are:

The provider’s URLs; for example, Authentication Endpoint URL, Access Token Endpoint URL, and User Profile Service URL.
The OAuth Scopes field.
The Well Known Endpoint for retrieving information about the provider.

Leave this field empty for the LINE (Browser) configuration.
The configuration in the UI Config Properties section.

For common UI properties, refer to UI Config Properties.
The script selected in the Transform Script drop-down list.

This script is responsible for mapping attributes provided by the identity providers to a profile format compatible with AM.

For details, refer to Transform Script.

Some features require choosing algorithms from those supported by the provider, as well as creating secrets. Consider the following points before configuring the client:

Several capabilities in the identity provider client share the same secret labels. For example, signing request objects and signing client authentication JWTs.
Every identity provider client in a realm shares the same secrets.

Therefore, ensure that you configure features requiring secrets in a way that they’re compatible across clients in the same realm.

Learn more in /oauth2/connect/rp/jwk_uri.

For details on client configuration settings, refer to Social identity provider client configuration.

Save your changes.

You are now ready to Configure basic social registration trees.

To let AM contact Internet services through a proxy, refer to Configure AM behind a reverse proxy.

You can control the behavior of the connection factory that AM uses as a client of the social identity providers:

Client connection handler properties

The following advanced server properties control aspects of the connection factory:

org.forgerock.openam.httpclienthandler.system.clients.connection.timeout
org.forgerock.openam.httpclienthandler.system.clients.max.connections
org.forgerock.openam.httpclienthandler.system.clients.pool.ttl
org.forgerock.openam.httpclienthandler.system.clients.response.timeout
org.forgerock.openam.httpclienthandler.system.clients.retry.failed.requests.enabled
org.forgerock.openam.httpclienthandler.system.clients.reuse.connections.enabled

They have sensible defaults configured. If you need to change them, read Advanced properties.

There are two nodes associated with Identity Providers:

Select Identity Provider node: The Select Identity Provider node prompts the user to select a social identity provider to register or log in with, or (optionally) continue on with a local registration or login flow. When a provider is selected, the flow continues on to the Social Provider Handler node.
Social Provider Handler node: The Social Provider Handler node is used in combination with the Select Identity Provider node. It communicates with the selected provider and collects the information provided after the user has authorized the service. It runs the provider’s configured normalization script to map the information into a format that AM can consume.

Next, the node uses a transformation script provided by AM called Normalized Profile to Identity to transform the profile information into an identity object.

The node then queries the identity store available for the realm to verify the user already exists. If the user exists, they are logged in. If the user does not exist, the user will need to be created.

Some of these steps differ slightly, depending on whether you’re using the AM admin UI or the Platform UI.

- AM admin UI
- Platform UI
Go to Realms > Realm Name > Authentication > Trees, and create a new tree.

In your realm, go to Journeys, and create a new journey.
Decide whether users can log in with their AM credentials, and add the relevant nodes to the tree:
- AM admin UI
- Platform UI
Social authentication trees allowing local authentication might look like the following:

Social authentication trees enforcing social authentication login might look like the following:
Social authentication journeys allowing local authentication might look like the following:

Social authentication journeys enforcing social authentication login might look like the following:
To configure either option, use the Include local authentication switch in the Select Identity Provider node.

To support both local and social authentication in the same page, you must use the Page node as shown in the example.
Configure the Social Provider Handler node:
- In the Transformation Script field, select Normalized Profile to Identity. This script transforms the normalized identity provider’s profile object into the appropriate user profile attributes of the realm’s identity store.
  
  If you are not using DS as the identity store, or if you added customized fields to it, you may need to modify the script.
  
  Find the script and available bindings in normalized-profile-to-identity.js.
- In Client Type, select BROWSER when using the AM UI, or NATIVE when using the Ping SDKs.

To let users connect to social identity providers through the End User UI profile page, add a mapping for your social authentication journey:

Log in to the AM admin UI and switch to the relevant realm.
From the left navigation pane, click Services.
Select Self Service Trees.
Set a new key and value and click + Add:

Key

connectSocial

Value

The name of the journey
Click Save Changes.

PingAM 8.0.0

Social authentication

Configure social identity providers

Add identity providers

Configure basic social registration trees

Set up a basic social registration tree (journey)

Let users connect through their profile page