Contact Akamai Support If You Need to Change an Owner Client Secret

Important. It's highly-recommended that you contact Akamai support (or your Identity Cloud representative) before you change the client secret for an owner client. That's because changing an owner client secret can have repercussions that go beyond simply assigning a new secret to the client. Note that this is especially true for organizations running Hosted Login. 


The Akamai Identity Cloud supports different types of API clients, which enables you to provide different levels and types of access to key features of the Identity Cloud itself (for example, different access levels to the Identity Cloud REST APIs). Each API client has, among other properties:

  • A client feature, which defines the type of client you’re working with.
  • A client ID.
  • A client secret. 

The latter two properties (the client ID and the client secret) function as the API client’s username and password when making API calls.

The most powerful API client type is the owner client, a client that can be used to call any of the Identity Cloud REST APIs. For example, you can use any API client type (including the login client) to view a user profile. But suppose you want to create a user profile or you want to delete a user profile? In that case, you have no choice but to use an owner client: nothing else will work.

As noted, all API clients (including owner clients) have a client secret that serves as the client password. In theory (and we’ll explain what that means in a moment) you can change this password any time you want; for example, if you access the client (aka property) in Console you can change an owner client password simply by clicking Reset Secret, and then confirming that you want to change the secret. Just like that, your owner client will have a new secret:

So why would you ever want to change an owner client secret? Well, sometimes you might have no choice: inadvertently (or otherwise) that secret might have been leaked to the outside world. Alternatively, you might want to change the secret as a security precaution whenever someone who had access to the secret leaves your organization. And, of course, many organizations have adopted a “password rotation” policy, in which passwords are periodically changed, just to be on the safe side.

Unfortunately, however, changing an owner secret can have some unexpected – and unwelcome – ramifications. For example, if you’re running Hosted Login each of your OpenID Connect (OIDC) login clients must be associated with a login policy. In turn, each login policy must have an owner client ID and client secret embedded in the policy definition. For example:

"identityStoreDetails": {
  "type": "janrainCapture",
  "connectionDetails": {
    "domain": "se-demos-gstemp.us-dev.janraincapture.com",
    "applicationId": "79y4mqf2rt3bxs378kw5479xdu",
    "entityType": "GREG_DEMO",
    "clientId": "7ns3pxeq92eghsqfu5sanshe939vmrjm",
    "clientSecret": "6kr5746q7e4ex2gfedp8ehzjemwjjsqe"
  }

This is one place where changing an owner client secret can lead to trouble. When the preceding login policy was created, it referenced an owner client with the client ID 7ns3pxeq92eghsqfu5sanshe939vmrjm and the client secret 6kr5746q7e4ex2gfedp8ehzjemwjjsqe. And that’s great: because of that, any OIDC client that uses the login policy can register and log in users.

But suppose you change the client secret, suppose that, instead of 6kr5746q7e4ex2gfedp8ehzjemwjjsqe, your owner client now has the client secret 2s277py2cv4ffg6vfwwjb2yf762tpfmv. That’s a problem. When a user accesses your Hosted Login sign-in screen they’ll be able to see the screen and they'll be able to enter their username and password:

However, when the user clicks Sign In they won’t be logged on to Hosted Login. Instead, the sign-in screen will simply reset itself:

And if the user tries to log in again, the same thing will happen ah=gain: instead of logging them in, the sign-in screen simply resets itself.

As you might have guessed, the problem lies with the new owner client secret: the owner client now has the secret 2s277py2cv4ffg6vfwwjb2yf762tpfmv, but the login policy still uses the old client secret of 6kr5746q7e4ex2gfedp8ehzjemwjjsqe. Because it’s presenting the wrong client secret, the login policy can’t be authenticated. And because the login policy can’t be authenticated that means that the user can’t be authenticated, either.

Of course, one easy way to fix this problem would be to update the login policy with the new client secret. Unfortunately, however, that won’t work: the client secret is part of the identiyStoreDetails property and that property can’t be modified – period. Yes, you can try to update the client secret, but when you do that your API call is bound to fail with the following error:

{
  "errors": "identityStoreDetails cannot be changed"
}

Which means that, at this point, your login policy is effectively useless: you can’t change the client secret in the login policy, and you can’t reset the owner client secret back to the original secret. In fact, the only thing you can do is create a new login policy and assign the new policy to all the API clients that used the previous login policy. And all because you changed the owner secret.

Oh, and keep in mind that this is only one example of the kind of domino effect that can occur if you change an owner client secret; you might run into other issues. And that’s why it’s highly recommended that you talk to someone from Akamai before changing an owner client secret.