docs: add secret key rotation guide

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
+```
+

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": [