Hosted Login API Clients and Client Settings

If you use a JavaScript SDK or an API-based implementation of the Akamai Identity Cloud, API clients(referred to as “properties” in the Console) are used to make authenticated requests against the Akamai Identity Cloud REST APIs. In addition, API clients that use the login_client feature are employed for user logins and registrations. Each application requires at least two API clients: one with the owner feature (used to manage the application itself) and one with the login_client feature (required for user logins and registrations).

That’s the way things have worked in the past. In Hosted Login, however, things are different. Hosted Login still requires at least two API clients:

  • An owner client for making API calls
  • A login_client that must be associated with an OpenID Connect (OIDC) client

But the login client is not used to handle user logins and registrations (that’s the job of the OIDC client). Instead, the login client works in tandem with the OIDC client: each OIDC client needs to be associated with a Hosted Login API client to help ensure that eventing information (such as each user login or each user social registration) is properly captured. The API client also helps render the login and registration screens, and help to drive the overall user experience.

Each OIDC client must be associated with an API client; if it’s not, logins, registrations, and profile management aren’t going to work. And note that the mapping between OIDC clients and API clients is one-to-one: each OIDC client can only be associated to one API client, and vice-version. This type of mapping is valid:

OIDC Client ID API Client ID
A 1
B 2
C 3

As you can see, each OIDC client is mapped to one API client, and each API client is mapped to one OIDC client. However, the following mapping type (in which API client 2 is mapped to three different OIDC clients) is not valid:

OIDC Client ID API Client ID
A 2
B 2
C 2

API Client Settings

If you have worked with the Akamai Identity Cloud in the past, most of the API client settings will be familiar to you: they’re the same settings you’ve used in the past to help configure user login and registration experiences. The one major exception to this rule is the janrainOidcClientId setting. This new, required setting ties your API client to an OIDC client. Needless to say, this setting must be present: without it, your API client is just an API client, and not a Hosted Login API client.

Incidentally, this is probably a good idea to reiterate that the OIDC client ID must be configured in the API client, as shown below

That means that you can look at the API client and instantly know which OIDC client it’s associated with. However, there’s no way to look at an OIDC client and be able to identify its associated API client. Things simply don’t work that way.

As indicated in the table below, some of the API client settings are required and some are not. In addition to indicating required settings and optional settings via the Required column, the table also includes a column labeled Can Inherit. If the Can Inherit setting is set to Yes, that means that the API client can inherit the setting from the global application settings. For example, if the rpx_key is configured at the application scope then you don’t have to configure that setting on the API client; instead, the setting will “inherit” the application scope setting.

What happens if you configure a setting at the application scope and then configure that exact same setting at the API client scope? In a case like that, the application value is ignored and the setting value explicitly assigned to the API client is used. For example:

Setting Applied at the Global Scope Setting Applied to the API Client Setting That is Actually Used
user_entity_type = user user_entity_type = user
user_entity_type = test user_entity_type = test
user_entity_type = user user_entity_type = user user_entity_type = user
user_entity_type = user user_entity_type = test user_entity_type = test

As you can see, the value set on the API client itself always take precedence.

If the Can Inherit column is set to No, that means that you must configure that value on the API client. If not, your API client will not function as expected (assuming that it even functions at all).

Here are the Hosted Login API client settings. Note that the highlighted rows represent custom settings; you’ll understand what that means when you read the section on configuring API client settings:

Setting Can Inherit Required

janrainOidcClientId

Unique identifier of the OIDC client associated with the API client (each OIDC client must be associated with one, and only one, API client). For example:
"janrainOidcClientId": "brg3q7xh8try6yy7clo09te24qaw487h5"

The ID of the OIDC client is configured in the API client. However, the reverse is not true: there is no setting in the OIDC client that identifies the associated API client. That means that you cannot examine the property values of an OIDC client and, from those values alone, determine the API client it’s associated with. Because of that, you might want to use a similar naming scheme for related OIDC and API clients. For example:

  • US Logins – Employees – OIDC Client
  • US Logins – Employees – API Client

That makes it easier to know which OIDC Client goes with which API client.

No Yes

user_entity_type

Identifies the entity type used by the OIDC client to store user profile data. For example:
"user_entity_type": "user"

Keep two things in mind here. First, each OIDC client can only be associated with one entity type. Second, that entity type must be based on a Hosted Login schema.

Yes Yes

default_flow_name

Name of the flow to be used by the associated OIDC client. For example:
"default_flow_name": "standard"

