Skip to content

Bring your own KMS (BYOK)

Make a key in your own cloud key management service the key-encryption key that protects your tenant's keys, so that the platform cannot unwrap them without your key.

Who can do it

A tenant administrator or a tenant key manager, or a platform super admin working inside the tenant. The console offers the declare, bind and rotate controls only to a person who holds the permission to manage the tenant's key-protection backend; without it each control stays visible and says that your role does not include that permission.

Before you start

  • Your tenant's effective edition is ENTERPRISE. On any other edition the panel says that BYOK requires the ENTERPRISE edition, and only a platform administrator can assign it.
  • Your tenant holds no key material yet. Declaring a backend is offered only before the first key exists. Once keys exist, bringing your own KMS is a key custody move instead: see Move the tenant's keys to another backend.
  • A key exists in your own Cloud KMS account, and you have a credential that can use it. The services you can choose from are the ones the platform admits for your tenant (Cloud KMS services such as AWS KMS, Google Cloud KMS or Azure Key Vault); the console offers exactly the list the platform returns.
  • On a customer-operated deployment, the platform operator has delegated key protection to your tenant.

Steps

  1. Open Settings in your tenant's navigation, then the Integrations tab.
  2. On the Key protection row, select its action (Declare, Manage or Review). The key-protection panel opens over the page.
  3. Select Configure a BYOK backend for this tenant.
  4. Under Backend, choose the key management service.
  5. Under Backend configuration, fill in the fields the platform names for that service, such as the key identifier and, where the service needs one, its endpoint. On AWS KMS the key identifier is the key ARN (arn:aws:kms:<region>:<account-id>:key/<key-id>); an alias ARN is refused.
  6. Under Access credential, enter the credential. It is write-only: it is sealed and never shown again.
  7. Optionally, select Check these coordinates. The check parses the coordinates and, where the service has an endpoint, probes it; it saves nothing and sends no credential.
  8. Select Declare this backend. The console reports Backend declared. Bind it to finish provisioning.
  9. Optionally, select Test connection to check that the platform reaches the declared key.
  10. Select Bind backend. The platform provisions your tenant's key-encryption key on your key and verifies it. While it works, the panel shows Binding the backend; select Refresh status to follow it.

Later, to replace the credential without changing the key, select Rotate credential on the bound backend, enter the new credential in the Rotate access credential dialog and confirm. The new credential is tested against your key before it replaces the current one.

What you see when it worked

The console reports Backend bound. The panel shows the backend, its key and endpoint, the credential as sealed with the result of its last check, the Key protection assurance derived from your backend, and the Protection level reported by your provider. The declaration, the bind and every credential rotation are written to your audit log.

From now on the keys you create are protected under your own key. The platform never rotates your key: you rotate it, or let your provider rotate it automatically, and the panel reports which.

If it fails

What you see Cause What to do
The declaration is refused as invalid, naming a property A key identifier or endpoint is missing, in the wrong place, or not the vendor's Correct the named property and save again; see Key Backend Declaration Invalid
BYOK requires the ENTERPRISE edition The tenant's effective edition is not ENTERPRISE Ask a platform administrator to assign the ENTERPRISE edition
The configure control is unavailable because key material already exists The tenant already holds keys Bring your own KMS through a key custody move
This deployment currently offers no key-protection backend this tenant may declare No service is admitted for your tenant Ask your platform operator to review the allowed backends
The platform refused this declaration The platform no longer admits that service for your tenant, or a value does not meet the service's rules Read the reason shown; the list of services is reloaded, so choose again
A field is refused, for example the endpoint or the key identifier The value does not have the form the service requires, for example an AWS alias ARN where the key ARN is required Correct the field and declare again
The backend refused the bind verification The declared key could not be found or addressed, or your provider declined an operation made with the credential Correct the key or the credential with Change backend, then bind again
The backend could not complete the bind verification right now Your provider could not be reached or did not answer in time Retry the bind later
A credential rotation is refused The new credential failed the test against your key; the current credential stays in force Correct the credential and rotate again

Without the console

Surface How
Key management CLI No command
Admin SDK Not available
API PUT /api/v3/admin/tenants/{tenantId}/key-backend/byok/driver-declaration (operation replaceByokDriverDeclaration), with the driver, its properties and its secrets; POST …/key-backend/byok/validate (operation validateTenantByokBackend); POST …/key-backend/byok/test (operation testByok); POST …/key-backend/byok/bind (operation bindByok); PATCH …/key-backend/byok/credential (operation updateByokCredential)