--- title: Social authentication description: 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. component: pingam version: 7.2 page_id: pingam:authentication-guide:social-registration canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authentication/social-registration.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md superseded_by: https://docs.pingidentity.com/pingam/8.1/am-authentication/social-registration.html section_ids: configure-social-providers: Configure social identity providers configure-idp: Add identity providers basic-social-registration: Configure basic social registration trees social-am-basic-reg-tree: Set up a basic social registration tree social-idp-client-reference: Client configuration reference --- # 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. ## Configure social identity providers PingAM supports social identity providers that are OAuth 2.0 or OpenID Connect 1.0-compliant. A number of social identity providers are configured by default: **Default social identity provider configurations** | | | | | --------- | -------------- | ---------- | | Amazon | Apple | Facebook | | Google | Instagram | itsme(1) | | LinkedIn | Microsoft | Salesforce | | Twitter | VK (Vkontakte) | WeChat | | WordPress | Yahoo | | (1) To integrate with [itsme](https://www.itsme.be/en/), 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. You can add providers that are not configured by default, as long as these providers have a solution implemented using either OAuth 2.0, or OpenID Connect. ### Add identity providers 1. 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 PingAM. > **Collapse: Redirect URLs** > > A *redirect URL* is a path in PingAM 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 PingAM client. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Some providers require that you enable a specific 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 . | 2. In the AM admin UI, go to Realms > *Realm Name* > Services. 3. 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. 4. Ensure that the Enabled switch is on. 5. Go to the Secondary Configurations tab. PingAM includes scripts and configurations for several common identity providers. 6. In the Add a Secondary Configuration drop-down list, select the required identity provider. If you do not see the required provider, 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 7. Provide the details of the service you registered with the social provider: 1. In the Client ID field, enter the client ID of the service. This field might have a different name, depending on the social identity provider. For example, for Twitter, this field is the API key. 2. In the Client Secret field, enter the client secret of the service. This field might have a different name, depending on the social identity provider. For example, for Twitter, this field is the API secret. 3. Enter the same Redirect URL that you set in the social provider service. > **Collapse: Redirect URLs** > > A *redirect URL* is a path in PingAM 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 PingAM client. Don't worry if you are missing some of the details; you'll be able to edit the configuration later, after saving the client profile for the first time. Click Create to access all the configuration fields for the client. 8. Provide the client's advanced configuration details, and edit any required configuration details if needed. > **Collapse: 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. PingAM provides a default configuration for the supported social identity providers based on each provider's requirements. Providers sometimes change their requirements over time. **Make sure the settings for the provider have not 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 configuration in the UI Config Properties section. * 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 PingAM. For details, refer to [Transform Script](#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 IDs. 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 are compatible across clients in the same realm.For more information, see the page about the [/oauth2/connect/rp/jwk_uri](../oidc1-guide/managing-rp-jwk_uri.html) endpoint. | For tips on how to configure the client, see [Client configuration reference](#social-idp-client-reference). 9. Save your changes. You are now ready to [Configure basic social registration trees](#basic-social-registration). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To let AM contact Internet services through a proxy, see [Configuring AM for Outbound Communication](https://docs.pingidentity.com/pingam/7.2/security-guide/reverse-proxy.html#outbound-communication).You can control the behavior of the connection factory that AM uses as a client of the social identity providers:> **Collapse: Client connection handler properties** > > The following advanced server properties control different 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, but if you need to change them, see [Advanced Properties](https://docs.pingidentity.com/pingam/7.2/reference/deployment-configuration-reference.html#server-advanced). | ## Configure basic social registration trees There are two nodes associated with Identity Providers: * Select Identity Provider node The [Select Identity Provider node](auth-node-configuration-hints.html#auth-node-select-identity-provider) 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](auth-node-configuration-hints.html#auth-node-social-provider-handler) 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 then takes that information and runs a transformation script to prepare it. AM includes a transformation script called Normalized Profile to Identity, which this node uses to transform the identity object gathered from the identity provider into a user profile in AM's identity store. The node then queries IDM to see if 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. The node then queries the identity store available for the realm to see if 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. ### Set up a basic social registration tree 1. In the AM admin UI, go to Realms > *Realm Name* > Authentication > Trees, and create a new [tree](about-authentication-trees.html). 2. Decide whether users can log in with their AM credentials, and add the relevant nodes to the tree: 1. Social authentication trees allowing local authentication might look like the following: ![Example Social Authentication Tree with Local Authentication](_images/social-registration-am.png) 2. Social authentication trees enforcing social authentication login might look like the following: ![Example Social Authentication Tree Enforcing Social Login](_images/trees-node-anonymous-user-mapping-tree-example.png) To configure either option, use the Include local authentication switch in the [Select Identity Provider node](auth-node-configuration-hints.html#auth-node-select-identity-provider). To support both local and social authentication in the same page, you must use the [Page node](auth-node-configuration-hints.html#auth-node-page) as shown in the example. 3. Configure the [Social Provider Handler node](auth-node-configuration-hints.html#auth-node-social-provider-handler): * In the Transformation Script field, select `Normalized Profile to Identity`. This script will transform 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 in Realms > *Realm Name* > Scripts. * In Client Type, select `BROWSER` when using the PingAM UI, or the ForgeRock SDK for JavaScript. ## Client configuration reference * Enabled Specifies whether the provider is enabled. Required: Yes. * Auth ID Key Specifies the attribute the social identity provider uses to identify an authenticated individual. For example, `id`, `sub`, and `user_id`. Required: Yes. * Client ID Specifies the `client_id` parameter as described in [section 2.2](https://www.rfc-editor.org/rfc/rfc6749.html#section-2.2) of *The OAuth 2.0 Authorization Framework* specification. Required: Yes. * Client Secret Specifies the `client_secret` parameter as described in [section 2.3](https://www.rfc-editor.org/rfc/rfc6749.html#section-2.3) of *The OAuth 2.0 Authorization Framework* specification. Required: No. * Authentication Endpoint URL Specifies the URL to the social provider's endpoint handling authentication as described in [section 3.1](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.1) of *The OAuth 2.0 Authorization Framework*. For example, `https://accounts.google.com/oauth2/v2/auth`. Required: Yes. * Access Token Endpoint URL Specifies the URL to the endpoint handling access tokens as described in [section 3.2](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.2) of *The OAuth 2.0 Authorization Framework* specification. For example, `https://www.googleapis.com/oauth2/v4/token`. Required: Yes. * User Profile Service URL Specifies the user profile URL that returns profile information. For example, `https://www.googleapis.com/oauth2/v3/userinfo`. This URL should return JSON objects in its response. Required: No. * Token Introspection Endpoint URL Specifies the URL to the endpoint handling access token validation, as described in the [OAuth 2.0 Token Introspection](https://www.rfc-editor.org/info/rfc7662) specification. For example, `https://oauth2.googleapis.com/tokeninfo`. Required: No. * Redirect URL Specifies the URL the identity provider will redirect the user to after authenticating, as described in [Section 3.1.2](https://www.rfc-editor.org/info/rfc6749#section-3.1.2) of *The OAuth 2.0 Authorization Framework* specification. This URL is usually a page or path in AM; for example, `https://platform.example.com:8443/am`, and it is also registered in the identity provider's service. You can also use a custom URI scheme as the redirect, if you are using an app built with the ForgeRock SDKs for Android or iOS. For example, `com.example.sdkapp:redirect_uri_path` or `frauth://com.forgerock.ios.sdkapp`. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------- | | | When using the `FORM_POST`Response Mode, you must specify the `form_post` endpoint in the redirection URL. See Response Mode for more information. | Required: Yes. * Redirect after form post URL Specifies the URL of a custom login page or application. PingAM will send processed form post data related to social login authentication to that URL as the value of the `form_post_entry` query parameter. To continue the authentication journey, the custom login page is responsible for making a call to the PingAM `/json/authenticate` endpoint with the authentication ID (`authID`) and the processed form data (`form_post_entry`). Configure this property when the following is true: * The `FORM_POST`Response Mode is configured. * Your users log in to PingAM using custom login pages, such as apps using the ForgeRock SDKs, instead of the PingAM UI. Required: No. * Scope Delimiter Specifies the delimiter used to separate scope values. For example, a blank space (``), or a comma character (`,`). Most providers use a blank space. Required: Yes. * OAuth Scopes Specifies the list of scopes to request from the provider. The scopes that the provider returns depends on the permissions that the resource owner, such as the end user, grants to the client application. For example, Google exposes its supported scopes in their [OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes) documentation. Required: Yes. * Client Authentication Method Specifies how the client should authenticate to the provider. Possible values are: * `CLIENT_SECRET_POST`. The client sends the client ID and the secret in the `client_ID` and the `client_secret` parameters in the body of the request. * `CLIENT_SECRET_BASIC`. The client sends the client ID and the secret in a basic authorization header with the base64-encoded value of *client-id:client-secret*. * `PRIVATE_KEY_JWT`. The client sends its credentials to the provider in a signed JWT as specified in the [JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://www.rfc-editor.org/info/rfc7523). * `ENCRYPTED_PRIVATE_KEY_JWT`. The client sends its credentials to the provider in a signed, then encrypted JWT as specified in the [JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://www.rfc-editor.org/info/rfc7523). * `TLS_CLIENT_AUTH`. The client presents a X.509 certificate that uses public key infrastructure (PKI), as specified in the [OAuth 2.0 Mutual TLS (mTLS) Client Authentication and Certificate Bound Access Tokens](https://www.rfc-editor.org/info/rfc8705). * `SELF_SIGNED_TLS_CLIENT_AUTH`. The client presents a X.509 self-signed certificate, as specified in the [OAuth 2.0 Mutual TLS (mTLS) Client Authentication and Certificate Bound Access Tokens](https://www.rfc-editor.org/info/rfc8705). Some of the authentication methods require additional configuration: > **Collapse: How do I configure JWT authentication with signed JWTs?** > > 1. Obtain a list of supported signing algorithms from the provider's `.well-known` endpoint, and decide which one you will use. > > 2. In the Private Key JWT Signing Algorithm field, enter the signing algorithm that PingAM will use to sign the JWT. For example, `RSA256`. > > This field may already be configured if the client is sending request objects. > > 3. Create a signing secret, and map it to the `am.services.oauth2.oidc.rp.jwt.authenticity.signing` secret ID in an AM secret store. > > The secret ID may already have secrets mapped to it if the client is sending signed request objects to the provider, or if another client in the realm is already using it. > > For more information, see [Secret stores](../security-guide/secret-stores.html), and [/oauth2/connect/rp/jwk_uri](https://docs.pingidentity.com/pingam/7.2/oidc1-guide/managing-rp-jwk_uri.html). > > 4. Provide a JWK with the public key to the identity provider. Refer to their documentation for more information. > > For example, you could copy the contents of the public JWK in a field in the provider's service configuration, or you could configure the realm's `/oauth2/connect/rp/jwk_uri` endpoint, which exposes the client's public keys. > > Configure the realm's `/oauth2/connect/rp/jwk_uri` endpoint in the provider, which exposes the client's public keys. Refer to the provider's documentation for more information. > > 5. Change the value in the Private Key JWT Expiration Time (seconds) field, if needed. It has a sensible value preconfigured, but you may need to tune it for your provider. > **Collapse: How do I configure JWT authentication with signed and encrypted JWTs?** > > 1. Follow the steps in [How do I configure JWT authentication with signed JWTs?](#JWT-auth-signing) to configure PingAM to sign authentication JWTs. > > Now you are ready to configure PingAM to encrypted authentication JWTs. > > 2. Obtain a list of supported encryption algorithms and methods from the provider's `.well-known` endpoint, and decide which one you will use. > > 3. In the JWT Encryption Algorithm field, select the encryption algorithm. > > If the required encryption algorithm does not appear in the drop-down, check the reference entry for the JWT Encryption Algorithm field for information on how to add it. > > This field may already be configured if the client is encrypting request objects. > > 4. In the JWT Encryption Method field, select the encryption method. > > This field may already be configured if the client is encrypting request objects. > > 5. In the JWKS URI Endpoint field, configure the URI containing the provider's public JWK set. > > Obtain the URI from the provider's `.well-known` endpoint, or their documentation. > > PingAM will use the JWK URI to fetch the provider's public encryption key. > > 6. Perform one of the following steps depending on the encryption method you configured: > > 1. If you chose Direct AES Encryption method, select `NONE` in the JWT Signing Algorithm field. Signing is redundant with this encryption method. > > 2. If you chose an encryption method different from the Direct AES Encryption method, configure signing. For more information, see [How do I configure JWT authentication with signed JWTs?](#JWT-auth-signing). > **Collapse: How do I configure mTLS authentication with PKI?** > > 1. Obtain a certificate for PingAM to use as a client. This certificate must be signed by a certificate authority (CA). > > You can use the same certificate for different social identity provider client configurations, and you can only have one mTLS certificate by realm (either PKI-related, or self-signed). > > 2. Make the certificate available to PingAM configuring it in an AM secret store, and map its alias to the `am.services.oauth2.mtls.client.authentication` secret ID. > > For example, you can create a `PKCS12` keystore secret store. > > For more information, see [Secret stores](../security-guide/secret-stores.html). > > Even though the identity provider should trust the CA certificate automatically, the client certificate will appear in the [/oauth2/connect/rp/jwk_uri](https://docs.pingidentity.com/pingam/7.2/oidc1-guide/managing-rp-jwk_uri.html) endpoint. > **Collapse: How do I configure mTLS authentication with self-signed certificates?** > > 1. Obtain a self-signed certificate that PingAM will use as a client. > > You can use the same certificate for different social identity provider client configurations, and you can only have one mTLS certificate by realm (either PKI-related, or self-signed). > > 2. Make the certificate available to PingAM configuring it in an AM secret store, and map its alias to the `am.services.oauth2.mtls.client.authentication` secret ID. > > For example, you can create a `PKCS12` keystore secret store. > > For more information, see [Secret stores](../security-guide/secret-stores.html). > > To trust the self-signed certificate, the social identity provider must be able to access its public key and certificate. Social identity providers may have different ways of accessing public keys; for example, you may be able to configure the public JWK directly in the provider, or you may be able to provide PingAM's [/oauth2/connect/rp/jwk_uri](https://docs.pingidentity.com/pingam/7.2/oidc1-guide/managing-rp-jwk_uri.html) endpoint, which exposes it. > > Refer to your social identity provider documentation for more information. Required: Yes. * PKCE Method Specifies the PKCE transformation method PingAM uses when making requests to the provider's authorization endpoint, as specified in [Section 4.2](https://www.rfc-editor.org/info/rfc7636#section-4.2) of the *Proof Key for Code Exchange by OAuth Public Clients* specification. Select `NONE` to disable PKCE transformations. Required: No. * Request Parameter JWT Option (OpenID Connect providers only) Specifies whether PingAM should provide a request object JWT to the provider. Possible values are: * `NONE`. PingAM does not send a request object to the provider. * `REFERENCE`. The request object JWT is stored in AM's CTS token store, and PingAM exposes a unique identifier for it using the `oauth2/request_uri` endpoint for the realm. The URL to the endpoint and the JWT's unique identifier are passed to the provider in the `request_uri` parameter of the request. Ensure that the provider can reach the endpoint. An example of the URL is `https://platform.example.com:8443/am/realms/root/realms/myRealm/oauth2/request_uri/requestobjectID` | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When integrating with [itsme](https://www.itsme.be/en/), ensure that the base URL of AM contains the `443` port. For example, `https://platform.example.com:443/am`.To do this, configure the reverse proxy or load balancer to expose the port, or the Base URL Source Service:1) In the AM admin UI, go to Realms > *Realm Name* > Services. 2) Add a Base URL Source service if one is not already configured, or select it to change its properties: ![A screenshot showing itsme example configuration details for the Base URL Source service.](_images/base-URL-itsme.png) | * `VALUE`. PingAM appends the JWT as the value of the `request` parameter of the request. > **Collapse: How do I configure the client to send signed request objects?** > > 1. In the Request Parameter JWT Option field, select either `VALUE` or `REFERENCE`. > > Refer to your identity provider's documentation for more information. > > 2. Obtain a list of supported signing algorithms from the provider's `.well-known` endpoint, and decide which one you will use. > > 3. In the JWT Signing Algorithm field, select the signing algorithm that PingAM will use to sign the request object. For example, `RS256`. > > This field may already be configured if the client is using JWT client authentication. > > 4. Create a signing secret that uses the algorithm you selected previously, and map it to the\`am.services.oauth2.oidc.rp.jwt.authenticity.signing\` secret ID in an AM secret store. > > The secret ID may already have secrets mapped to it if the client is using JWT client authentication, or if another client in the realm is already using it. > > For details, refer to [Secret stores](../security-guide/secret-stores.html) and [/oauth2/connect/rp/jwk_uri](../oidc1-guide/managing-rp-jwk_uri.html). > > 5. Provide a JWK with the public key to the identity provider. Refer to their documentation for more information. > > For example, you could copy the contents of the public JWK in a field in the provider's service configuration, or you could configure the realm's `/oauth2/connect/rp/jwk_uri` endpoint, which exposes the client's public keys. > > Configure the realm's `/oauth2/connect/rp/jwk_uri` endpoint in the provider, which exposes the client's public keys. Refer to the provider's documentation for more information. > **Collapse: How do I configure the client to send signed and encrypted request objects?** > > 1. Follow the steps in [How do I configure the client to send signed request objects?](#how-to-sign-request-objects) to configure PingAM to send signed request objects. > > Now you are ready to configure PingAM to send encrypted request objects. > > 2. Enable Encrypt Request Parameter JWT. > > 3. Obtain a list of supported encryption algorithms and methods from the provider's `.well-known` endpoint, and decide which one you will use. > > 4. In the JWT Encryption Algorithm field, select the encryption algorithm. > > If the required encryption algorithm does not appear in the drop-down, check the reference entry for the JWT Encryption Algorithm field for information on how to add it. > > This field may already be configured if the client is encrypting authentication JTWs. > > 5. In the JWT Encryption Method field, select the encryption method. > > This field may already be configured if the client is encrypting authentication JWTs. > > 6. In the JWKS URI Endpoint field, configure the URI containing the provider's public JWK set. > > Obtain the URI from the provider's `.well-known` endpoint. > > PingAM will use the JWK URI to fetch the provider's public encryption key. > > 7. Perform one of the following steps depending on the encryption method you configured: > > 1. If you chose Direct AES Encryption method, select `NONE` in the JWT Signing Algorithm field. Signing is redundant with this encryption method. > > 2. If you chose an encryption method different from the Direct AES Encryption method, configure signing. For more information, see [How do I configure the client to send signed request objects?](#how-to-sign-request-objects). * Encrypt Request Parameter JWT Specifies whether the request parameter must be encrypted when Request Parameter JWT Option is set to `REFERENCE` or `VALUE`. * ACR Values (OpenID Connect providers only) Specifies a space-separated list, in order of preference, of the client's `acr` values. Required: No. * Well Known Endpoint (OpenID Connect providers only) Specifies the URL for retrieving information about the provider, such as endpoints, and public keys. For example, `https://accounts.google.com/.well-known/openid-configuration`. Required: Yes. * Request Object Audience (OpenID Connect providers only) Specifies the intended audience (`aud`) of the request object when the Request Parameter JWT Option field is set to `VALUE` or `REFERENCE`. When not configured, the value of the Issuer field will be used as the audience of the request object. * OP Encrypts ID Tokens (OpenID Connect providers only) Specifies whether the provider encrypts ID Tokens. > **Collapse: How do I configure the PingAM to receive encrypted tokens?** > > 1. Obtain a list of supported ID token encryption algorithms from the provider's `.well-known` endpoint, and decide which one the client will use. > > 2. Create a suitable secret for the algorithm that you chose, and map it to the `am.services.oauth2.oidc.rp.idtoken.encryption` secret ID in an AM secret store. > > The secret ID may already have secrets mapped if another client in the realm is already using it. > > For more information, see [Secret stores](../security-guide/secret-stores.html), and [/oauth2/connect/rp/jwk_uri](https://docs.pingidentity.com/pingam/7.2/oidc1-guide/managing-rp-jwk_uri.html). > > 3. Provide a JWK with the public key to the identity provider. Refer to their documentation for more information. > > For example, you could copy the contents of the public JWK in a field in the provider's service configuration, or you could configure the realm's `/oauth2/connect/rp/jwk_uri` endpoint, which exposes the client's public keys. > > Configure the realm's `/oauth2/connect/rp/jwk_uri` endpoint in the provider, which exposes the client's public keys. Refer to the provider's documentation for more information. Required: No. * Issuer (OpenID Connect providers only) Specifies the issuer of ID Tokens. Must exactly match the value returned in the ID token. Obtain the `issuer` value from the provider's `.well-known` endpoint. Required: Yes. * Enable Native Nonce (OpenID Connect providers only) When enabled, the provider native SDK must include a `nonce` claim in the ID token. The value of the claim must be the value of the `nonce` claim sent in the Authentication Request. Required: No. * User Info Response Format (OpenID Connect providers only) Specifies the format in which the provider's `userinfo` endpoint returns data. Some of the options require additional configuration: > **Collapse: How do I configure the client to receive signed userinfo JWTs?** > > 1. In the JWKS URI Endpoint field, configure the URL containing the provider's public JWK set. Obtain it from the provider's `.well-known` endpoint, or their documentation. > > PingAM will use this URL to fetch the provider's public signing key. > **Collapse: How do I configure the client to receive signed, then encrypted userinfo JWTs?** > > 1. Follow the steps in [How do I configure the client to receive signed userinfo JWTs?](#signed-userinfo-JWT) to configure PingAM to receive signed JWTs. > > Now you are ready to configure PingAM to receive encrypted JWTs. > > 2. Obtain a list of supported ID token encryption algorithms from the provider's `.well-known` endpoint, and decide which one the client will use. > > 3. Create a suitable secret for the algorithm that you chose, and map it to the `am.services.oauth2.oidc.rp.idtoken.encryption` secret ID in an AM secret store. > > The secret ID may already have secrets mapped if another client in the realm is already using it, or if the provider encrypts ID tokens. > > For more information, see [Secret stores](../security-guide/secret-stores.html), and [/oauth2/connect/rp/jwk_uri](https://docs.pingidentity.com/pingam/7.2/oidc1-guide/managing-rp-jwk_uri.html). > > 4. Provide a JWK with the public key to the identity provider. Refer to the identity provider's documentation for more information. > > For example, you could copy the contents of the public JWK in a field in the provider's service configuration, or you could configure the realm's `/oauth2/connect/rp/jwk_uri` endpoint, which exposes the client's public keys. > > Configure the realm's `/oauth2/connect/rp/jwk_uri` endpoint in the provider, which exposes the client's public keys. Refer to the provider's documentation for more information. Possible values are: * `JSON`. The provider's `userinfo` endpoint returns a JSON object. * `SIGNED_JWT`. The provider's `userinfo` endpoint returns a signed JWT. * `SIGNED_THEN_ENCRYPTED_JWT`. The provider's `userinfo` endpoint returns a signed, then encrypted JWT. * JWKS URI Endpoint Specifies the URI that contains the public keys of the identity provider. PingAM will use these keys to verify signatures, or to encrypt objects. Configure this field when: * Client Authentication Method is set to `ENCRYPTED_PRIVATE_KEY_JWT`. * Encrypt Request Parameter JWT is enabled. * User Info Response Format is set to `SIGNED_JWT` or `SIGNED_THEN_ENCRYPTED_JWT`. Required: No. * Claims Any claims on the request object, in JSON format. These claims must conform to the [claims request parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter), as defined in the *OpenID Connect specification*. * JWT Signing Algorithm Specifies the signing algorithm supported by the provider that PingAM use to sign the following: * Client authentication JWTs when Client Authentication Method is set to `PRIVATE_KEY_JWT`. * (OpenID Connect providers only) Request JWTs when Request Parameter JWT Option is set to `VALUE` or `REFERENCE`. Obtain a list of the supported algorithms from the provider's `.well-known` endpoint. Select `NONE` if the client will encrypt the JWT with the Direct AES Encryption method, because the signature will be redundant.\ Required: No. * JWT Encryption Algorithm Specifies the encryption algorithm supported by the provider that PingAM should use to encrypt client authentication JWTs when Client Authentication Method is set to `PRIVATE_KEY_JWT`, and (OpenID Connect providers only) request JWTs when Request Parameter JWT Option is set to `VALUE` or `REFERENCE`. If set to `NONE`, PingAM will not encrypt the JWTs. Obtain a list of the supported algorithms from the provider's `.well-known` endpoint. Configure the algorithms exposed in this field using the AM advanced server property, [openam.private.key.jwt.encryption.algorithm.whitelist](../reference/deployment-configuration-reference.html#social-provider-encrypt-JWT-alg-property). > **Collapse: How do I configure advanced server properties?** > > * To configure advanced server properties for all instances in the AM environment, go to Configure > Server Defaults > Advanced in the AM admin UI. > > * To configure advanced server properties for a specific instance, go to Deployment > Servers > *Server Name* > Advanced. > > If the property you want to add or edit is already configured, click on the pencil ([icon: pencil-alt, set=fa]) button to edit it. When you are finished, click on the tick ([icon: check, set=fa]) button. > > Save your changes. Required: No. * JWT Encryption Method Specifies the encryption algorithm supported by the provider that PingAM should use to encrypt the following: * Client authentication JWTs when Client Authentication Method is set to `PRIVATE_KEY_JWT`. * (OpenID Connect providers only) Request JWTs when Request Parameter JWT Option is set to `VALUE` or `REFERENCE`. Use in conjunction with `JWT Encryption Algorithm`. Obtain a list of the supported methods from the provider's `.well-known` endpoint.\ Required: No. * Private Key JWT Expiration Time (seconds) Specifies the amount of time, in seconds, that PingAM will cache the client authentication JWT before creating a new one. Caching the JWT avoids creating a new one for every client authentication. However, it may also become invalid if the provider changes it configuration. Required: No. * Response Mode (OpenID Connect providers only) Specify the way the provider will return ID tokens to PingAM. Possible values are: * `DEFAULT`. The provider returns the ID token as query parameters, as explained in the [OpenID Connect Core 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-core-1_0.html) specification. Most preconfigured providers use the `DEFAULT` response mode. * `FORM_POST`. The provider returns the ID token by submitting an HTML form using the HTTP POST method, as explained in the [OAuth 2.0 Form Post Response Mode](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html) specification. When using this response mode, add the `/oauth2/client/form_post/ClientConfigName` URI to the Redirect URL, where *ClientConfigName* is the name of the social identity provider client that you are configuring. For example, `https://platform.example.com:8443/am/oauth2/client/form_post/myAppleClient`. By default, the `form_post` endpoint processes the post data, encrypts it, and redirects with it back to the authentication tree to resume authentication. However, environments using custom login pages need to configure the Redirect after form post URL property to redirect back to the custom login pages. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The `/oauth2/client/form_post` does not require authentication. Protect it from denial of service (DoS) attacks by limiting the rate at which it can take connections in your load balancer or proxy.If you configured PingAM with AES Key Wrap encryption, you must configure the `org.forgerock.openam.encryption.useextractandexpand` property.For more information, see [Preparing AES Key Wrap Encryption](https://docs.pingidentity.com/pingam/7.2/install-guide/prepare-aeswrap.html). | Required: Yes. - Request Native App for UserInfo (Apple SSO) When enabled, this flag indicates that the native app can send the user's `userinfo` in JSON format. Apple returns the `userinfo` only *once*, when the user first consents to send their details, and not on subsequent authentication attempts. In addition, the user has the option *not* to consent to Apple sending their `userinfo`. If you are progressively profiling the `userinfo` with data from other social providers (usually, using a Patch Object node), there is a risk of overwriting the user's details with blank values when the user authenticates through Apple SSO. To mitigate this risk, you can add a Scripted Decision node to your authentication journey that assesses whether the `userinfo` is provided and patches the object accordingly. > **Collapse: How do I use a Scripted Decision node to patch an object, based on the returned ?** > > The [normalized-profile-to-managed-user.groovy](../scripting-guide/sample-scripts.html#normalized-profile-to-managed-user-groovy) script and [normalized-profile-to-managed-user.js](../scripting-guide/sample-scripts.html#normalized-profile-to-managed-user-js) scripts set a boolean flag (`nameEmptyOrNull`) that indicates whether the user's `firstName` and `lastName` have been returned. > > Create a custom script that uses this flag, then add a Scripted Decision node that calls your script. An example of a custom script that achieves this functionality follows: > > * JavaScript > > * Groovy > > ```javascript > if (sharedState.get('nameEmptyOrNull')) { > outcome = 'true' > } else { > outcome = 'false' > } > ``` > > ```groovy > if (sharedState.get("nameEmptyOrNull").asBoolean()) { > outcome = "true" > } else { > outcome = "false" > } > ``` > > The outcome of the Scripted Decision node will be either to patch the `userinfo` object or not to patch the `userinfo` object. > > If you need to progressively profile the user information on every authentication, *regardless of whether the user's first name and last name are returned by the OIDC provider*, you can use another Scripted Decision node that does the following: \* If the user details are not present, route the `userinfo` patch through a [Patch Object node](auth-node-configuration-hints.html#auth-node-patch-object), configured to ignore the `firstName` and `lastName`. (In the Ignored Fields list, add `givenName` to ignore the `firstName` and `sn` to ignore the `lastName`.) \* If the user details are present, route the `userinfo` patch through a Patch Object node that patches the full object. > > For information about using Scripted Decision nodes in authentication journeys, see [Scripted Decision node](auth-node-configuration-hints.html#auth-node-scripted-decision). > > Learn more in [First name and last name get blanked out when signing in to Advanced Identity Cloud or PingAM using Apple social sign-on](https://support.pingidentity.com/s/article/First-name-and-last-name-get-blanked-out-when-signing-in-to-Advanced-Identity-Cloud-or-PingAM-using-Apple-social-signon) in the *Knowledge Base*. Required: No. - UI Config Properties Specifies a map of properties defined and consumed in the UI. The map affects how the identity provider's logo will show on the login page. > **Collapse: PingAM common end user UI properties** > > * `buttonImage`: A relative path to an image in the End User UI. > > * `buttonCustomStyle`: Any custom CSS you wish to apply to the button outside of normal End User UI styling. > > * `buttonClass`: Adds the specified class to the identity provider button, for any additional styling you want to apply. > > * `buttonCustomStyleHover`: Adds custom styling when the cursor is hovering over the button. > > * `buttonDisplayName`: The name of the identity provider, which will be included either on the button or in the button's `alt` attribute, depending on styling. > > * `iconFontColor`: Specifies the color of the icon. You can use methods supported in CSS (such as `white`, or `#ffffff`). > > * `iconClass`: Adds the specified class to the identity provider icon, for any additional styling you want to apply. > > * `iconBackground`: The color for the background of the icon. You can use methods supported in CSS (such as `white`, or `#ffffff`). Required: Yes. * Transform Script A script to convert the provider's raw profile object into a normalized object. Each social identity provider returns different user profile information using their own attribute names. For example, Google's OIDC `/userinfo` endpoint returns claims, which AM stores in a `rawProfile` object. The following `google-profile-normalization.groovy` script maps the attributes of this object to AM profile attributes: ```groovy import static org.forgerock.json.JsonValue.field import static org.forgerock.json.JsonValue.json import static org.forgerock.json.JsonValue.object return json(object( field("id", rawProfile.sub), field("displayName", rawProfile.name), field("givenName", rawProfile.given_name), field("familyName", rawProfile.family_name), field("photoUrl", rawProfile.picture), field("email", rawProfile.email), field("username", rawProfile.email), field("locale", rawProfile.locale))) ``` The script returns a JSON object containing normalized attributes in the following format: `("", rawProfile.)` For example, `id` is the platform attribute name, while `rawProfile.sub` is the field received from the provider. Even if field names are the same, such as `email` and `rawProfile.email`, they must still be mapped for them to be included in the returned JSON object. PingAM provides default scripts for other preconfigured identity providers. To view the bindings and expected return values, find the `-profile-normalization.*` scripts in [Sample scripts](../scripting-guide/sample-scripts.html). To write your own script in Groovy or Javascript for an identity provider, go to Realms > *Realm Name* > Scripts, and use the provided scripts as a reference. When a user authenticates, the social authentication journey calls another transformation script set in the [Social Provider Handler node](auth-node-configuration-hints.html#auth-node-social-provider-handler) to convert the attributes again; this time into an identity object that AM can process. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Social authentication nodes expect every attribute to have a value. In other words, the attributes returned by the identity provider cannot be empty or `null`, or the journey will end with an error.For example, if a user tries to log in using Google as the identity provider, but they did not configure a surname in their account, Google returns `null` as the value of the `familyName` for the identity, and social authentication fails.Ensure all users have their social profiles configured correctly, or modify the transformation scripts so that they don't collect null or empty attributes. | Required: Yes