Standard is the name of the default flow provided for use with Hosted Login. You can use a different flow if you need to; however, this alternate flow must be based on standard. That’s because standard uses form and translation names that match the login, registration, and user profile screens employed by Hosted Login.

In the Console, you can find the name and version number of your flows by clicking Registration Builder.

Yes Yes

default_flow_version

Version number of the flow specified by the default_flow_name setting. For example:
"default_flow_version": "20190405205553900000"

In the Console, you can find the name and version number of your flows by clicking Registration Builder.

Yes Yes

password_reset_url

URL that enables a Customer Care Portal agent to initiate a password reset flow for the user. For example:
"password_reset_url": "https://v1.api.us.janrain.com/customers/
00000000-0000-0000-0000-000000000000/reset-password"

This setting is not required if you don’t use Customer Care Portal.

No Yes

theming.stylesheetURL

URL of CSS file associated with Hosted Login’s login, registration, and user profile pages. For example:
"theming.stylesheet": "https://documentation.akamai.com/custom-styles.css"

If not present, Hosted Login uses the defaukt stylesheet.

Yes No

theming.logoURL

URL of the logo displayed on Hosted Login pages. For example:
"theming.logoURL": "https://documentation.akamai.com/images/logo.svg"

Note that logos do not have to use the SVG file format. Other standard image formats (such as PNG or JPG) work just fine.

If not present, Hosted Logon uses the default Akamai logo.

Yes No

theming.faviconURL

URL of the favicon to be used on Hosted Login pages. For example:
"theming.faviconURL": "https://documentation.akamai.com/images/favicon.svg"

Note that favicons do not have to use the SVG file format. Other standard image formats (such as PNG or JPG) work just fine.

If not present, Hosted Logon uses the default Akamai favicon.

Yes No

rpx_key

API key for the Engage application used to enable social login. For example:
"rpx_key": "677fte5gftyoag56sd30sw2up572ec252cd3afnj"

In the Engage dashboard, you can find this value on the Application Settings page: it’s listed as API Key (Secret). In the Console, go to the Manage Application page, scroll down to the Global Settings section, and look for the value in the Social Login pane.

Yes No

rpx_realm

Domain name for the Engage application used to enable social login. For example:
"rpx_realm": "documentation-login"
In the Engage dashboard, you can find this value on the Application Settings page; it’s the domain name portion of the Application Domain setting. For example, suppose your Application Domain is this:
https://akamai-documentation.rpxnow.com 

In that case, akamai-documentation (highlighted in red above) is the rpx_realm.

In the Console, go to the Manage Application page, scroll down to the Global Settings section, and look for the value in the Social Login pane.

Yes No

rpx_id

Unique identifier of the Engage application used to enable social login. For example:
"rpx_id": "fdbppnbjfcbbijkmifkl"

In the Engage dashboard, you can find this value on the Application Settings page: it’s listed as App ID. In the Console, go to the Manage Application page, scroll down to the Global Settings section, and look for the value in the Social Login pane.

Yes No

regex_standard_newPassword

Specifies the regular expression (regex) used to validate user passwords. This value should match the regex validation added to the password field in the flow. For example:
"regex_standard_newPassword": ".*"
Yes No

authentication.providers

Array that specifies the social login identity providers (IdPs) available to a user who logs on to or registers with a website or application. For example, the following syntax makes two IdPs – Facebook and Twitter – available for social login/registration. Note that, because the set of available IdPs is passed as an array, each identity provider name must be enclosed in double quote marks, and the entire set must be enclosed by square brackets:
"authentication.providers": ["facebook", "twitter"]

Keep in mind that the authentication.providers setting only controls the display of the individual IdP buttons: configuring this setting does not mean users can login or register by using the referenced identity providers. Instead, you must:

  • Create login/registration apps for each identity provider.
  • Configure those identity providers in the Engage dashboard.
  • Add the API client settings (rpx_key, rpx_realm, rpx_app_id) that enable Hosted Login to access your Engage dashboard and retrieve social login information.

There are three different ways to use the authentication.providers setting:

  • Don’t include the authentication.providers setting in your API client settings. If this setting is not found, Hosted Login uses all of the social login identity providers defined in the Engage dashboard. For example, if your dashboard “widget” includes Facebook, Twitter, and LinkedIn, then all three of those IdPs will be available to users logging on to Hosted Login using the OIDC client associated with this API client.

  • Include the authentication.providers setting in your API client settings, and configure the setting value to a specified array of identity providers. For example, suppose you have three IdPs – Facebook, Twitter, and LinkedIn – configured in the Engage app. For the OIDC client associated with this API client, however, you only wanted to make LinkedIn available as a social login option. To do that, use this syntax:
    "authentication.providers": ["linkedin"]
  • Include the authentication.providers setting in your API client settings, but configure the setting value to a blank array. Setting authentication.providersto a blank array means that nosocial login identity providers will be available to users logging on to the site or app. To suppress all social login providers, use this syntax:
    "authentication.providers": []

