Skip to content

OAuth Client Secret Rotation

When client secrets are expired, clients cannot authenticate using the Identity Management Service anymore. Thus, client secrets must be updated in time.

This section describes how to update the client secret without downtime.

Introduce a new Secret

In order to avoid downtime, a new client secret should be introduced before the old secret expires. Both secrets are stored in parallel, allowing clients to keep using the old secret during the secret rotation. New secrets can either be generated by the user or by Insights Hub.

The following REST call introduces a new user generated secret. Trigger Insights Hub to generate the new secret by leaving the data input for the new secret empty (-d '{}').

curl -X POST \
  -H 'Current-Secret: {active secret}' \
  -H 'Authorization: Bearer {token with prv.oc.sec.ch scope}' \
  -H 'Content-type: application/json' \
  -d '{
        "newSecret": "{new secret to introduce}"
      }' \
  '.../provider/oauth/clients/{clientId}/secrets'

Update Clients to use the new Secret

Update all clients and make sure they use the new secret.

Remove the old Secret

Identity Management Service can handle up to two secrets per client. However, it is recommended to only use one at a time and to remove the old secret after secret rotation. The following REST call removes the old secret and thus makes it invalid:

curl -X DELETE \
  -H 'Current-Secret: {active secret}' \
  -H 'Authorization: Bearer {token with prv.oc.sec.ch scope}' \
  '.../provider/oauth/clients/{clientId}/secrets'

Last update: March 17, 2023

Except where otherwise noted, content on this site is licensed under the Development License Agreement.