[Key Vault] Add External Key Manager (EKM) support for Managed HSM (Preview)#33651
Open
notyashhh wants to merge 5 commits into
Open
[Key Vault] Add External Key Manager (EKM) support for Managed HSM (Preview)#33651notyashhh wants to merge 5 commits into
notyashhh wants to merge 5 commits into
Conversation
…review) - Add 'az keyvault ekm-connection' (create/update/show/check/delete + certificate show) as preview. - Add --external-key-id on 'az keyvault key create' to create EKM-backed external keys (preview). - Use public SDKs: azure-keyvault-keys==4.12.0b2 (create_external_key + public ExternalKey) and azure-keyvault-administration==4.8.0b1. - Enforce external-key-id <=64 chars per public SDK contract. - Add --server-cn alias to satisfy option-length linter.
notyashhh
requested review from
DanielMicrosoft,
MaddyMicrosoft,
isra-fel,
necusjz,
teresaritorto,
xuming-ms and
yonzhan
as code owners
️✔️AzureCLI-FullTest
|
|
Hi @notyashhh, |
|
| rule | cmd_name | rule_message | suggest_message |
|---|---|---|---|
| keyvault ekm-connection | sub group keyvault ekm-connection added |
||
| keyvault key create | cmd keyvault key create added parameter external_key_id |
Collaborator
|
Thank you for your contribution! We will review the pull request and get back to you soon. |
3 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Adds public-preview Managed HSM External Key Manager (EKM) support to az keyvault by introducing a new az keyvault ekm-connection command group and enabling creation of EKM-backed external keys via az keyvault key create --external-key-id. The implementation updates Key Vault SDK dependencies to public preview versions, adds validators/serialization helpers for EKM connection/cert handling, and exposes external key metadata in key output.
Changes:
- Added
az keyvault ekm-connection(create/update/show/check/delete +certificate show) backed by a new EKM data-plane client factory and validators. - Added preview
--external-key-idtoaz keyvault key create, routing external-key creation to the new SDKcreate_external_key()path. - Updated Key Vault SDK dependency pins and improved key output transformations (including external key id; plus hex output normalization for encrypt results).
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/azure-cli/setup.py | Bumps Key Vault SDK dependency pins to public-preview versions needed for EKM/external keys. |
| src/azure-cli/requirements.py3.windows.txt | Updates Windows pinned Key Vault SDK versions to match setup dependency changes. |
| src/azure-cli/requirements.py3.Linux.txt | Updates Linux pinned Key Vault SDK versions to match setup dependency changes. |
| src/azure-cli/requirements.py3.Darwin.txt | Updates macOS pinned Key Vault SDK versions to match setup dependency changes. |
| src/azure-cli/azure/cli/command_modules/keyvault/tests/latest/test_keyvault_commands.py | Adds unit tests for external key id validation and EKM certificate serialization behavior. |
| src/azure-cli/azure/cli/command_modules/keyvault/custom.py | Implements external key creation routing and adds EKM connection/certificate custom handlers. |
| src/azure-cli/azure/cli/command_modules/keyvault/commands.py | Registers new preview keyvault ekm-connection command groups and wires validators/client factory. |
| src/azure-cli/azure/cli/command_modules/keyvault/_validators.py | Adds validation for --external-key-id and EKM connection inputs (host, path prefix, CA certs). |
| src/azure-cli/azure/cli/command_modules/keyvault/_transformers.py | Exposes external key id in key outputs and normalizes encrypt output fields to strings. |
| src/azure-cli/azure/cli/command_modules/keyvault/_params.py | Adds CLI parameters for --external-key-id and new EKM connection command arguments. |
| src/azure-cli/azure/cli/command_modules/keyvault/_help.py | Adds help entries for the new keyvault ekm-connection commands. |
| src/azure-cli/azure/cli/command_modules/keyvault/_client_factory.py | Adds a data-plane KeyVaultEkmClient factory for EKM connection operations. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+737
to
+746
| # External keys are backed by EKM and the service rejects client-specified key type/size/curve. | ||
| # Avoid the defaulting behavior in validate_key_type (RSA) when --external-key-id is present. | ||
| if getattr(ns, 'external_key_id', None): | ||
| setattr(ns, 'kty', None) | ||
| setattr(ns, 'key_size', None) | ||
| setattr(ns, 'curve', None) | ||
| setattr(ns, 'protection', None) | ||
| else: | ||
| validate_key_type(ns) | ||
|
|
Comment on lines
+359
to
+363
| @@ -360,6 +360,9 @@ class CLISecurityDomainOperation(str, Enum): | |||
| help='The type of key to create. For valid values, see: https://learn.microsoft.com/rest/api/keyvault/keys/create-key/create-key#jsonwebkeytype') | |||
| c.argument('curve', arg_type=get_enum_type(KeyCurveName), | |||
| help='Elliptic curve name. For valid values, see: https://learn.microsoft.com/rest/api/keyvault/keys/create-key/create-key#jsonwebkeycurvename') | |||
| c.extra('external_key_id', options_list=['--external-key-id'], arg_group='External Key', | |||
Member
Author
|
/azp run |
|
Azure Pipelines successfully started running 3 pipeline(s). |
…ey args, wrap cert IO errors) - key create: when --external-key-id is set, fail fast with a clear error if key-shape args (--kty/--size/--curve/--ops/--protection/--exportable) are provided, instead of silently ignoring them. - Remove arg-level validate_key_type validator from --kty so an explicitly provided value is detectable (no more default-then-undo). - _load_certificates_as_der_bytes: wrap file IO in CLIError for missing/unreadable certificate files.
… lifecycle Live-only, env-var-gated scenario test (KeyVaultEkmScenarioTest) covering ekm-connection create/show/check/certificate-show, external key create/show/list-versions/delete, the fail-fast guard, and a normal-key regression. Skips unless AZURE_CLI_TEST_EKM_* env vars are set, so it is safe in CI playback and ready to run/record against a real MHSM+EKM proxy.
…n-slate) Validated the scenario test by actually running it live against a real MHSM + EKM proxy. Two fixes from that run: - Support optional AZURE_CLI_TEST_EKM_PATH_PREFIX and pass --path-prefix; without it the connection check fails on proxies that require a path prefix (e.g. /api/v1). - Delete any pre-existing connection before create: the service returns 'EKM connection is already setup' if one exists, so start from a clean slate. Test now passes end-to-end live and still skips cleanly in CI.
…ify multi-cert input Addresses review feedback from Chandan on the EKM connection commands: - --server-ca-certificate is now a required argument on 'ekm-connection create' so help shows [Required]. The validator's non-empty check is kept as a safety net for files that parse to zero certs. Left optional on 'update'. - Clarified the help text to document both supported input forms. - Added unit tests proving both certificate input combinations: (1) a single file containing a multi-cert PEM chain is split into separate DER blobs, and (2) multiple space-separated file paths (PEM and/or DER, each possibly multi-block) are all loaded in order. Also added a test that create rejects a missing certificate. Both forms were additionally verified live end-to-end against a Managed HSM + EKM proxy (create -> show shows 2 CAs -> check passes), then the connection was restored.
isra-fel
reviewed
Jun 26, 2026
| 'Release policies are mutable by default.') | ||
|
|
||
| with self.argument_context('keyvault key create') as c: | ||
| c.argument('kty', arg_type=get_enum_type(JsonWebKeyType), validator=validate_key_type, |
isra-fel
reviewed
Jun 26, 2026
| help='The type of key to create. For valid values, see: https://learn.microsoft.com/rest/api/keyvault/keys/create-key/create-key#jsonwebkeytype') | ||
| c.argument('curve', arg_type=get_enum_type(KeyCurveName), | ||
| help='Elliptic curve name. For valid values, see: https://learn.microsoft.com/rest/api/keyvault/keys/create-key/create-key#jsonwebkeycurvename') | ||
| c.extra('external_key_id', options_list=['--external-key-id'], arg_group='External Key', |
Member
There was a problem hiding this comment.
What does .extra do differently from .argument?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related command
az keyvault ekm-connection(create/update/show/check/delete +certificate show)az keyvault key create --external-key-idDescription
Adds public-preview support for Managed HSM External Key Manager (EKM) to
az keyvault.What's added:
az keyvault ekm-connectionto wire a Managed HSM to an external keymanager proxy:
create,update,show,check,delete, andcertificate show.--external-key-idflag onaz keyvault key createto create EKM-backed external keys.All new commands and the
--external-key-idargument are marked preview (is_preview=True).This builds on the private-preview implementation and moves it to the public preview SDKs:
azure-keyvault-keys==4.12.0b2— uses the newcreate_external_key()API and the publicExternalKeymodel.azure-keyvault-administration==4.8.0b1—KeyVaultEkmClient/KeyVaultEkmConnection.Both SDKs are published on PyPI and require Python >=3.10, which matches the CLI's floor
(
python_requires>=3.10), so there is no dependency-resolution impact on CI.Notes:
dedicated
create_external_key()path and omits those attributes.--external-key-idis validated to the public SDK contract ([A-Za-z0-9-], max 64 chars).internal 1P drop.
Testing Guide
Unit (offline):
Live smoke (Managed HSM required):
History Notes
[Key Vault]
az keyvault ekm-connection: Add command group to manage External Key Manager (EKM) connections for Managed HSM (Preview)[Key Vault]
az keyvault key create: Add--external-key-idto create EKM-backed external keys on Managed HSM (Preview)