See the article Configuring Social Loginfor more information.

Yes No

Creating a Hosted Login API Client

Creating an API client is a two-step process. First, you create a standard API client. This can be done either by using the Console or by using the /config/{application_id}/clientsendpoint. For example, this Curl command creates an API client named Documentation API Client:

curl -X POST \
  https://v1.api.us.janrain.com/config/pg65klnchge38jfhrs3c7pfww/clients \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj
4oBfuplftc7t
MbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/json' \
  -d '{
  "features": [
    "login_client"
  ],
  "ipWhitelist": [
    "0.0.0.0"
  ]
  "name": "Documentation API Client"
}'

Next, you’ll need to add API client settings and authorization rules to your new API client. Keep in mind, however, that you can’t add those settings until you know the ID of your OIDC client, and you can’t create an OIDC client until after you’ve created a login policy and a token policy. It’s probably best to make sure all these other components have been created and configured before you add API client settings to your client.

Configuring API Client Settings

When the time comes, you can use the /config/{application_id}/clients/{client_id}settings endpoint to link your API client to the new OIDC client. To do that, you need to add the setting janrainOidcClientId to the API client, and set the value of janrainOidcClientId to the ID of the OIDC client. At the same time, you should also add any other API client settings and authorization rules to the API client. For example:
curl -X PUT \
https://v1.api.us.janrain.com/config/pg65klnchge38jfhrs3c7pfww/clients/brg3q7xh8try6yy7clo09te24qaw48
7h5/settings \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc
6Qj4oBfuplftc7t
MbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/json' \
  -d '{
   "custom": {"janrainOidcClientId": "7de8f0e4-5112-4e67-9cf7-a735050e965b",
               "theming.stylesheet": "https://documentation.akamai.com/custom-styles.css",
              "theming.logoURL": "https://documentation.akamai.com/images/logo.svg",
              "theming.faviconURL": "https://documentation.akamai.com/images/favicon.svg"
   },
    "user_entity_type": "user",
    "default_flow_name": "standard",
    "default_flow_version": "20190405205553900000",
    "rpx_key": "677fte5gftyoag56sd30sw2up572ec252cd3afnj",
    "rpx_realm": "documentation-login",
    "rpx_id": "fdbppnbjfcbbijkmifkl"
}
'
When you do this, make sure that your custom settings, such as janrainOidcClientId, be enclosed within a master setting labeled custom (note the curly braces that enclose all the custom settings):
"custom": {"janrainOidcClientId": "7de8f0e4-5112-4e67-9cf7-a735050e965b",
    "theming.stylesheet": "https://documentation.akamai.com/custom-styles.css",
    "theming.logoURL": "https://documentation.akamai.com/images/logo.svg",
    "theming.faviconURL": "https://documentation.akamai.com/images/favicon.svg"
},
Custom settings must be specifically identified as such, and must be specifically formatted as shown above, in order to add them to an API client. Suppose you forget to do that, and you just add custom settings as if they were standard API client settings:
"janrainOidcClientId": "7de8f0e4-5112-4e67-9cf7-a735050e965b",
    "theming.stylesheet": "https://documentation.akamai.com/custom-styles.css",
    "theming.logoURL": "https://documentation.akamai.com/images/logo.svg",
    "theming.faviconURL": "https://documentation.akamai.com/images/favicon.svg",

If you run the preceding the API call, that call will run just fine and no error will be generated. However, the custom settings will simply be ignored and will notbe added to the API client. Custom settings must be identified as being, well, custom.

Here’s another gotcha to watch out for when working with API client settings. When you use the PUT method to add settings to a client, PUT actually replaces all the existing settings with whatever you’ve specified in the body parameter. Is that important? Well, suppose you have an API client with the following settings:
"janrainOidcClientId": "7de8f0e4-5112-4e67-9cf7-a735050e965b",
"theming.stylesheet": "https://documentation.akamai.com/custom-styles.css",
"theming.logoURL": "https://documentation.akamai.com/images/logo.svg",
"theming.faviconURL": "https://documentation.akamai.com/images/favicon.svg".
"user_entity_type": "user",
"default_flow_name": "standard",
"default_flow_version": "20190405205553900000",

