Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove client secret rotation from zero downtime guide #881

Merged
merged 1 commit into from
Nov 14, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 3 additions & 54 deletions docs/guides/client_secret_rotation.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,54 +6,10 @@ description: |-

# 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.
In this guide we'll show how to rotate a client's credentials to eliminate downtime for the impacted system when using
Private Key JWT credentials.

## 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 characters
and valid characters are numbers, letters and `_`, `-`, `+`, `=`, `.` symbols. You can make use of the
[Terraform random provider](https://registry.terraform.io/providers/hashicorp/random/latest/docs) to generate this.
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 "random_password" "client_secret" {
length = 48
special = true
override_special = "_-+=."
}

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 = random_password.client_secret.result # You can also patch directly with your own client secret.
}
```

### Rotating Private Key JWT credentials
## 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
Expand Down Expand Up @@ -132,10 +88,3 @@ 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.
57 changes: 3 additions & 54 deletions templates/guides/client_secret_rotation.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,54 +6,10 @@ description: |-

# 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.
In this guide we'll show how to rotate a client's credentials to eliminate downtime for the impacted system when using
Private Key JWT credentials.

## 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 characters
and valid characters are numbers, letters and `_`, `-`, `+`, `=`, `.` symbols. You can make use of the
[Terraform random provider](https://registry.terraform.io/providers/hashicorp/random/latest/docs) to generate this.
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 "random_password" "client_secret" {
length = 48
special = true
override_special = "_-+=."
}

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 = random_password.client_secret.result # You can also patch directly with your own client secret.
}
```

### Rotating Private Key JWT credentials
## 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
Expand Down Expand Up @@ -132,10 +88,3 @@ 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.
Loading