Application Clients and Client Settings

Application clients help provide a seamless interaction between the brave new world of OAuth and OpenID Connect and the rest of the Identity Cloud infrastructure. For example, the application client contains the name and version number of the Identity Cloud flow used to manage user logins and registrations. The application client also provides links to the stylesheets, fonts, logos, and authorization rules that you can use to customize the user experience.

That’s important (and necessary) information, which explains why each OIDC client used for logins and registrations must be associated with an application client. No exceptions.

Unlike OIDC login clients, application clients are instances of Identity Cloud API clients: each application client is an API client configured with the login_client feature. As such, application clients can  be modified by using either Console or the Identity Cloud Configuration APIs; however, you should not use Console (or the APIs) to create or delete application clients. For more information on why that’s a bad idea (which it is), see the section How Not to Create and Delete Application Clients.

Fortunately, you don’t have to worry about creating or deleting application clients: instead, applications clients are automatically created when you create a new OIDC login client, and are automatically deleted when you delete an OIDC client. However, you will need to manage the client settings used by your application client. By default, the following client settings are created (and configured) at the time an application client is created:

  • janrainOidcClientId. The UUID of the confidential/public client that the application client is associated with. You can’t change this value, which is for the best: if you could change it, and did, you’d break the link between the application client and the OIDC client.
     
  • user_entity_type. By default, this is set to user, meaning that users of this client have their profiles stored in the user entity type. However, you can change this to any valid entity type, provided that it’s the same entity type mentioned in the login policy associated with the OIDC client. In other words, the entity type referenced in the login policy must be the same entity type referenced in the application client.
     
  • password_recover_url. The URL used when generating a password reset link. For an OpenID Connect implementation, use the following format to construct your password recover URL:
{base_url}/{CustomerID}/auth-ui/reset-password?client_id={OIDC client_id}

For example, suppose your Identity domain URL is https://v1.api.us.janrain.com, your customer ID number is 01000000-0000-3000-9000-000000000000, and your confidential/public client ID is 07e4b6e4-4a6f-4825-94fe-8a7bc57196c1. In that case, the password_recover_url should be set to this:

https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/auth-ui/reset-password?client_id=07e4b6e4-4a6f-4825-94fe-8a7bc57196c1

If this value is not configured users won’t be able to reset a forgotten password.

  • verify_email_url. The  URL used when generating an email verification link. For an OpenID Connect implementation, use the following format to construct your email verification URL:
{base_url}/{CustomerID}/auth-ui/verify-account?client_id={OIDC client_id}

For example, suppose your base URL is https://v1.api.us.janrain.com, your customer ID number is 01000000-0000-3000-9000-000000000000, and your confidential/public client ID is 07e4b6e4-4a6f-4825-94fe-8a7bc57196c1. In that case, the verify_email_url should be set to this:

https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/auth-ui/verify-account?client_id=07e4b6e4-4a6f-4825-94fe-8a7bc57196c1

If this value is not configured users won’t be able to verify their email addresses, which means that your Hosted Login sign-in screen won't be displayed. As a result, users won't be able to log on.

Note that it's possible to add a redirect_uri parameter to your email verification URL; for example:

https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/auth-ui/verify-account?client_id=07e4b6e4-4a6f-4825-94fe-8a7bc57196c1&redirect_uri=https://identitydocs.akamai.com

In the preceding example, after a user initially verifies his or her email address, that user is redirected to the page https://identitydocs.akamai.com.

However (and this is an important however), this redirection only occurs when the user verifies their email address as part of the registration flow. By contrast, suppose a user decides to change an email address that's already been verified. If a user updates a verified email address redirection will not work; instead, after verifying the address the user is presented with a Something went wrong error:


If you choose to include the redirect_uri parameter in your verify_email_url you'll need to trap for this error any time a user changes their email address in their user profile. If that can't be done, then it's probably best not to include redirect_uri in your email verification URL.

If not already present you should also add the following settings to your application client:

  • default_flow_name. Name of the flow to be used with the login/registration process. For example
"default_flow_name": "hostedLogin"

If this setting is not included then Hosted Login will default to using the standard flow (assuming, of course, that a flow by that name exists).

  • default_flow_version. Version number of the flow used with the login/registration process. For example:
"default_flow_version": "20190720205552725054"

If you’d prefer to always use the latest version of a flow, set default_flow_version to HEAD:

"default_flow_version": "HEAD"