"rpx_key": "677fte5gftyoag56sd30sw2up572ec252cd3afnj",     
"rpx_realm": "documentation-login",     
"rpx_id": "fdbppnbjfcbbijkmifkl"

You now decide to add the password_reset_url setting. With that in mind, you make the following API call, one that specifies only the new setting:

curl -X PUT \ 
https://v1.api.us.janrain.com/config/pg65klnchge38jfhrs3c7pfww/clients/brg3q7xh8try6yy7clo09te24qaw487
h5/settings \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6
Qj4oBfuplftc7
tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/json' \
  -d '{
    "password_reset_url": "https://documentation.akamai.com/reset-password"
}
'
When your API call completes, your API client will have the following client settings:
"password_reset_url": "https://documentation.akamai.com/reset-password "

Why just the one setting? That’s right: because the PUT method replaced all your old settings with the newly-specified settings. Because you only had one new setting, the API client now has just that one lone setting.

In other words, any time you update API client settings you must specify all the settings that you want the client to have. For example:
curl -X PUT \
https://v1.api.us.janrain.com/config/pg65klnchge38jfhrs3c7pfww/clients/brg3q7xh8try6yy7clo09te24qaw487h
5/settings \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Q
j4oBfuplftc7
tMbR2
6eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/json' \
  -d '{
   "custom": {"janrainOidcClientId": "7de8f0e4-5112-4e67-9cf7-a735050e965b",
               "theming.stylesheet": "https://documentation.akamai.com/custom-styles.css",
              "theming.logoURL": "https://documentation.akamai.com/images/logo.svg",
              "theming.faviconURL": "https://documentation.akamai.com/images/favicon.svg"
   },
    "user_entity_type": "user",
    "default_flow_name": "standard",
    "default_flow_version": "20190405205553900000",

"rpx_key": "677fte5gftyoag56sd30sw2up572ec252cd3afnj",
    "rpx_realm": "documentation-login",
    "rpx_id": "fdbppnbjfcbbijkmifkl"
    "password_reset_url": "https://documentation.akamai.com/reset-password "
}
'

One suggestion? If you’re going to add a new setting or two to a API client, start by returning all the current client settings, then copying and pasting them into your new API call (the one you’re using to add the new settings). Add the new settings to the old settings and then make the API call.

And if you want to delete a setting from a API client? Just remove that setting from the body parameter before making your API call. For example, this command doesn’t include the password_reset_url parameter. Consequently, when you make this call the password_reset_url parameter will be deleted from the API client:
curl -X PUT \
https://v1.api.us.janrain.com/config/pg65klnchge38jfhrs3c7pfww/clients/brg3q7xh8try6yy7clo09te24qaw487h
5/settings \
  -H 'Authorization: Basic RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Q
j4oBfuplftc7
tMb
R26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/json' \
  -d '{
   "custom": {"janrainOidcClientId": "7de8f0e4-5112-4e67-9cf7-a735050e965b",
               "theming.stylesheet": "https://documentation.akamai.com/custom-styles.css",
              "theming.logoURL": "https://documentation.akamai.com/images/logo.svg",
              "theming.faviconURL": "https://documentation.akamai.com/images/favicon.svg"
   },
    "user_entity_type": "user",
    "default_flow_name": "standard",
    "default_flow_version": "20190405205553900000",
     "rpx_key": "677fte5gftyoag56sd30sw2up572ec252cd3afnj",
    "rpx_realm": "documentation-login",
    "rpx_id": "fdbppnbjfcbbijkmifkl"
}
'

Adding API Client Settings by Using Console

Alternatively, you can use the Console to add API client settings to a Hosted Login API client. To do that, complete the following procedure:

  1. In Manage Properties, click the Add Setting icon:
  2. To add a standard setting, in the Edit Settings pane, click Select setting key and then click the setting you want to add:

    Depending on the situation, some of the setting names in the dropdown list might be grayed-out. That means that those settings are already in your list of settings, having been previously-configured at either the global or the property scope.

  3. In the Value field, enter the value for the new setting:
  4. To add a custom setting, type the setting name in the Select setting key field:
  5. As you type, the setting name appears in the Create setting button located just above the new setting. Click (in this example) Create janrainOidcClientId:
  6. Type the value for the custom setting in the Value field:
  7. Repeat this process as needed to add all the necessary settings. When you are finished adding new settings, click the Save Changes icon: