Skip to main content

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 takes the latest key from the key store to sign JSON Web Tokens. All public keys will be shown at http://ory-hydra-public-api/.well-known/jwks.json.

OpenID Connect ID Token​

hydra keys create --endpoint=http://ory-hydra-admin-api/ hydra.openid.id-token -a 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 keys create --endpoint=http://ory-hydra-admin-api/ hydra.jwt.access-token -a RS256

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.