Create a Hosted Login configuration client

Unlike public clients and confidential clients, configuration clients have nothing to do with user logins and registrations. Instead, configuration clients help you obtain the configuration access tokens needed to call the OpenID Connect (OIDC) Configuration APIs. When you request a configuration token, you need to use Basic authentication and provide a client ID and client secret as your user name and password. For example::

That client ID and client secret must come from a configuration client.

When your first subscribe to the Identity Cloud you’ll be given a configuration client and a token policy (if you weren’t given those items then you wouldn’t be able to call any of the OIDC Configuration APIs). That initial configuration client might be all you need. On the other hand, you might want to create, and use, other configuration clients; if nothing else, that way you won’t inadvertently delete your only configuration client, a disaster that would prevent you from obtaining configuration tokens.

Fortunately, creating a configuration client is pretty easy: all it takes is one simple API call. Just remember that, in order to make this one API call, you’ll first need to be issued a configuration token. That means you need to use an existing configuration client to obtain the token that lets you create a new configuration client. But, really, that’s as tricky as it gets.

📘

We won’t bother explaining how to get a configuration token in this article. But that’s OK: the article Get an administrative access token walks you through the process, step-by-step.

Let’s assume that you’ve obtained your token and are ready to begin. To create a configuration client, use the /{customerId}/config/clients operation and the POST method. For example, a Curl command to create a configuration client looks something like this

curl -X POST \
  https://v1.api.us.janrain.com/g/01000000-0000-3000-9000-000000000000/config/clients/fd72dfd7-3ad8-4237-a74d-013e04ae947c \
  -H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Akamai Documentation Configuration Client",
    "redirectURIs": [
        "http://127.0.0.1"
    ],
    "tokenPolicy": "48e04957-2d89-414e-bfcd-5ca6298a2f07",
    "type": "confidential"
}'

If you’re wondering what those parameters actually do (and how you configure them), the following table should answer your questions:

If your POST call succeeds you’ll get back property values for your new configuration client:

{
   "id": "bccf1068-43a1-4fd5-a9e7-dac6a8b5c67e",
   "name": "Akamai Documentation Configuration Client",
   "redirectURIs": [
       "http://127.0.0.1"
   ],
   "loginPolicy": null,
   "tokenPolicy": "48e04957-2d89-414e-bfcd-5ca6298a2f07",
   "type": "confidential",
   "_links": {
       "self": {
           "href": "/config/e0a70b4f-1eef-4856-bcdb-f050fee66aae/clients/bccf1068-43a1-4fd5-a9e7-dac6a8b5c67e"
       }
   },
   "secret": "cATXBlpxsL8OQqnCF3QSm-4YBtLUi-0vobBOWWwbVUeXOUPlzSipJ7tqYolQQtiaH8C_A9KsczxjSsmiEladWw"
}

Notice the secret property at the bottom of the API response? That’s your client secret, and we point this out simply because, if you do fail to make a note if it, the secret can be a little tricky to find again. For example, suppose you disregarded our advice and forgot to note the client secret. But you’re not worried: after all, you can just use the GET method to return the properties of the configuration client (and yes, the client secret is a property of a configuration client), right?

Uh, no, no exactly. Instead, here’s what you’ll get back when you call the GET method:

{
   "id": "bccf1068-43a1-4fd5-a9e7-dac6a8b5c67e",
   "name": "Akamai Documentation Configuration Client",
   "redirectURIs": [
       "http://127.0.0.1"
   ],
   "loginPolicy": null,
   "tokenPolicy": "48e04957-2d89-414e-bfcd-5ca6298a2f0",
   "type": "confidential",
   "_links": {
       "self": {
           "href": "/config/e0a70b4f-1eef-4856-bcdb-f050fee66aae/clients/bccf1068-43a1-4fd5-a9e7-dac6a8b5c67e"
       }
   }
}

If you’re looking for the client secret, we’ll save you the trouble: it’s not there. Returning the properties of a configuration client doesn’t return the client secret after all. If you need to look up the client secret, you’ll have to use the /config/{customerId}/clients/{oidcClientId}/secret operation instead:

curl -X POST \
  'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/clients/bccf1068-43a1-4fd5-a9e7-dac6a8b5c67e/secret' \
  --header 'Authorization: Bearer mjqC8wHYcxW6d4gxGolsfp3nSSmxX10DJbQUz0OD2JqNV3M44BmDOebotEOalUIF'

That API call does return the client secret:

{
   "secret": "cATXBlpxsL8OQqnCF3QSm-4YBtLUi-0vobBOWWwbVUeXOUPlzSipJ7tqYolQQtiaH8C_A9KsczxjSsmiEladWw"
}

Not a big deal, but something you need to know.

After you have the client ID and client secret you can use those values to configure Basic authentication and begin using your new configuration client to return configuration access tokens: