Add guide on how to achieve 0 downtime client credential rotation

docs/guides/client_secret_rotation.md

@@ -0,0 +1,134 @@
+---
+page_title: Zero downtime client credentials rotation
+description: |-
+  Achieve zero downtime client credentials rotation with the Auth0 Terraform provider.
+---
+
+# Achieving zero downtime client credentials rotation
+
+In this guide we'll show how to rotate a client's credentials to eliminate downtime for the impacted system.
+
+## Pre-requisites:
+
+- The system relies on the configuration to maintain either a list of client secrets or at least two separate
+configuration entries (CURRENT and NEXT) representing client secrets.
+- By default, the system uses the first client secret in the list or the CURRENT configuration entry. If an error is
+received during an exchange that requires client authentication and the error is known to be associated with a problem 
+related to client credentials, the system should be capable of retrying the operation using the next secret in the
+list or the NEXT configuration entry.
+- If an event occurs that forces the system to attempt to use the next secret in the list or the NEXT configuration
+entry and the operation succeeds when using the new secret, the system should discard the old secret and update the
+configuration in a way that the next secret (the one that succeeded) is considered to be the default/current one going
+forward.
+
+## Process (to rotate the credentials):
+
+### Rotating a client secret
+
+1. Generate a new value for the client secret on behalf of the system associated with the client application record.
+This value should have similar entropy to the client secret values generated by the Auth0 service, minimum 48 chars and
+valid chars are numbers, letters and `_`, `-`, `+`, `=`, `.` symbols.
+2. Add the newly generated secret to the system configuration as the next secret in the list or in the respective entry
+if separate configuration entries are used.
+3. Add the new client secret generated in the first step in your terraform configuration and run `terraform apply`:
+
+```terraform
+resource "auth0_client" "my_client" {
+	name     = "My client that needs the secret rotated"
+	app_type = "non_interactive"
+}
+
+resource "auth0_client_credentials" "test" {
+  client_id = auth0_client.my_client.id
+
+  authentication_method = "client_secret_post" ## Your target authentication method, client_secret_post or client_secret_basic.
+  client_secret         = "<the generated client secret>"
+}
+```
+
+### Rotating Private Key JWT credentials
+
+1. Generate a new Private Key JWT credential on behalf of the system associated with the client application record.
+2. Add the newly generated credential to the system configuration as the next credential in the list or in the
+respective entry if separate configuration entries are used.
+3. Attach the Private Key JWT credential to the client application record using Terraform and run `terraform apply`:
+
+```terraform
+resource "auth0_client" "my_client" {
+	name     = "My client that needs the credentials rotated"
+	app_type = "non_interactive"
+
+  jwt_configuration {
+    alg = "RS256"
+  }
+}
+
+resource "auth0_client_credentials" "test" {
+  client_id = auth0_client.my_client.id
+
+  authentication_method = "private_key_jwt"
+  
+  private_key_jwt {
+    credentials {
+      name                   = "Current Credential"
+      credential_type        = "public_key"
+      algorithm              = "RS256"
+      pem                    = <<EOF
+-----BEGIN CERTIFICATE-----
+MIIFWDCCA0ACCQDXqpBo3R...G9w0BAQsFADBuMQswCQYDVQQGEwJl
+-----END CERTIFICATE-----
+EOF
+    }
+
+    credentials {
+      name                   = "Next Credential"
+      credential_type        = "public_key"
+      algorithm              = "RS256"
+      pem                    = <<EOF
+-----BEGIN CERTIFICATE-----
+BBBIIFWDCCA0ACCQDXqpBo3R...G9w0BAQsFADBuMQswCQYDVQQGEwJl
+-----END CERTIFICATE-----
+EOF
+    }
+  }
+}
+```
+
+4. Remove the old Private Key JWT credential on the client application record using Terraform and run `terraform apply`:
+
+```terraform
+resource "auth0_client" "my_client" {
+	name     = "My client that needs the credentials rotated"
+	app_type = "non_interactive"
+
+  jwt_configuration {
+    alg = "RS256"
+  }
+}
+
+resource "auth0_client_credentials" "test" {
+  client_id = auth0_client.my_client.id
+
+  authentication_method = "private_key_jwt"
+  
+  private_key_jwt {
+    credentials {
+      name                   = "Current Credential" # Next becomes current.
+      credential_type        = "public_key"
+      algorithm              = "RS256"
+      pem                    = <<EOF
+-----BEGIN CERTIFICATE-----
+BBBIIFWDCCA0ACCQDXqpBo3R...G9w0BAQsFADBuMQswCQYDVQQGEwJl
+-----END CERTIFICATE-----
+EOF
+    }
+  }
+}
+```
+
+## Summary
+
+Given the system is prepared to automatically fall back to use the next client credential as available in system 
+configuration, this process will allow rotating a credential without downtime because by the time that the new 
+credential takes effect in the Auth0 service, the system is already aware of that value and can automatically fall back
+and retry any operation that fails due to the old credential that got rotated.

