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
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_KEY
ACTIVE` to
ENC_KEY_ACTIVE=Wx1zrbLF
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.
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.