Rotate Credentials
Auth0 recommends you rotate key material regularly to meet your compliance needs and ensure security is not compromised by leaked private keys. You can use the Auth0 Dashboard or Management API to rotate new keys into use. You need to create a new credential, associate it with the private_key_jwt
authentication method, and remove old or unused credentials.
To rotate your application credentials with Auth0 Dashboard:
Navigate to Auth0 Dashboard > Applications > Application and select the application you want to update.
Switch to the Credentials tab.
In the Available Credentials section, select Add New Key.
Set a name for your new credential, the public key in PEM format, and the algorithm for the new credential.
Select Add Credential.
To activate your new credential, navigate to the menu for the credential and choose Enable for Private Key JWT use.
Once you have updated your applications to use the new credential, deactivate your original credential:
Select Disable for Private Key JWT Use.
Once disabled, return to the credential menu and select Delete Credential.
In the rotation examples below, credential1
is an existing credential in use, and credential2
is a new credential to replace the existing one.
Generate a new key pair.
Create the credential resource with a
POST
request to the Management API.Make a PATCH request to the Management API Update a Client endpoint to associate the credential to the authentication method
private_key_jwt
:curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \ --header 'Authorization: Bearer {managementApiAccessToken} \ --header 'Content-Type: application/json' \ --data-raw '{ "client_authentication_methods": { "private_key_jwt": { "credentials": [{ "id": {credentialId1} }, { "id": {credentialId2} }] } } }'
Was this helpful?
/Parameter Description clientId
Application you want to update. credentialId1
ID for the existing credential in use. credentialId2
ID for the new credential. managementApiAccessToken
Access token for the Management API with the scopes update:clients
andupdate:credentials
.Update your application to use the new private key to sign assertions for the Auth0 Authentication API.
Remove the unused key from your application.
curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \ --header 'Authorization: Bearer $management_access_token' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_authentication_methods": { "private_key_jwt": { "credentials": [{ "id": {credentialId2} }] } } }'
Was this helpful?
/Remove the unused key from your application. This will permanently delete the credential from storage. You must unassociate the credential from your application or you will not be able to remove it.
curl --location --request DELETE 'https://{domain}/api/v2/clients/{clientId}/credentials/{credentialId}' \ --header 'Authorization: Bearer {managementApiAccessToken}
Was this helpful?
/Parameter Description clientId
Application you want to update. credentialId
ID for the old credential you want to delete. managementApiAccessToken
Access token for the Management API with the scope delete:credentials
.
Active credentials
To assure zero downtime, you can leave multiple credentials active during rotation. Applications can function normally using older keys until keys are updated. Applications can send signed assertions with any set of active credentials.
Auth0 recommends you minimize the time that multiple credentials are in use. The example below uses multiple associated credentials:
curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
--header 'Authorization: Bearer $management_access_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"client_authentication_methods": {
"private_key_jwt": {
"credentials": [{ "id": $credential1.id }, { "id": $credential2.id }]
}
}
}'
Was this helpful?