Identity Cloud

Use ESVs for signing and encryption keys

Overview

Identity Cloud lets you store signing and encryption keys in ESV secrets, then map them to secret IDs. Each secret ID represents an authentication feature in Identity Cloud, such as signing OAuth 2.0 client access tokens.

Identity Cloud can directly access keys stored in a mapped ESV secret, there is no need to restart Identity Cloud services.

You can rotate keys stored in a mapped ESV secret by adding new secret versions to the ESV. The key in the latest secret version is used to sign new access tokens, then subsequently validate them. Keys in older secret versions (that are still enabled) are still used to validate existing access tokens.

Secret IDs

Secret IDs (also known as secret purposes) represent authentication features in Identity Cloud that need a signing or encryption key. For example, to sign an OAuth 2.0 client access token with an HMAC key, you would use the secret ID am.services.oauth2.stateless.signing.HMAC.

For a full list of secret IDs, see secret ID mappings.

Map ESV secrets to secret IDs

In each realm, each secret ID is mapped to a default secret key. You cannot access these default secret keys. However, you can override the default key mappings. To do this, map a secret ID to an ESV secret in a realm’s ESV secret store.

To store a key in an ESV secret, then map it to a secret ID:

  1. Create an ESV secret, containing the value of your new signing or encryption key:

    You can only create secrets that contain keys using the API. The UI currently does not support the encoding and useInPlaceholders parameters.
    1. Create an access token for the appropriate realm. See Get an access token.

    2. Create the ESV secret:

      Show request
      $ curl \
      --request PUT 'https://<tenant-name>.forgeblocks.com/environment/secrets/<secret-name>' \ (1)
      --header 'Authorization: Bearer <access-token>' \ (2)
      --header 'Content-Type: application/json' \
      --header 'Accept-API-Version: protocol=1.0;resource=1.0' \
      --data-raw '{
          "encoding": "<encoding-format>", (3)
          "useInPlaceholders": false, (4)
          "valueBase64": "<base64-encoded-key>" (5)
      }'
      1 Replace <secret-name> with an appropriate secret name; for example, esv-oauth2-signing-key. See ESV naming.
      2 Replace <access-token> with the access token.
      3 Replace <encoding-format> with pem for asymmetric keys or base64hmac for symmetric keys. See Encoding format.
      4 Ensure that useInPlaceholders is set to false. See Control access to secrets.
      5 Replace <base64-encoded-key> with your new signing or encryption key, encoded as a Base64 string.
      Show response
      {
          "_id": "esv-oauth2-signing-key",
          "activeVersion": "",
          "description": "",
          "encoding": "base64hmac",
          "lastChangeDate": "2022-01-28T13:25:40.515Z",
          "lastChangedBy": "23b299e8-90d4-406e-9431-80faf25bc7c0",
          "loaded": true,
          "loadedVersion": "",
          "useInPlaceholders": false
      }
  2. In the Identity Cloud admin UI, click Native Consoles > Access Management.

  3. In the AM admin UI (native console), go to Realm > Secret Stores.

  4. Click the ESV secret store, then click Mappings.

  5. Click + Add Mapping, then enter the following information:

    Secret ID

    Select a secret ID; for example am.services.oauth2.stateless.signing.HMAC.

    aliases

    Enter the name of the ESV secret you created in step 1, including the esv- prefix; for example, esv-oauth2-signing-key. Then click Add.

    Only add a single ESV alias. The UI lets you add additional aliases, but this is a legacy mechanism for key rotation. Instead, rotate ESV keys by adding new secret versions to the ESV. See Rotate keys in mapped ESV secrets.
  6. Click Create.

Rotate keys in mapped ESV secrets

You can rotate keys stored in a mapped ESV secret by manipulating the enabled status of its secret versions:

idcloudui esv secrets manage versions rotation

Version 4

This is the latest secret version. It is enabled and cannot be disabled. It is used to sign new tokens. Existing tokens signed by this key are still valid.

Version 3 and version 2

These are older secret versions. They are still enabled. Existing tokens signed by these keys are still valid.

Version 1

This is an older secret version. It is disabled. Existing tokens signed by this key are not valid.

Rotate SAML2 certificates using ESVs

The following knowledge base article describes how to rotate SAML2 certificates using ESVs: https://backstage.forgerock.com/knowledge/kb/article/a47544526.

Copyright © 2010-2022 ForgeRock, all rights reserved.