Use ESVs for signing and encryption keys

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, refer to Secret IDs.

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:

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.

For examples of how to generate asymmetric and symmetric keys, see the following:

Generate an RSA key pair
Generate a HMAC key

Create an access token for the appropriate realm. See Get an access token.

Create the ESV secret:

Show request

$ curl \
--request PUT 'https://<tenant-env-fqdn>/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
}

In the Identity Cloud admin UI, click Native Consoles > Access Management.
In the AM admin UI (native console), go to Realm > Secret Stores.
Click the ESV secret store, then click Mappings.

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.

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 SAML 2.0 certificates using ESVs

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

Generate keys to use in ESVs

Generate an RSA key pair

To generate an RSA key pair to use in an ESV:

Run the following command to generate a private key:
```
$ openssl genrsa -out private-key.pem
```

Then, generate a public key using the private key:

$ openssl req -new -x509 -key private-key.pem -out public-key.pem -days 365 -subj /CN=idcloud

Combine the private key and public key into a key pair:
```
$ cat private-key.pem public-key.pem > key-pair.pem
```
If you intend to use an API request to create the ESV:
1. Encode the key pair into base64:
  $ openssl enc -base64 -A -in key-pair.pem -out key-pair-base64.pem
  The file key-pair-base64.pem now contains a base64 encoded key pair value.
2. You can now use this value in the valueBase64 property of the JSON body of the API request. See step 1b in Map ESV secrets to secret IDs for an example.

Generate a HMAC key

To generate a HMAC key to use in an ESV:

Run the following command:

$ head -c<bytes> /dev/urandom | openssl enc -base64 -A -out hmac-key.txt(1)

1	Replace <bytes> with your required key length; for example, 512.

Summary of command:

Generates a random number using /dev/urandom
Truncates the random number to your required key length using head
Encodes the truncated random number into base64 using openssl

If you intend to use an API request to create the ESV:
1. Encode the key into base64 again:
  $ openssl enc -base64 -A -in hmac-key.txt -out hmac-key-base64.txt
  The file hmac-key-base64.txt now contains a base64 encoded key value.
2. You can now use this value in the valueBase64 property of the JSON body of the API request. See step 1b in Map ESV secrets to secret IDs for an example.