The advantage of using HEAD is that you never need to change the flow version; if you update the flow the application client will automatically use the latest version. However, that’s also the disadvantage of using HEAD: if you modify the flow and there turns out to be some problems with that version, Hosted Login will nevertheless use the latest version, problems or no problems. As a general rule, HEAD is good for testing and development scenarios: that way you don't have to constantly update your application client each time you make a change to the flow. However, HEAD is not recommended for production scenarios. Instead, wait until you've made and verified all your flow changes, and then go in and update the default_flow_version setting.

Because application clients are API clients, settings can be managed either by using Console or by using the /config/{appId}/clients/{client_id}/settings API endpoint. If you decide to use the /settings endpoint to manage your application client settings (that is, add new settings, modify or delete old settings) keep in mind that each time you call the PUT method you must include all the settings that need to be in the application client. For example, suppose your application client settings look like this:


{
    "password_recover_url": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/reset-password?client_id=5847606e-bb5b-48d9-b1ea-4fccabd5f6ae",
    "_global": {
        "email_sender_address": "\"Identity Cloud Documentation\" <noreply@janrain.com>",
        "rpx_server": "https://rpxnow.com",
        "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/settings",
        "email_method": "ses_sync",
        "custom": {}
    },
    "site_name": "Akamai Documentation Public Client",
    "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/clients/szjprfpwkt4thw8e95x99upj67ykrswe/settings",
    "verify_email_url": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/verify-account?client_id=5847606e-bb5b-48d9-b1ea-4fccabd5f6ae",
    "custom": {
        "janrainOidcClientId": "5847606e-bb5b-48d9-b1ea-4fccabd5f6ae"
    },
    "user_entity_type": "GREG_DEMO"
}

You now decide to add the default_flow_name and the default_flow_version. With that in mind, you make an API call that – as far as you know – adds those two settings to the client:


curl -X PUT ]\ 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/links/linkHelp' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
  --data-raw '{
    "default_flow_name": "standard",
    "default_flow_version": "HEAD"
}'

And here’s what your API client settings look like after you make that API call:


{
    "default_flow_name": "standard",
    "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/clients/szjprfpwkt4thw8e95x99upj67ykrswe/settings",
    "default_flow_version": "HEAD",
    "_global": {
        "email_method": "ses_sync",
        "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/settings",
        "email_sender_address": "\"Identity Cloud Documentation\" <noreply@janrain.com>",
        "rpx_server": "https://rpxnow.com",
        "custom": {}
    },
    "custom": {
        "janrainOidcClientId": "5847606e-bb5b-48d9-b1ea-4fccabd5f6ae"
    }
}

If you look closely, you’ll see that default_flow_name and default_flow_version were both added to the client settings; those settings also retain and global settings (i.e., values set at the application level) and any custom settings. But all your other settings – including password_recover_url, site_name, verify_email_url, and user_entity_type – are gone. What happened here?

What happened is that none of those four settings were included in your API call; consequently, they were removed from the application client. That’s because the PUT command functions as a replace command: it replaces all the existing settings with the settings found in the body parameter of this call. And that’s exactly what happened.

Note. The global settings survived because they can only be changed at the application level. And your custom setting – janrainOidcClientId – didn’t get deleted because you can’t delete that setting.

To ensure that all your existing settings are retained, your body parameter should look like this (with the two new settings marked in red):


{
    "default_flow_name": "standard",
    "default_flow_version": "HEAD",    
    "password_recover_url": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/reset-password?client_id=5847606e-bb5b-48d9-b1ea-4fccabd5f6ae",
    "_global": {
        "email_sender_address": "\"Identity Cloud Documentation\" <noreply@janrain.com>",
        "rpx_server": "https://rpxnow.com",
        "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/settings",
        "email_method": "ses_sync",
        "custom": {}
    },
    "site_name": "Akamai Documentation Public Client",
    "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/clients/szjprfpwkt4thw8e95x99upj67ykrswe/settings",
    "verify_email_url": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/verify-account?client_id=5847606e-bb5b-48d9-b1ea-4fccabd5f6ae",
    "custom": {
        "janrainOidcClientId": "5847606e-bb5b-48d9-b1ea-4fccabd5f6ae"
    },
    "user_entity_type": "GREG_DEMO"
}

Our recommendation for using the Configuration APIs to modify client settings? Use the GET method to return the current collection of settings, and paste that information into the body parameter of your PUT call. And then add or modify any settings as needed before actually making your API call.