templates/guides/client_secret_rotation.md

@@ -0,0 +1,134 @@
+---
+page_title: Zero downtime client credentials rotation
+description: |-
+  Achieve zero downtime client credentials rotation with the Auth0 Terraform provider.
+---
+
+# Achieving zero downtime client credentials rotation
+
+In this guide we'll show how to rotate a client's credentials to eliminate downtime for the impacted system.
+
+## Pre-requisites:
+
+- The system relies on the configuration to maintain either a list of client secrets or at least two separate
+configuration entries (CURRENT and NEXT) representing client secrets.
+- By default, the system uses the first client secret in the list or the CURRENT configuration entry. If an error is
+received during an exchange that requires client authentication and the error is known to be associated with a problem 
+related to client credentials, the system should be capable of retrying the operation using the next secret in the
+list or the NEXT configuration entry.
+- If an event occurs that forces the system to attempt to use the next secret in the list or the NEXT configuration
+entry and the operation succeeds when using the new secret, the system should discard the old secret and update the
+configuration in a way that the next secret (the one that succeeded) is considered to be the default/current one going
+forward.
+
+## Process (to rotate the credentials):
+
+### Rotating a client secret
+
+1. Generate a new value for the client secret on behalf of the system associated with the client application record.
+This value should have similar entropy to the client secret values generated by the Auth0 service, minimum 48 chars and
+valid chars are numbers, letters and `_`, `-`, `+`, `=`, `.` symbols.
+2. Add the newly generated secret to the system configuration as the next secret in the list or in the respective entry
+if separate configuration entries are used.
+3. Add the new client secret generated in the first step in your terraform configuration and run `terraform apply`:
+
+```terraform
+resource "auth0_client" "my_client" {
+	name     = "My client that needs the secret rotated"
+	app_type = "non_interactive"
+}
+
+resource "auth0_client_credentials" "test" {
+  client_id = auth0_client.my_client.id
+
+  authentication_method = "client_secret_post" ## Your target authentication method, client_secret_post or client_secret_basic.
+  client_secret         = "<the generated client secret>"
+}
+```
+
+### Rotating Private Key JWT credentials
+
+1. Generate a new Private Key JWT credential on behalf of the system associated with the client application record.
+2. Add the newly generated credential to the system configuration as the next credential in the list or in the
+respective entry if separate configuration entries are used.
+3. Attach the Private Key JWT credential to the client application record using Terraform and run `terraform apply`:
+
+```terraform
+resource "auth0_client" "my_client" {
+	name     = "My client that needs the credentials rotated"
+	app_type = "non_interactive"
+
+  jwt_configuration {
+    alg = "RS256"
+  }
+}
+
+resource "auth0_client_credentials" "test" {
+  client_id = auth0_client.my_client.id
+
+  authentication_method = "private_key_jwt"
+  
+  private_key_jwt {
+    credentials {
+      name                   = "Current Credential"
+      credential_type        = "public_key"
+      algorithm              = "RS256"
+      pem                    = <<EOF
+-----BEGIN CERTIFICATE-----
+MIIFWDCCA0ACCQDXqpBo3R...G9w0BAQsFADBuMQswCQYDVQQGEwJl
+-----END CERTIFICATE-----
+EOF
+    }
+
+    credentials {
+      name                   = "Next Credential"
+      credential_type        = "public_key"
+      algorithm              = "RS256"
+      pem                    = <<EOF
+-----BEGIN CERTIFICATE-----
+BBBIIFWDCCA0ACCQDXqpBo3R...G9w0BAQsFADBuMQswCQYDVQQGEwJl
+-----END CERTIFICATE-----
+EOF
+    }
+  }
+}
+```
+
+4. Remove the old Private Key JWT credential on the client application record using Terraform and run `terraform apply`:
+
+```terraform
+resource "auth0_client" "my_client" {
+	name     = "My client that needs the credentials rotated"
+	app_type = "non_interactive"
+
+  jwt_configuration {
+    alg = "RS256"
+  }
+}
+
+resource "auth0_client_credentials" "test" {
+  client_id = auth0_client.my_client.id
+
+  authentication_method = "private_key_jwt"
+  
+  private_key_jwt {
+    credentials {
+      name                   = "Current Credential" # Next becomes current.
+      credential_type        = "public_key"
+      algorithm              = "RS256"
+      pem                    = <<EOF
+-----BEGIN CERTIFICATE-----
+BBBIIFWDCCA0ACCQDXqpBo3R...G9w0BAQsFADBuMQswCQYDVQQGEwJl
+-----END CERTIFICATE-----
+EOF
+    }
+  }
+}
+```
+
+## Summary
+
+Given the system is prepared to automatically fall back to use the next client credential as available in system 
+configuration, this process will allow rotating a credential without downtime because by the time that the new 
+credential takes effect in the Auth0 service, the system is already aware of that value and can automatically fall back
+and retry any operation that fails due to the old credential that got rotated.