Configure the Azure Key Vault provider
Step 2 of 5 in Connect Azure KMS with BYOK and BYOC.
Collect the HTTPS vault or Managed HSM URI, the Microsoft Entra tenant id, the workload client id and the Azure role assignments before starting. Wrong role assignments surface as a validation failure, not as a configuration error.
For a tenant-owned vault, create the resource with a providerId you choose (runtime KMS calls use
it later), a displayName, kind: AZURE_KEY_VAULT and a configuration object holding vaultUri,
the Entra tenantId, the clientId and hsmType (KEYVAULT or MANAGED_HSM). The response
returns a handle, resourceVersion 1 and a credentialSecretRef (the captures redact it). The
resource starts DEGRADED with no credential, which is expected: it cannot reach the vault until the
next call.
- Overview
- Request
- Response
Tenant creates its own Azure resource
Endpoint: POST /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources
Captured response: 201 Created
This captured endpoint is shown from the E2E run; it is not mapped to one of the generated EDK REST API reference pages.
Connect an environment to rewrite this call to real service bases and run it.
Attach the Azure client secret with expectedResourceVersion: 1, clientSecretRef set to the
credentialSecretRef from the create response, and the one-time clientSecret. A
TENANT_SUPPLIED resource instead takes a tenant-owned sec_... reference plus
providerAssignmentId and never plaintext. The secret is write-only and stored in the tenant secret
store; the value never travels back, and the response only confirms credentialConfigured: true at
resourceVersion 2.
- Overview
- Request
- Response
Tenant attaches its own Azure client secret
Endpoint: PUT /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources/krh_%3Copaque%3E/credentials/azure-key-vault
Captured response: 200 OK
This captured endpoint is shown from the E2E run; it is not mapped to one of the generated EDK REST API reference pages.
Connect an environment to rewrite this call to real service bases and run it.
Validation proves the provider can reach the vault with the configured identity: it opens the
provider and makes one read-only call against the vault, without creating or reading a key. The
captured result is CONFIGURED and HEALTHY. Treat anything else as a stop. FAILED with
KMS_PROVIDER_OPEN_REFUSED means the configuration or credential was refused, FAILED with
KMS_PROVIDER_PROBE_FAILED means the vault call failed, often on role assignments, and DEGRADED
with KMS_PROVIDER_PROBE_UNAVAILABLE means the probe could not run, so validate again.
- Overview
- Request
- Response
Tenant validates its own Azure resource
Endpoint: POST /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources/krh_%3Copaque%3E/validate
Captured response: 200 OK
This captured endpoint is shown from the E2E run; it is not mapped to one of the generated EDK REST API reference pages.
Connect an environment to rewrite this call to real service bases and run it.
For a platform-owned shared vault, the platform operator offers the provider and the tenant enables
it instead of creating a second resource. The operator either creates that provider through these
calls on the platform tenant or declares it in the deployment configuration, as described in
Cloud KMS providers. Sharing the provider does not share every key: each Azure
object a tenant may use must carry the tag sphereon-tenant-id=<tenant id>.
- Overview
- Request
- Response
Tenant enables the shared Azure provider
Endpoint: POST /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/shared-providers/azure-lc-d0564e71:enable
Captured response: 200 OK
This captured endpoint is shown from the E2E run; it is not mapped to one of the generated EDK REST API reference pages.
Connect an environment to rewrite this call to real service bases and run it.
Enabling takes no body and returns the offered entry with enabled: true. From then on the tenant
signs with the shared providerId exactly as it would with its own.
Next
Continue with step 3, Register an existing Azure key (BYOK).