Modify an OpenID Connect Client

Endpoint URL: {identityDomain}/{customerId}config/clients/{oidcClientId}


Description

Modifies the specified OpenID Connect (OIDC) client. When modifying OIDC clients remember that:

  • You cannot modify an OIDC client’s client secret by using the PUT method. If you need to change a client secret, use the /secret endpoint instead.
  • You cannot change the client type: once a public client always a public client.
  • If you have multiple applications, and if you have liked-name OIDC clients in each application (e.g., an OIDC client named My OIDC Client in application A and in Application B), you must be especially careful when modifying either of those clients. See the note at the end of this article for more information.

Video: Adding a Redirect URI


Respects the API Client Allow List:  No


Authentication

This endpoint requires token-based authentication. To obtain an access token, you must use a configuration client (using the client ID as the username and the client secret as the password) to access the /{customerId}/login/token endpoint. The access token returned from the token endpoint is then used in the Authorization header of your API call. For example, if you get back the access token Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB then your Authorization header would look like this when using Curl:

-H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'

In Postman, set the Authorization Type to Bearer and use the access token as the value of the Token field.

Path Parameters

The path parameters that must be included in the request are listed in the following table:

NameTypeRequiredDescription

{customerId}

string

Yes

Unique identifier of the customer associated with the OIDC client.

{oidcClientId}

string

Yes

Unique identifier of the OIDC client being modified.


Request Parameters

Request parameters for this endpoint must be formatted as a JSON object and included in the body parameter of your API call. For example: 

{
    "name": "Akamai Documentation Login",
    "redirectURIs": ["https://localhost"],
    "loginPolicy": "b8097975-93c7-46db-8cfe-19609e67eadb",
    "tokenPolicy": "2dcae965-0d56-4961-a98e-f98583e30bb9",
    "type": "public"
}

The keys and key values used in the body parameter include the following:

KeyDescription

name

Friendly name to be assigned to the OIDC client. The OIDC client name also serves as the title for the Hosted Login login page.

For example:

"name": "Akamai Documentation Client"

Incidentally, client names must be unique for each organization (i.e., for each customer ID). If your customer ID is 01000000-0000-3000-9000-000000000000 you can have only one OIDC client named Akamai Documentation Client.

Incidentally, changing your the name of an OIDC client also changes the value of the site_name setting found in the associated application client. See this article for more information about what that means, and what you might want to do about that.

redirectURIs

URL of the page the user is redirected to following authentication. The redirect URI accepts both HTTPS links and mobile deep links; however, the only allowed HTTP link is localhost:

"redirectUris": ["http://localhost"]‘

As the name implies, you can specify multiple redirect URIs; just include each URI in double quotes and separate the URIs by using commas:

"redirectUris": ["http://localhost", "https://documentation.akamai.com"]

When requesting authentication (or when exchanging an authorization code for a set of tokens), that request must include one of the URIs specified in the redirectUris key. If it doesn’t, your request will fail.

Note that your redirect URI can contain any query parameters except for code and state.

loginPolicy

Unique identifier of the login policy associated with the client. Login policies do such things as: 1) provide the exact path to the Capture domain and the user profile entity type; 2) specify the allowed OAuth scopes; and, 3) point the user to the appropriate login page.

For example:

"loginPolicy": "b8097975-93c7-46db-8cfe-19609e67eadb"

Login policies are required for both public clients and confidential clients: you can’t login or register using an OIDC client that hasn’t been assigned a login policy. Login policies are not required for configuration clients. However, after a login policy has been assigned to a client that client must always have a login policy: the only way to remove a login policy assigned to a client is to assign that client a new policy.

See this article for more information.

tokenPolicy

Unique identifier of the token policy associated with the client. Token policies are primarily used to specify the time-to-live value for refresh tokens.

For example:

"tokenPolicy": "2dcae965-0d56-4961-a98e-f98583e30bb9"

All OIDC clients must be assigned a token policy. The only way to "remove" a token policy from a client is to assign that client a different policy.

type

Specifies the type of OIDC client being modified. Allowed values are:

  • confidential
  • public

Although the type parameter is required in your API call, you cannot change the client type (e.g., you can’t convert a confidential client into a public client or vice-versa). 