Or use the Console to make your changes. The you don’t have to worry about copying and pasting.

By the way, the settings mentioned so far are mandatory, but there are other settings that can be added to an application client that are extremely good to know about. Those settings are summarized in the table below.

Hosted Login Application Client Settings

Back to top

Setting

Can Inherit

Required

janrainOidcClientId

Back to top

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"

You cannot change or delete this value.

No

Yes

user_entity_type

Back to top

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

"user_entity_type": "user"

Keep three things in mind here

  • Each OIDC client can only be associated with one entity type.
  • Your entity type must be based on a Hosted Login schema. You will run into problems if you use a custom schema that does not include all the fields required by Hosted Login.
  • The entity type specified in the application client must be the same entity type specified in the login policy.

Yes

Yes

default_flow_name

Back to top

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 using Registration Builder.


Yes

Yes

default_flow_version

Back to top

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 using Registration Builder.

In case you're wondering, yes, it's valid to set the flow version to HEAD; if you do that, Hosted Login will automatically use the latest version of the specified flow. Using HEAD is fine for your development work; as a general rule, however, we discourage the use of HEAD in a production environment. 

Why? Well, remember each time you make a change (and save) to a flow a new version of the flow is created; if default_flow_version is set to HEAD Hosted Login will automatically use that new version. That's fine ... if the new version is complete and if the new version actually works. Suppose you make a change to your flow and that flow breaks. If Hosted Login is using a specified version number, no problem: Hosted Login will continue to that version number. But if Hosted Login is set to HEAD it will begin to use the new, and broken, flow, which could lead to any number of problems.

Yes

Yes

theming.stylesheetURLs

Back to top

URL of CSS file associated with Hosted Login’s login, registration, and user profile pages. For example:

"theming.stylesheetURLs": "https://documentation.akamai.com/custom-styles.css"

If not present, Hosted Login uses the default CSS stylesheet.


Yes

No

theming.logoURL

Back to top

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

Back to top

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

theming.fontURLs

Back to top

URLs for additional font files that that can be used on Hosted Login pages. For example:

"theming.fontURLs": "https://fonts.google.com/css?family=Open+Sans"


Yes

No

rpx_key

Back to top

API key for the Social Login application used to enable social login. For example:

"rpx_key": "677fte5gftyoag56sd30sw2up572ec252cd3afnj"

In the Social Login 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

Back to top

Domain name for the Social Login application used to enable social login. For example:

"rpx_realm": "documentation-login"

In the Social Login 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_appid

Back to top

Unique identifier of the Social Login application used to enable social login. For example:

"rpx_appid": "fdbppnbjfcbbijkmifkl"

In the Social Login 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

Back to top

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": ".*"
The regular express simply means that, other than a linebreak character, you can use any characters (and any number of characters) in your password.


Yes

No

site_name

Back to top

Name of the Hosted Login login page; by default, this is the same name assigned to your OpenID Connect client. For example:

"site_name": "Akamai Documentation"


Yes

No

authentication.providers

Back to top

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 Social Login 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 Social Login dashboard. 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 no social 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 Login for more information. 

Yes

No

authentication.captureui_domain

Back to top

Specifies the domain to be employed when making requests to a Capture application. This is an advanced setting that should only be used when Akamai has configured a CNAME for your Capture application. Check with your Identity Cloud representative before adding and configuring this setting. 

For example:

"authentication.captureui_domain": "mydomain.janraincapture.com"

You should use only the domain name (e.g., mydomain.janraincapture.com) when configuring the value for this setting: don't include the domain protocol (e.g., https://)

Yes

No

authentication.second_factor

Back to top

In Hosted Login v2, enables and disables two-factor authentication (2FA). To enable 2FA, set the value of this setting to true; to disable 2FA, set the value of the setting to false.

Yes
No
authentication.second_factor.trust_device_ttl
Back to top

Sets the time-to-live (TTL) value for trusted devices in Hosted Login v2. By default, the trusted device TTL is 30 days: after a device has been trusted, you're allowed to bypass two-factor authentication for 30 days (provided, of course, that you're logging on with the trusted device).

The trusted device TTL is configured in seconds; for example, the value 604800 sets the trusted device time-to-live to 7 days (7 days x 24 hours per day x 60 minutes per hour x 60 seconds per minute). Setting the value to 0 effectively eliminates the use of trusted devices, and forces users to go through two-factor authentication each time they log on.

