Identity Cloud

Social authentication

You can configure user self-registration to include social identity providers as an option for users. This lets users register and log in to AM using an account they have through another trusted service.

The high-level steps to configure social authentication are:

Configure social identity providers

AM supports social identity providers that are OAuth 2.0 or OpenID Connect 1.0-compliant, and comes preconfigured with support for a number of social providers:

Table 1. 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®, you must obtain an Organization Validation (OV) or an Extended Validation (EV) SSL certificate.

How do I get a custom OV/EV SSL certificate?

The procedure to create and configure a custom SSL certificate is as follows:

  1. Request a certificate signing request (CSR) by raising a support ticket.

    Provide information in the CSR ticket according to the type of certificate you need to obtain:

  2. Request an OV/EV certificate.

    Send the CSR to your preferred certificate authority (CA) and receive a custom certificate in return.

  3. Supply ForgeRock support with the certificate.

    ForgeRock will apply the certificate to the requisite environments for you to use to securely query endpoints supported by your social identity provider.

If you need support for a social identity provider that is not preconfigured, you can manually add new providers, as long as they have a solution implemented using either OAuth 2.0, or OpenID Connect.

Add identity providers

  1. Register a service with the identity provider.

    Registering with a provider comprises creating a client ID and adding the redirection URL to AM at the very least.

    Each identity provider will have a different registration or onboarding process. Make sure you are familiar with their documentation and refer to it throughout this procedure so that you are aware of any particular requirements.

    Although AM is preconfigured with many of the settings that are required by the provider, you may need to perform additional tasks.

    For example, a financial-grade provider could stipulate that you connect using a high-assurance SSL certificate, so you would need to follow the steps to obtain a custom SSL certificate.

    Redirection URLs

    The redirection URL is a path in AM that the identity provider will redirect the user to after a successful authentication. For example, https://platform.example.com:8443/am.

    Depending on the social identity provider and on your environment, you may need to make changes to the redirection URI later.

    Configure the same redirection URL in the identity provider service and in the AM 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.

  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 to add, and select Social Identity Provider Service from the drop-down list.

    The service’s Configuration page appears.

  4. Ensure that the Enabled switch is on.

  5. Go to the Secondary Configurations tab.

    AM 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

    The new identity provider configuration page appears.

  7. Provide the client’s required configuration details, such as the Client ID, Client Secret (for confidential clients), the Scope Delimiter (usually an empty space), and the Redirect URL.

    Redirection URLs

    The redirection URL is a path in AM that the identity provider will redirect the user to after a successful authentication. For example, https://platform.example.com:8443/am.

    Depending on the social identity provider and on your environment, you may need to make changes to the redirection URI later.

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

    Do not worry if you are missing some of the details; you will be able to edit the configuration later, after saving the client profile for the first time.

    Save your changes 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.

    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 is preconfigured for your convenience, but you must make sure the settings for the provider have not changed. Some of the most 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.

      Scripts named after identity providers are suitable for most use cases. However, if you need to view or edit the scripts, go to Realms > Realm Name > Scripts.

    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 /oauth2/connect/rp/jwk_uri.

    For tips on how to configure the client, see Client configuration reference.

  9. Save your changes.

Configure basic social registration trees

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 then takes that information and runs a transformation script to prepare it.

AM includes a transformation script called Normalized Profile to Managed User, which this node uses to transform the identity object gathered from the identity provider into a AM object.

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 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 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 your realm, go to Journeys.

    You can create a new tree, modify an existing tree, or duplicate an existing tree.

  2. Decide whether users can log in with their local 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
    2. Social authentication trees enforcing social authentication login might look like the following:

      Example social authentication tree enforcing social login

      To configure either option, use the Include local authentication switch in the Select Identity Provider node.

      Note that, to support both local and social authentication in the same page, you must use the Page node as shown in the example.

  3. Configure the Social Provider Handler node:

    • In the Transformation Script field, configure Normalized Profile to Managed User. This script will transform the normalized identity provider’s profile object into an appropriate object that AM can use.

      Find the script in Realms > Realm Name > Scripts.

    • In Client Type , select BROWSER when using the AM UI, or the ForgeRock SDK for JavaScript.

  4. Configure the Required Attributes Present node and the Create Object node:

    In the Identity Resource field, configure the relevant managed identity resource type. For example, managed/user or managed/alpha_user.

To check for the available managed identity resource types, go to the IDM admin UI, and open the Manage drop-down list, at the upper right corner of the screen.

Identity managed object types are preceded by the icon.

  1. Configure the Attribute Collector node adding, at least, the mail, givenName, and sn attributes.

Configure social registration with account claiming

If your users have one or more social identity provider accounts, they can link them to the same AM account.

The following example builds on the basic social registration tree shown in Set up a basic social registration tree:

Example social authentication tree with account claiming
Figure 1. Example Social Registration Tree with Account Claiming

The tree uses the Identify Existing User node to determine if the user is already registered in AM. By default, the node checks whether the email address associated with the account is already registered in AM.

Ensure that you configure the Transformation Script in the Social Provider Handler node, and the Identity Resource field in the Patch Object node.

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 of The OAuth 2.0 Authorization Framework specification.

Required: Yes.

Client Secret