You must include all the keys and key values in your body request, even if those values are not being changed. For example, suppose you leave out the key value redirectURIs. In that case, your API call will fail with a 400 Bad Request error and the following error message:

{
   "errors": "('redirectURIs',) field required"
}


Sample Request (Curl)

The following command changes the name of the OIDC client with the client ID 6be73a3a-5bf0-4190-a0de-698aa409ff28. Although only the name is being changed, all the other keys and key values (such as tokenPolicy) must be included in the body parameter:

curl -X PUT \
  https://v1.api.us.janrain.com//01000000-0000-3000-9000-000000000000/config/clients/6be73a3a-5bf0-4190-a0de-698aa409ff28 \
  -H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Akamai Training Login Client",
    "redirectURIs": ["https://localhost"],
    "loginPolicy": "b8097975-93c7-46db-8cfe-19609e67eadb",
    "tokenPolicy": "2dcae965-0d56-4961-a98e-f98583e30bb9",
    "type": "public"
}'


Responses

200 OK

If your call to this endpoint succeeds, you'll get back updated information for the newly-modified OIDC client:

{
    "id": "6be73a3a-5bf0-4190-a0de-698aa409ff28",
    "name": "Akamai Training Login Client",
    "redirectURIs": ["https://localhost"],
    "loginPolicy": "b8097975-93c7-46db-8cfe-19609e67eadb",
    "tokenPolicy": "2dcae965-0d56-4961-a98e-f98583e30bb9",
    "type": "public",
    "_links": {
        "self": {
            "href": "/config/01000000-0000-3000-9000-000000000000/clients/6be73a3a-5bf0-4190-a0de-698aa409ff28"
        }
    }
}


Responses

The following table includes information about some of the response codes that you might encounter when calling this endpoint.

Response CodeDescription

204

No content. The customer client has been updated successfully but no content is available.


Bad request. Typically indicates a syntax error; for example, you might have left off a parameter or misspelled a parameter name. Often-times the error description will help you pinpoint the problem; for example:

{
    "errors": {
        "tokenPolicy": [
            "Missing data for required field."
        ]
    }
}

401

Authentication required or Invalid credentials. You either did not specify an authentication method for the call (this endpoint requires token-based authentication) or the token was rejected. In the latter case, this could be because the token is not valid or because the token has expired.

403

Forbidden. You do not have permission to access the requested resource.

409

Dependency error

 

OIDC Clients and Multiple Applications

Back to top

Although this situation is rare (in fact, there's a good chance you'll never encounter it), you need to be especially careful when modifying a OIDC client if:

  • You have multiple Identity Cloud applications.
  • You have like-named OIDC clients in two or more of those applications; for example, Application A has an OIC client named My OIDC Client and Application B also has an OIDC client named My OIDC Client. (This is possible because OIDC client names only have to be unique within a given application; they don't have to be unique across all your applications.)

So why is this a potential problem? Well, to modify an OIDC client it's typical to start by using the GET method to return the existing properties and property values of the client. You copy that information, paste it into the body parameter of your PUT method API call, then make any necessary changes to that informartion (for example, you add a redirect URI). After you make the changes, you call the PUT method and update the client.

That's a fast and wasy way to update an OIDC client. However, suppose you want to update the My OIDC Client client from Application A and you inadvertently copy and paste properties and property methods from the My OIDC Client client found in Application B. When you make your API call, that call is going to fail with an error similar to this:

{
  "errors": "message:duplicate client description found for p8e4u745z75zv3emjw8qxejnz3ye26mf"
}

Unfortunately, that's not the worst of it. In addition to the API call failing, the application client will be removed from the My OIDC Client you were trying to update. And that's a fatal error: once an application client has been removed from an OIDC client that client is now useless: there's no way to restore an application client that's been removed and, without an application client, an OIDC client can't be used for logins and registrations. At that point the only thing you can do is start over and create (and deploy) a brand-new API client.

Again, this a rare scenario,  one that requires multiple applications and multiple OIDC clients that share the same name and an inadvertent attempt to assign the properties and property values from one client to another. It's unlikely to happen, but if you do have multiple applications and if you do have OIDC clients that share the same name it's something to be aware of.