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 operation. If you decide to use the /settings operation 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.

📘

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:

{
 "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

How not to create and delete application clients

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.

📘

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

📘

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 client, 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 associated with an application client, meaning that this login client can no longer be used for logins and registrations. 

What that boils down to is this: 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). 

📘

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.