Specifies the client_secret parameter as described in 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 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 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 specification. For example, https://oauth2.googleapis.com/tokeninfo.

Required: No.

Redirect URL

The URL to which the identity provider will redirect the user after authenticating, as described in 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.

  • If you encounter domain validation prompts when using forgeblocks.com and id.forgerock.io domains as redirect URLs in your Google OAuth 2.0 applications, you must use a custom domain, and then set up domain verification with Google.

  • If you encounter No provider found errors when using forgeblocks.com and id.forgerock.io domains as redirect URLs in your OAuth 2.0 applications, either modify the redirect URL to include a realm identifier, or use a custom domain:

    • Wrong:
      https://<tenant-env-fqdn>/am/oauth2/client/form_post/…​

    • Right:
      https://<tenant-env-fqdn>/am/oauth2/<realm>/client/form_post/…​
      or
      https://<custom-domain>/am/oauth2/client/form_post/…​

      A custom domain acts as a realm DNS alias, so when it is used as a redirect URL, Identity Cloud implicitly knows which realm to use.

Required: Yes.

Redirect after form post URL

Specifies the URL of a custom login page or application. AM 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 AM /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 AM using custom login pages, such as apps using the ForgeRock SDKs, instead of the AM UI.

    Required: No.

Scope Delimiter

Specifies the delimiter used to separate scope values. For example, a blank space (kbd:[ ]), or a comma character (kbd:[,]).

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 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.

  • 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.

    Some authentication methods require additional configuration:

    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 AM will use to sign the JWT. For example, RSA256.

      This field may already be configured if the client is sending request objects.

    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.

    4. 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.

    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? to configure AM to sign authentication JWTs.

      Now you are ready to configure AM 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.

      AM 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?.

    Required: Yes.

PKCE Method

Specifies the PKCE transformation method AM uses when making requests to the provider’s authorization endpoint, as specified in 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 AM should provide a request object JWT to the provider. Possible values are:

  • NONE. AM does not send a request object to the provider.

  • REFERENCE. The request object JWT is stored in AM’s CTS token store, and AM 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®, ensure that the base URL of AM contains the 443 port. For example, https://platform.example.com:443/am.

    To do this, configure 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.
  • VALUE. AM appends the JWT as the value of the request parameter of the request.

    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 AM 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. 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.

    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? to configure AM to send signed request objects.

      Now you are ready to configure AM 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.

      AM 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?.

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.

How do I configure AM to receive encrypted tokens?
  1. 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.

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 options require additional configuration:

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.

    AM will use this URL to fetch the provider’s public signing key.

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? to configure AM to receive signed JWTs.

    Now you are ready to configure AM to receive encrypted JWTs.

  2. Provide a JWK with the public key to the identity provider. Refer to the 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.

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. AM 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, as defined in the OpenID Connect specification.

JWT Signing Algorithm

Specifies the signing algorithm supported by the provider that AM will 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 AM 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, AM will not encrypt the JWTs. Obtain a list of the supported algorithms from the provider’s .well-known endpoint.

Required: No.

JWT Encryption Method

Specifies the encryption algorithm supported by the provider that AM 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 AM 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 AM. 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 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 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.

    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.

How do I use a Scripted Decision node to patch an object, based on the returned userinfo?

The normalized-profile-to-managed-user.js script sets 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:

if (sharedState.get('nameEmptyOrNull')) {
  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, 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.

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.

AM 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

Specifies a script to convert the provider’s raw profile object into a normalized object. An authentication tree will later convert the object again into attributes the AM can use.

AM provides scripts for the preconfigured identity providers; they are ready to use, and suitable for most use cases.

To write a script in Javascript for an identity provider, go to Realms > Realm Name > Scripts, and use the provided scripts as a reference.

Transformation script information and example

The following is the default JavaScript transformation script for Google:

(function () {
    var frJava = JavaImporter(
        org.forgerock.json.JsonValue
    );

    var normalizedProfileData = frJava.JsonValue.json(frJava.JsonValue.object());

    normalizedProfileData.put('id', rawProfile.get('sub'));
    normalizedProfileData.put('displayName', rawProfile.get('name'));
    normalizedProfileData.put('givenName', rawProfile.get('given_name'));
    normalizedProfileData.put('familyName', rawProfile.get('family_name'));
    normalizedProfileData.put('photoUrl', rawProfile.get('picture'));
    normalizedProfileData.put('email', rawProfile.get('email'));
    normalizedProfileData.put('username', rawProfile.get('email'));
    normalizedProfileData.put('locale', rawProfile.get('locale'));

    return normalizedProfileData;
}());

The script returns a JsonValue object with all the mapped ojects.

Each field is mapped using a key and corresponding value in the following format: ("platformAttributeName", rawProfile.get(providerAttributeName)).

For example, id is the platform attribute name, while rawProfile.get('sub') is the value received from the provider.

Note that some field names are the same, for instance email and rawProfile.get('email'). These fields still need to be mapped, so they are included in the returned JsonValue object.

The 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. If any of the attributes is empty or null, the social authentication tree 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 will return null as the value of the familyName for the identity, and social authentication will fail.

Ensure that all the users have their social profiles configured correctly, or modify the transformation scripts so that they not collect attributes that may be empty.

Required: Yes.

Copyright © 2010-2022 ForgeRock, all rights reserved.