PingIDM 7.5.0

Account claiming: links between accounts and social identity providers

Social authentication is deprecated and will be removed in a future release of IDM. For more information, refer to Deprecation.

If your users have one or more social identity providers, they can link them to the same IDM user account. This section assumes that you have configured one or more of the social identity providers described in Social registration.

Conversely, you should not be able to link more than one IDM account with a single social identity provider account.

When social accounts are associated with an IDM account, IDM creates a managed record, which uses the name of the social identity provider name as the managed object type, and the subject is used as the _id. This combination has a unique constraint; if you try to associate a second IDM account with the same social account, IDM detects a conflict, which prevents the association.

The default process uses the email address associated with the account. Once you’ve configured social identity providers, you can see this filter in the selfservice-socialUserClaim.json file:

{
    "name" : "socialUserClaim",
    "identityServiceUrl" : "managed/user",
    "claimQueryFilter" : "/mail eq \"{{mail}}\""
},

You can modify the claimQueryFilter to a different property such as telephoneNumber. Make sure that property is:

  • Set to "required" in the managed.json file; the default list for managed users is shown here:

    "required" : [
    "userName",
    "givenName",
    "sn",
    "mail"
]

  • Unique; for example, if multiple users have the same telephone number, IDM responds with error messages shown in When Multiple Users have the Same Email Address.

Based on the claimQueryFilter, what IDM does depends on the following scenarios:

When you register with a social identity provider, IDM checks the email address of that account against the managed user data store.

If that email address doesn’t exist for any IDM managed user, IDM takes available identifying information, and pre-populates the self-registration screen. If all required information is included, IDM proceeds to other screens, depending on what you’ve activated in this section: Additional configuration.

When you register with a social identity provider, IDM checks the email address of that account against the managed user data store.

If that email address exists for one IDM managed user, IDM gives you a chance to link to that account, with the following message:

We found an existing account with the same email address <substitute email address>. To continue, please enter your password to link accounts.

In the text box, users are expected to enter their IDM account password.

When you register with a social identity provider, IDM checks the email address of that account against the managed user data store.

If that email address exists for multiple IDM managed users, IDM denies the login attempt, with the following error message:

Unable to authenticate using login provider

IDM denies further attempts to login with that account with the following message:

Forbidden request error

For information about customizing the End User UI, refer to the Github repository: ForgeRock/end-user-ui.

When your users register with a social identity provider, as defined in Social registration, they create an account in the IDM managed user data store. As an end user, you can link additional social identity providers to that data store, from the End User UI:

  1. Navigate to the End User UI. For example, http://idm.example.com:8080.

  2. Log in to the account, either as an IDM user, or with a social identity provider.

  3. Navigate to Profile > Social Sign-in.

    The list of configured social identity providers displays.

  4. Connect to the social identity providers of your choice. Unless you’ve already signed in with that social provider, you are prompted to log in to that provider.

  5. To test the result, log out and log back in, using the link for the newly linked social identity provider.

You can review social identity accounts linked to an IDM account, from the admin UI and from the command line. You can disable or delete social identity provider information for a specific user from the command line, as described in Reviewing Linked Accounts Over REST.

When you activate a social identity provider, IDM creates a new managed object for that provider. You can review that managed object in the managed.json file, as well as in the admin UI, by selecting Configure > Managed Objects.

The information shown is reflected in the schema in the identityProvider-providername.json file for the selected provider.

Do not edit social identity provider profile information in IDM. Any changes won’t be synchronized with the provider.

To identify linked social identity provider accounts for a user, you must specifically add the idps field to your user query. For example, the following query shows bjensen’s linked social identity information:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/user?_queryFilter=userName+eq+'bjensen'&_fields=idps"
{
  "result": [
    {
      "_id": "bjensen",
      "_rev": "000000003062291c",
      "idps": [
        {
          "_ref": "managed/google/108246554379618660085",
          "_refResourceCollection": "managed/google",
          "_refResourceId": "108246554379618660085",
          "_refProperties": {
            "_id": "ba01a4c3-8a7f-468b-8b09-95f5d34f05ea",
            "_rev": "0000000098619792"
          }
        }
      ]
    }
  ],
  ...
}

For more information about a specific social identity provider, query the identity relationship using the referred resource ID. The following example shows the information collected from the Google provider for bjensen:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/google/108246554379618660085"
{
  "_id": "108246554379618660085",
  "_rev": "00000000e5cace4d",
  "sub": "108246554379618660085",
  "name": "Barbara Jensen",
  "given_name": "Barbara",
  "family_name": "Jensen",
  "picture": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg",
  "email": "babs.jensen@gmail.com",
  "email_verified": true,
  "locale": "en",
  "_meta": {
    "subject": "108246554379618660085",
    "scope": [
      "openid",
      "profile",
      "email"
    ],
    "dateCollected": "2018-03-08T02:07:27.882"
  }
}

When a user disables logins through one specific social identity provider in the End User UI, that sets "enabled" : false in the data for that provider. However, that user’s social identity information is preserved.

Alternatively, you can use a REST call to disable logins to a specific social identity provider. The following REST call removes a user’s ability to log in through Google:

curl  \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-type: application/json" \
--request POST \
"http://localhost:8080/openidm/managed/user/9dce06d4-2fc1-4830-a92b-bd35c2f6bcbb?_action=unbind&provider=google"

In this case, the REST call deletes all Google social identity provider information for that user.

When you configure a social identity provider, IDM includes two features in the admin UI.

  • The ability to review the social identity accounts linked to specific users. To refer to how this works, log in to the admin UI, and select Manage > User, and select a user. Under the Identity Providers tab, you can review the social identity providers associated with a specific account.

  • A managed object for each provider. For example, if you’ve enabled Google as a social identity provider, select Manage > Google. On the Google List page, you can select the ID for any Google social identity account that has been used or linked to an existing IDM account, and review the profile information shared from the provider.