If this value is not present in the application client then the default TTL of 30 days is used.

Yes
No



How Not to Create and Delete Application Clients

Back to top

There’s nothing particularly-special about application clients: in fact, and as we noted earlier, application clients are standard-issue Identity Cloud API clients and, as such, can be managed by using either the Identity Cloud Configuration APIs or by using Console.

Note. In this case we’re talking about the “regular” Configuration APIs, not the OpenID Connect Configuration APIs.

That said, however, you should never use the Identity Cloud Configuration APIs or the Console to create or delete application clients: doing that breaks the tie between an application client and its associated OIDC client. And that’s likely to lead to problems later on down the road.

So how should you go about creating and deleting application clients? To be honest, you shouldn’t go about creating and deleting application clients. Instead, you should let the OIDC client endpoints do that work for you.

At the risk of repeating ourselves, any time you create an OIDC client (either a confidential client or a public client) an application client is automatically created for you, and is automatically assigned to the new client. That’s the way that you create an application client: create an OIDC client, and you get the associated application client for free.

Note. Before you ask, no, there’s no way to manually specify the application client associated with an OIDC client; it simply can't be done. When you create an OIDC client that client is automatically associated with a specific application cliebnt, and the two remain inextricably tied together, till death do them part.

You should use a similar approach if you need to delete an application client. Admittedly, it looks like it's possible to use the Configuration APIs to directly delete the application client: that deletes the client and removes the client from its associated OIDC client. For example, consider the property values for a sample OIDC client:


{
    "id": "07e4b6e4-4a6f-4825-94fe-8a7bc57196c1",
    "name": "Test Application Client",
    "redirectURIs": [
        "https://localhost"
    ],
    "loginPolicy": "2ffc9cfe-e0eb-4c44-9253-063670febece",
    "tokenPolicy": "002a99a8-f890-4fe0-baa4-e5112b9e3b40",
    "type": "public",
    "_links": {
        "self": {
            "href": "/01000000-0000-3000-9000-000000000000/config/clients/07e4b6e4-4a6f-4825-94fe-8a7bc57196c1"
        },
        "application_client": {
            "href": "/config/kfcmdfudasmx9wkay7463vpdsy/clients/4678p9t6apgchzamuvqzx75pm3zt3pcm"
        }
    
}
 

If you delete the application client then the application_client setting will be removed from the OIDC client as well:

{
    "id": "07e4b6e4-4a6f-4825-94fe-8a7bc57196c1",
    "name": "Test Application Client",
    "redirectURIs": [
        "https://localhost"
    ],
    "loginPolicy": "2ffc9cfe-e0eb-4c44-9253-063670febece",
    "tokenPolicy": "002a99a8-f890-4fe0-baa4-e5112b9e3b40",
    "type": "public",
    "_links": {
        "self": {
            "href": "/01000000-0000-3000-9000-000000000000/config/clients/07e4b6e4-4a6f-4825-94fe-8a7bc57196c1"
        }
    }
} 

That all seems to be fine, but, again, there’s a problem: as we noted a moment ago, there’s currently no way to manually assign an application client to an OIDC client. Application clients are associated with an OIDC client at the same time the OIDC client is created. If that association is broken, there’s no way to restore it, and no way to associate the OIDC client with a different application client. You'll now have an OIDC login client that isn't assoicated with an application client, meaning that this login client can no longer be used for logins and registrations. 

What that boils down to is tthis: if you want to delete an application client then you should delete its associated OIDC client and not the application client. Deleting the OIDC client automatically deletes the application client as well, and without leaving your setup in an indeterminate state (that is, without having some OIDC clients that are no longer associated with an application client, and without having some application clients that are no longer associated with an OIDC client). 

Note. But what if you really want to associate an OIDC client with a different application client? Well, consider what that means. Most likely you don’t want your OIDC client to be specifically associated with application client 4678p9t6apgchzamuvqzx75pm3zt3pcm. Instead, you probably want your OIDC client to use the same configuration settings and the same authorization rules as client 4678p9t6apgchzamuvqzx75pm3zt3pcm uses. If that’s the case then the solution is simple: copy the settings and authorization rules used in client 4678p9t6apgchzamuvqzx75pm3zt3pcm, and paste those values into the application client already associated with your OIDC client. That’s all you need to do.