Skip to main content
Version: v0.25.0 (Latest)

Azure KMS, BYOK, and BYOC

This guide separates three lifecycles that are often collapsed into “configure Azure”:

  1. the platform configuration resource that stores non-secret Azure coordinates and a credential reference;
  2. the runtime KMS provider and provider-native key alias used for cryptographic operations; and
  3. the public certificate material used by verifiers.

EDK must never export an Azure private key. BYOK here means register an existing provider-native key reference, and BYOC means register public certificate material or a provider-native certificate reference.

Keep the identifiers distinct​

IdentifierOwned byUsed for
kmsResourceHandlePlatform configuration planeAttach, credential lifecycle, validate, rotate, detach, and retire the provider resource
providerIdRuntime KMS planeSelect the concrete runtime provider
key alias / canonical kidAzure/providerResolve and operate on a key without copying it
certificate alias / provider certificate idRuntime KMS + providerResolve public leaf or chain material
clientSecretRefTenant secret mechanismRefer to write-only Azure credentials without exposing their value

Passing a configuration handle where a runtime provider id is expected produces an ambiguous or failed signing selection. Store both relationships explicitly.

1. Prepare the Azure boundary​

Before touching EDK, identify the HTTPS vault or Managed HSM URI, Microsoft Entra directory tenant id, workload client/application id, intended key or certificate name/version, and the least-privilege Azure permissions required for the selected algorithms and operations.

For a shared provider, enforce tenant ownership at the Azure object boundary as well as in EDK. The expected Azure assignment/tag is sphereon-tenant-id=<authenticated EDK tenant id>; validate it during registration and later use.

Never place an Azure client secret, PFX, private JWK, access token, or customer vault identifier in documentation, screenshots, OpenAPI examples, or collection variables.

2. Create or attach the Azure resource​

The platform configuration operation accepts non-secret coordinates such as vaultUri, Entra tenant/application identifiers, and HSM type. Tenant-managed attachment and platform-managed creation are separate lifecycle modes.

Navigation: Resources > KMS > Providers

KMS provider inventory in the Admin Console

The list proves only that a resource is configured. Open its detail, inspect lifecycle ownership, attach credentials through an approved secret reference, and run validation.

3. Attach credentials by reference​

For a tenant-supplied service principal, create or select a tenant-owned secret reference first. The Azure credential request contains clientSecretRef, not the secret itself. A product-managed write-only variant may accept a one-time secret for server-side storage, but that value must never be returned or persisted in a collection.

The platform configuration route ends in credentials/azure-key-vault; this distinct route makes the credential type explicit while keeping the secret behind its reference.

The provider detail should display whether credentials are configured and the non-secret reference metadata. It must not render the secret value.

Azure provider status without secret material

Run validation again after attaching or rotating credentials. Resource presence is not proof of Azure authentication, network reachability, permissions, supported algorithms, or successful key use.

Validate tenant setup KMS 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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

4. Prove the runtime provider​

The runtime API is the authority for cryptographic capability. Resolve the stable providerId, inspect its advertised capabilities, and use its provider-native alias for key operations.

Use Resources > KMS > Keys to inspect provider and alias ownership. A key row is a reference; it does not mean EDK holds the private material.

KMS keys and provider aliases

5. Register an existing Azure key (BYOK)​

Registration creates an EXTERNALLY_MANAGED EDK reference to a key that already exists in Azure. Send the runtime providerId, the provider-native alias, and the canonical kid when available. The service checks that the identifiers resolve to the same object.

The runtime endpoint is /keys/register.

Choose Register existing key. Verify the provider, alias, canonical identifier, supported algorithm, and external lifecycle before saving.

Register an existing provider-native key

6. Register public certificate material (BYOC)​

Use provider native when Azure can return the public leaf for the provider certificate id. Use stored public material for a public DER chain maintained as tenant-local verification material. Both forms must prove their public key matches the linked key.

The /certificates/register request selects source: provider_native or source: stored_public_material; the names describe custody of the public certificate material, never custody of a private key.

Choose Register certificate, select the source, and link it to the intended key. For stored chains, preserve leaf-to-root ordering.

Register provider-native or stored public certificate material

For mdoc, ensure the registered DSC, runtime KMS key, credential x5chain, and IACA trust policy all agree. Azure protects the key operation; it does not create IACA governance, VICAL trust, or wallet device authentication.

7. Sign and verify before binding production use​

Prove a non-production signature with the exact runtime provider id, alias, algorithm, and payload mode that the issuer or status-list lane will use. Verify the result independently.

Use the provider and key detail to confirm that the selected object is externally managed and active. Record only sanitized identifiers in evidence.

Runtime key selected for signature proof

Only after this proof should the same provider id and alias be selected for SD-JWT, mdoc, W3C JWT, status-list, authorization-server, verifier, or DID operations.

8. Delete references without deleting Azure objects​

Deleting an externally managed key or certificate removes only the EDK reference. It must not delete the Azure key or certificate. Platform-managed resources may have different provider-deletion behavior, so inspect lifecycle ownership before detaching or retiring anything.

Loading example...

Acceptance checklist​

  • Azure authentication, reachability, permissions, and tenant-object assignment validate successfully.
  • The configuration kmsResourceHandle resolves to the intended runtime providerId.
  • The provider advertises the required algorithms and operations.
  • The registered alias and canonical kid resolve to the same Azure key.
  • No private key or client secret appears in an API response, screenshot, log, collection, or guide.
  • Provider-native or stored certificate material matches the linked public key and intended chain.
  • The actual signature operation and independent verification succeed with the production selector shape.
  • Removing an externally managed reference leaves the Azure object intact.

The EDK Credential Status Profiles collection contains optional Azure resource, BYOK, and BYOC shapes. Those mutations are disabled by default and require an explicitly approved Azure target and tenant-owned credentials before use.