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:
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:
The Customer Managed Keys operations adds the following log event in your tenant logs:
A
- 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).
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 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_keysupdate: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.
- 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.
Monitor Customer Managed Keys log events
Auth0 automatically rotates tenant encryption keys once a year, adding the following log events in your tenant logs:
kms_key_state_changedkms_key_management_success
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
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.