Secrets and key rotation

There are two types of key rotation:

• Rotation of JSON Web Token Signing Keys
• Rotation of HMAC Token Signing and Database and Cookie Encryption Keys

Rotation of JSON Web Token Signing Keys

JSON Web Token Signing Key rotation is simple with Ory Hydra. You can rotate OpenID Connect ID Token and OAuth 2.0 Access Tokens, when using the JSON Web Token strategy, keys with one simple command.

Ory Hydra Authorization signs JSON Web Tokens with the newest private key of a key set, so a new key signs right away. All public keys will be shown at http://ory-hydra-public-api/.well-known/jwks.json.

OpenID Connect ID Token

hydra create jwks --endpoint=http://ory-hydra-admin-api/ hydra.openid.id-token --alg RS256

OAuth 2.0 Access Tokens (JSON Web Token)

This will only work when using the JWT access token strategy. Otherwise, this will have no effect.

hydra create jwks --endpoint=http://ory-hydra-admin-api/ hydra.jwt.access-token --alg RS256

After the rotation

After the rotation, the key set still holds the old key, including its private half. Tokens signed with the old key keep verifying for as long as the key set holds the old key, with or without its private half. To remove the private half while those tokens keep verifying, retire the old key. To stop accepting those tokens, delete the old key with DELETE /admin/keys/{set}/{kid}.

Cryptographic key management also covers:

• Which key signs, including the order of keys on MySQL and in a Hardware Security Module (HSM). With an HSM, creating a key replaces the key set, so tokens signed with the old key stop verifying.
• Publishing a new key before it signs, for applications that cache /.well-known/jwks.json.
• Caching of JWKs in the Ory Hydra Enterprise License (OEL).

The ory commands on that page work the same way with the hydra CLI and its --endpoint flag.

Rotation of HMAC Token Signing and Database and Cookie Encryption Keys

Rotating database encryption keys is done by prepending the new encryption key to the respective configuration value. Assuming configuration

secrets:
  cookie:
    - the-old-cookie-encryption-key
  system:
    - the-old-system-encryption-key

one would add the new keys as follows

secrets:
  cookie:
    - the-new-cookie-encryption-key # the new key must be the first entry
    - the-old-cookie-encryption-key
  system:
    - the-new-system-encryption-key # the new key must be the first entry
    - the-old-system-encryption-key

It's very important that the new key is the first entry in the list as only the first key is used for encryption while all keys from the list are used for decryption. Please note that existing data won't be automatically re-encrypted using the new key. Only new data will be signed and encrypted using the new key. It's therefore imperative that the old key is added to the list, unless you want to also invalidate all data that was signed or encrypted using the old key.