Registry /
azure / azure-keyvault-administration
The `azure-keyvault-administration` client library for Python provides functionalities for managing Azure Key Vault Managed HSMs, including role-based access control (RBAC) and vault-level backup and restore operations. It is part of the Azure SDK for Python, which follows a regular release cadence, and is currently at version 4.6.0. This library is specifically designed for Managed HSMs and will not work with standard Azure Key Vaults.
Install & Compatibility
Where this runs
tested against v4.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.488s · 43.4MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 3.7s · import 0.445s · 44MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
KeyVaultAccessControlClient
✓ from azure.keyvault.administration import KeyVaultAccessControlClient
Client for managing role-based access to Key Vault Managed HSM.
KeyVaultBackupClient
✓ from azure.keyvault.administration import KeyVaultBackupClient
Client for performing backup and restore operations on Key Vault Managed HSM.
DefaultAzureCredential
✓ from azure.identity import DefaultAzureCredential
Standard credential for authenticating with Azure services across various environments.
KeyVaultRoleScope
✓ from azure.keyvault.administration import KeyVaultRoleScope
Enum defining well-known role scopes for RBAC.
KeyVaultAccessControlClient
✓ from azure.keyvault.administration.aio import KeyVaultAccessControlClient
✗ from azure.keyvault.administration import KeyVaultAccessControlClient
For asynchronous operations, import clients from the `aio` namespace. The synchronous client is the default.
This quickstart demonstrates how to authenticate with Azure Key Vault Managed HSM using `DefaultAzureCredential` and then list role definitions using the `KeyVaultAccessControlClient`. It requires setting the `KEY_VAULT_MANAGED_HSM_URL` environment variable to your Managed HSM's URL. For local development, ensure you are logged in via Azure CLI (`az login`) and have sufficient permissions (e.g., 'Managed HSM Administrator' role).
import os
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
# Set these environment variables or ensure DefaultAzureCredential can find them
# For local development, 'az login' is often sufficient.
# KEY_VAULT_MANAGED_HSM_URL should be in the format: "https://<your-hsm-name>.managedhsm.azure.net"
hsm_url = os.environ.get("KEY_VAULT_MANAGED_HSM_URL", "<your-hsm-url>")
if hsm_url == "<your-hsm-url>":
raise ValueError("Please set the KEY_VAULT_MANAGED_HSM_URL environment variable.")
try:
# Authenticate using DefaultAzureCredential
credential = DefaultAzureCredential()
# Create a KeyVaultAccessControlClient
access_control_client = KeyVaultAccessControlClient(vault_url=hsm_url, credential=credential)
print(f"Listing role definitions for {hsm_url}...")
role_definitions = access_control_client.list_role_definitions()
for role_def in role_definitions:
print(f" Role Name: {role_def.role_name}, ID: {role_def.id}")
print("Successfully listed role definitions.")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure that your environment is authenticated (e.g., via 'az login') ")
print("and the service principal/user has 'Managed HSM Administrator' or equivalent RBAC role on the HSM.")
Debug
Known issues
breakingThis library is exclusively for Azure Key Vault Managed HSM. It will NOT work with standard Azure Key Vault instances. Attempting to use it with a standard Key Vault will result in errors.fixEnsure you are targeting an Azure Key Vault Managed HSM instance. For standard Key Vaults, use `azure-keyvault-keys`, `azure-keyvault-secrets`, or `azure-keyvault-certificates` libraries.
affects: All versions
gotchaAuthentication requires proper setup of `DefaultAzureCredential`. This often means logging in via Azure CLI (`az login`), setting specific environment variables (e.g., `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`), or configuring managed identities in Azure. Incorrect authentication setup is a common source of errors.fixRefer to the `azure-identity` documentation for detailed authentication methods. For local development, ensure you run `az login` or set required service principal environment variables.
affects: All versions
gotchaOperations on Managed HSMs require specific Azure RBAC permissions. Simply having contributor access on the resource group is often insufficient. For administration tasks like managing role definitions or performing backups, roles like 'Managed HSM Administrator' or 'Managed HSM Crypto User' are typically required.fixGrant the appropriate RBAC roles directly on the Managed HSM resource to the identity used for authentication (user, service principal, or managed identity).
affects: All versions
gotchaThe library provides both synchronous and asynchronous (async) clients. Asynchronous clients are located in the `azure.keyvault.administration.aio` namespace (e.g., `azure.keyvault.administration.aio.KeyVaultAccessControlClient`). Mixing synchronous and asynchronous client imports or usage can lead to unexpected behavior or runtime errors if not handled correctly within an async event loop.fixIf working with async Python, explicitly import clients from the `aio` namespace and ensure your code is run within an `asyncio` event loop. Install an async transport like `aiohttp` if using async clients (`pip install aiohttp`).
affects: All versions
breakingPython 3.9 or later is required for this package. Older Python versions (3.8 and below) are no longer supported by the Azure SDK for Python.fixUpgrade your Python environment to 3.9 or a newer supported version.
affects: 4.x.x (specifically from 4.6.0 onwards, building on earlier changes in related libraries that dropped 3.7 and 3.8 support).
Audit
Dependencies
azure-identityrequiredRequired for Azure Active Directory authentication with Azure services.
azure-corerequiredBase package for Azure SDK client libraries, providing shared primitives.