Customer Managed Keys
Using Auth0 Customer Managed Keys allows you to configure the lifecycle of your Tenant Master Key and bring your own Customer Provided Root Key to replace the Environment Root Key for your Auth0 tenant.
Customer Managed Keys provides two methods of managing your keys:
Control Your Own Key: Allows users with the Key Management Editor role to customize the lifecycle of the Tenant Master Key in Auth0 KMS.
Bring Your Own Key: Allows users with the Key Management Editor role to replace the Auth0 Environment Root Key and import their own wrapped encryption key to the corresponding Auth0 Cloud Hardware Security Module (HSM).
To learn more about Auth0 Keys, read Auth0 key hierarchy.
The Customer Managed Keys feature is available to users with the Key Management Editor role. This role is not applied to users by default and needs to be explicitly applied to a Tenant member. To learn more, read Add Tenant Members.
Control Your Own Key
You can control the lifecycle of your Tenant Master Key using the Auth0 Management API Rekey endpoint to:
Rotate the old Tenant Master Key with a newly-created Tenant Master Key.
Rotate and re-encrypt Namespace Keys with the new Tenant Master Key.
Permissions
Use the following permissions to provide access to the rekey endpoints:
| Permissions | Descriptions |
|---|---|
create:encryption_keys
update:encryption_keys |
Users can rotate and re-encrypt the Key hierarchy of an Auth0 tenant with the Management API Rekey endpoint. |
Endpoint
Use the Management API Rekey endpoint to rotate the Tenant Master Key and rotate and re-encrypt Namespace Keys.
Rotate the Tenant Master Key: deactivates the currently active Tenant Master Key and creates a new Tenant Master Key.
Rotate all Namespace Keys in the tenant: deactivate currently active keys and activate new keys.
New Namespace Keys are used in new encryption operations.
Deactivated Namespace Keys are used to decrypt previously encrypted data.
Re-encrypts all existing Namespace Keys with the new Tenant Master Key.
The endpoint is only available to tenant members with specific authorization scopes in Auth0, by default these scopes are granted to users with the Key Management Editor role.
Bring Your Own Key
By importing your own Customer Provided Root Key with Bring Your Own Key, you are implicitly deauthorizing Auth0 from managing the lifecycle of the Customer Provided Root Key, except for its deletion.
Bring Your Own Key allows Key Management Editors to securely import a Wrapped Encryption Key (Customer Provided Root Key) to a FIPS 140-2 L3 Hardware Security Module (HSM) in the corresponding Auth0 Cloud.
Using Bring Your Own Key you can:
Replace the default Auth0 generated Environment Root Key with a new Customer Provided Root Key.
Rotate and re-encrypt the key hierarchy with the Customer Provided Root Key. For example: create and re-encrypt a new Tenant Master Key and a new Namespace Key.
You can use the Dashboard or the Management API to enable Bring Your Own Key.
Monitor Customer Managed Keys log events
The Customer Managed Keys operations adds the following log event in your tenant logs:
A sapi event code indicating:
Create the new encryption key
Create the public wrapping key
Import the encryption key
Delete the encryption key by its key id
Rekey the key hierarchy
A kms_key_management_success event code indicating a successful KMS operation.
A kms_key_management_failure event code indicating a failed KMS operation.
A kms_key_state_changed event code indicating a KMS key state change.
Auth0 key hierarchy
At the Auth0 application layer, Auth0 secures customer secrets and data using envelope encryption.
The Auth0 envelope encryption hierarchy consists of the following keys, each of which are encrypted using the key above it. The table below summarizes the key hierarchy:
| Key | Algorithm | Storage |
|---|---|---|
| Environment Root Key | RSA 2048 OAEP (Auth0 on Azure) AES-256-GCM (Auth0 on AWS) |
FIPS 140-2 L3 Hardware Security Module |
| Tenant Master Key | AES-256-GCM | Auth0 KMS database |
| Namespace Key | AES-256-GCM | Auth0 KMS database |
| Data Encryption Key | AES-256-GCM | Stored next to the data |
Environment Root Key
The Environment Root Key represents the top of the hierarchy and wraps the Tenant Master Key to prevent it from being disclosed or tampered with outside of Auth0.
An independent Auth0 Environment Root Key is generated for each Auth0 environment and stored in an adjacent HSM. The HSMs are deployed in a highly available, multiple geographic configuration. This means the HSMs will failover to another region in case of a severe region-wide incident.
The Auth0 Environment Root Key is shared across all tenants. Customers can use the Bring Your Own Key feature to have a dedicated Environment Root Key for their tenant.
Auth0 uses the following algorithms to wrap the Tenant Master Key with the Environment Root Key based on your Auth0 Cloud Service Provider:
Auth0 on Azure: RSA 2048 OAEP
Auth0 on AWS: AES 256 GCM
Using the Auth0 Dashboard or Management API, tenant Admins can replace the Auth0 Environment Root Key with their own Customer Provided Root Key.
Tenant Master Keys
Each tenant has an encrypted Tenant Master Key stored in the Auth0 Key Management Service and it encrypts the Namespace keys.
The algorithm used to encrypt the Tenant Master Key is AES256 GCM.
When a Tenant Admin using the Auth0 Dashboard or Management API has provided their own Customer Provided Root Key, a new Tenant Master Key is created.
Namespace Keys
Namespace Keys segregate the encryption keys used for different purposes within the tenant. The number and use of Namespace Keys is configured internally by Auth0 and unavailable for customization.
Encryption and decryption of Namespace Keys require access to the Tenant Master Key. Namespace Keys never leave the Auth0 Key Management Service and are not accessible to developers or administrators.
The Namespace Keys are located in the Auth0 Key Management Service and are encrypted with the AES256 GCM algorithm.
Data Encryption Keys
The Auth0 Key Management Service securely generates different Data Encryption Keys for subsequent data encryption requests. The Auth0 Key Management Service optimizes security and performance by regularly issuing new Data Encryption Keys.
Encryption and decryption of Data Encryption Keys require access to its assigned Namespace Key. Data Encryption Keys cannot be decrypted outside the Auth0 Key Management Service or by Key Management Editors.
The Data Encryption Keys are located next to the data and are encrypted with the AES256 GCM algorithm.