Selecting a Social Login Application

In order to use a custom provider (or, for that matter, in order to use one of the Identity Cloud’s predefined identity providers), you need a social login application (historically known as an “Engage” application). If you’re already using social login in Hosted Login then you’re fine: you wouldn’t be able to use social login if you didn’t have a social login application. In that case, you can use Console to view your application (or application client) and retrieve your social login application ID (look for the rpx_app_id setting):

Why do we care so much about the social login application ID? Well, for one thing, this ID is required anytime you call the Custom Provider API endpoints (which, in turn, are the only way to create and manage custom providers). For example, the following code snippet references the value layflfixkxlhgruitref:

https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/v2/config/low/services/engage-v2/apps/layflfixkxlhgruitref/custom-providers

As you probably figured out, layflfixkxlhgruitref is a social login application ID.

If you aren’t sure whether or not you have a social login application (or if you can’t find this information in Console), you can retrieve a list of your social login application IDs by using the /engage-v2/apps endpoint and the GET method. For example, the following Curl command returns information about all your social login applications (or, to be more precise, all the social login applications associated with the Akamai customer ID 00000000-0000-0000-0000-000000000000):

curl -L -X GET \
  'https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/v2/config/low/services/engage-v2/apps' \
  -H 'Authorization: Bearer 90Yqubr1_0DvSDtNl8OVtkOyPV6orQspL3ZYCYLzvp_qiTWCVqnGBlnhJcF-gW90'

Assuming that you have at least one social login application, you’ll get back information similar to the following, with the social login application IDs shown in red:

{
  "_links": {
    "self": {
      "href": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/v2/config/low/services/engage-v2/apps"
    },
    "item": {
      "href": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/v2/config/low/services/engage-v2/apps{/id}",
      "templated": true
    }
  },
  "_embedded": {
    "item": [
      {
        "_links": {
          "self": {
            "href": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/v2/config/low/services/engage-v2/apps/bsvgwtngmcsycuerawjj"
          }
        },
        "appid": "bsvgwtngmcsycuerawja",
        "realm": "acme-dev"
      },
      {
        "_links": {
          "self": {
            "href": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/v2/config/low/services/engage-v2/apps/hsvgwtngmcsycuerawjj"
          }
        },
        "appid": "hsvgwtngmcsycuerawj",
        "realm": "acme-stg"
      },
      {
        "_links": {
          "self": {
            "href": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/v2/config/low/services/engage-v2/apps/edvgwtngmcsycuerawhl"
          }
        },
        "appid": "edvgwtngmcsycuerawhl",
        "domain": "social.acme.com",
        "cname": "social-acme-com.janrain.ws"
      }
    ]
  },
  "total": 3
}

Note. What if the API response doesn’t show any social login applications? In that case, you’ll need to contact your Identity Cloud representative and make arrangements to get one of those applications.

To return detailed information about a specific social login application, just add the application ID to the end of your API call. For example, this command returns detailed information for the social login application with the ID layflfixkxlhgruitref:

curl -L -X GET \
  'https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/v2/config/low/services/engage-v2/apps/layflfixkxlhgruitref'\
  -H 'Authorization: Bearer 90Yqubr1_0DvSDtNl8OVtkOyPV6orQspL3ZYCYLzvp_qiTWCVqnGBlnhJcF-gW90'

What kind of information does that API call return? Information like the following:

{
  "_links": {
    "self": {
      "href": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/v2/config/low/services/engage-v2/apps/hsvgwtngmcsycuerawjj"
    },
    "custom-providers": {
      "href": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/v2/config/low/services/engage-v2/apps/hsvgwtngmcsycuerawjj/custom-providers"
    }
  },
  "appid": "hsvgwtngmcsycuerawjj",
  "createdAt": "2021-02-06T00:16:07.259495126Z",
  "updatedAt": "2021-02-06T00:16:07.259495126Z",
  "customerid": "00000000-0000-0000-0000-000000000000",
  "realm": "identitydocs",
  "secret": "e6681cb18g04bd08gc40d42efgd9f2fd88he7aea"
}

And that’s another good question: do we really need this level of detail when it comes to social login applications? Well, the fact that we highlighted several of the preceding property values in red should give you a hint: yes, you do need that level of detail for your social login applications. That’s because, in order to enable social login in Hosted Login, your application clients must include values for several Social Login settings:

Without these values, social login won’t be available in Hosted Login.

Note: You can configure these values on an application client-by-application client basis, or you can configure these values as part of your global application settings. If you take the latter route, the values will, by default, apply to all your application clients. 

With one exception, the values needed to configure the Social Login settings are the same values returned by the /apps/{appId} API call:

Social Login Setting

API Response Value

rpx_app_id. Unique identifier for the social login application.

appId. For example: 

hsvgwtngmcsycuerawjj

rpx_key. “Password” associated with the social login application.

secret. For example:

fg54e1cb18g04bd08gc40d42efgd9f2fd88heiiu8

rpx_realm. Social login subdomain on the https://rpxnow.com domain. For example, if your social login URL is https://identitydocs.rpxnow.com then your rpx_realm is identitydocs.

realm.  For example:

identitydocs

rpx_server. URL for the social login server.

Not returned by the API call. The rpx_server value is not returned by the /apps/{appId} endpoint. However, unless instructed otherwise by your Akamai representative this value should always be set to https://rpxnow.com.

We should probably add that, if you haven’t configured social login in Hosted Login, you must do that before you create a custom provider. See this article for more information.