diff --git a/docs/docs/guides/secret-key-rotation.mdx b/docs/docs/guides/secret-key-rotation.mdx new file mode 100644 index 00000000000..a74deb282b6 --- /dev/null +++ b/docs/docs/guides/secret-key-rotation.mdx @@ -0,0 +1,33 @@ +--- +id: secret-key-rotation +title: Secret and Key Rotation +--- + +ORY Kratos needs secrets that are used for encrypting, decrypting, generating and validating signatures, and other +cryptographic tasks. + +These secrets must have high entropy (>= 256 bit). It is also a good idea to rotate the keys every now and then. +Assuming you have the following secrets configured + +```yaml title="path/to/kratos/config.yml +secrets: + default: + - old-default-secret + cookie: + - old-cookie-secret +``` + +and want to rotate these secrets, you would add the new secrets to the top of the list and keep the old secrets +around. This allows the system to verify and decrypt things that have been signed/encrypted with the old secret, +while generating new signatures and encrypting new things using the new secret: + +```yaml title="path/to/kratos/config.yml +secrets: + default: + - new-default-secret + - old-default-secret + cookie: + - new-cookie-secret + - old-cookie-secret +``` + diff --git a/docs/sidebar.js b/docs/sidebar.js index ada8a5cb8d3..5b9d0fb9846 100644 --- a/docs/sidebar.js +++ b/docs/sidebar.js @@ -64,7 +64,8 @@ module.exports = { "guides/account-recovery-password-reset", "guides/account-activation-email-verification", "guides/multi-tenancy-multitenant", - "guides/high-availability-ha", + "guides/secret-key-rotation", + "guides/high-availability-ha", "guides/docker" ], "Reference": [