Encryption

In the Getting Started, we have set up the ENC_KEYS and ENC_KEY_ACTIVE.

The ENC_KEYS defines the static keys used for additional data encryption in a few places. This values may contain multiple keys, if you want to rotate them at some point without breaking the decryption of all already existing secrets.

ENC_KEY_ACTIVE defines the key inside ENC_KEYS which will be used as the default. This means that all new / current encryptions performed by the backend will use the key with the given ID.

Key Rotation

1. Add a new key to the ENC_KEYS in you secrets

Fail

You must not remove a current key, before the migration has been done via the UI.
If the old key is gone, the migration will fail.

2. Generate a new key + id

echo "$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | head -c8)/$(cat /dev/urandom | head -c32 | base64)"

The part before the first / is the ENC_KEY_ID and the part afterwards is the key base64 encoded. You might set the new ENC_KEY_ACTIVE to the newly generated key ID.

Keep in mind, you need to ADD this to your existing keys and not just replace them! If you just replace them, almost all things will break and fall apart.

The final format of the ENC_KEYS should look something like this, for instance:

ENC_KEYS="
Wx1zrbLF/5vTaB7LdUSg1aTecmqHJOu2+RnU6zgTwNkDQU52Y3JM=
6uf5QebA/9DsKMoq8A+Gn2WQrTcSpz5sg751yYs3IJlkw3dn0rII=
"

In this example, if the first key should be the new active default, set your ENC_KEYACTIVE` to

ENC_KEY_ACTIVE=Wx1zrbLF

Help

If you are inside Kubernetes and (hopefully) use a Kubernetes secret for this, you need to base64 encode the whole value: echo 'PutTheWholeValueHere' | base64

3. Set the ENC_KEY_ACTIVE to the ID of your newly generated key

This will make sure, that all new encryptions will use the new key. If you do not care about removing the old keys, because you maybe just want to rotate because its good practice, the secrets will migrate "by themselves" over time. If Rauthy finds any secrets during its normal operation, that have been encrypted with an older key than the current ENC_KEY_ACTIVE, it will re-encrypt these secrets and update the values.
This means, you may just stop at this point, if this is good enough for you.

4. Migrate Keys

If you however want to trigger a re-encryption of all existing secrets on purpose, there is a small tool in the Admin UI which helps you with this.

Log in to the Admin UI and navigate to Config -> Encryption Keys.
You will see the currently recognized keys and the currently active ID.

You can then make sure, that the ID you want to migrate secrets to is selected and execute the migrations.
Please keep in mind, that if you have a lot of data, it might take a few seconds to perform this operation.
This will migrate all encrypted data for existing OIDC clients and all JWKs used for JWT token singing with the new key.

5. Remove old keys

After a successful migration via the UI tool, you may remove old keys from the ENC_KEYS value.

Caution

The MFA cookies, which are set for a client with an active security after a successful login, are encrypted with the ENC_KEY_ACTIVE too. This means, if you remove something from the ENC_KEYS which was used to encrypt one of these MFA cookies, the user will be prompted for the password again, even if the cookie has not expired yet.