{"id":1926,"library":"azure-keyvault-administration","title":"Azure Key Vault Administration Client Library for Python","description":"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.","status":"active","version":"4.6.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-administration","tags":["Azure","Key Vault","Managed HSM","Administration","RBAC","Security","Cloud"],"install":[{"cmd":"pip install azure-keyvault-administration azure-identity","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for Azure Active Directory authentication with Azure services.","package":"azure-identity"},{"reason":"Base package for Azure SDK client libraries, providing shared primitives.","package":"azure-core"}],"imports":[{"note":"Client for managing role-based access to Key Vault Managed HSM.","symbol":"KeyVaultAccessControlClient","correct":"from azure.keyvault.administration import KeyVaultAccessControlClient"},{"note":"Client for performing backup and restore operations on Key Vault Managed HSM.","symbol":"KeyVaultBackupClient","correct":"from azure.keyvault.administration import KeyVaultBackupClient"},{"note":"Standard credential for authenticating with Azure services across various environments.","symbol":"DefaultAzureCredential","correct":"from azure.identity import DefaultAzureCredential"},{"note":"Enum defining well-known role scopes for RBAC.","symbol":"KeyVaultRoleScope","correct":"from azure.keyvault.administration import KeyVaultRoleScope"},{"note":"For asynchronous operations, import clients from the `aio` namespace. The synchronous client is the default.","wrong":"from azure.keyvault.administration import KeyVaultAccessControlClient","symbol":"KeyVaultAccessControlClient","correct":"from azure.keyvault.administration.aio import KeyVaultAccessControlClient"}],"quickstart":{"code":"import os\nfrom azure.identity import DefaultAzureCredential\nfrom azure.keyvault.administration import KeyVaultAccessControlClient\n\n# Set these environment variables or ensure DefaultAzureCredential can find them\n# For local development, 'az login' is often sufficient.\n# KEY_VAULT_MANAGED_HSM_URL should be in the format: \"https://<your-hsm-name>.managedhsm.azure.net\"\nhsm_url = os.environ.get(\"KEY_VAULT_MANAGED_HSM_URL\", \"<your-hsm-url>\")\n\nif hsm_url == \"<your-hsm-url>\":\n    raise ValueError(\"Please set the KEY_VAULT_MANAGED_HSM_URL environment variable.\")\n\ntry:\n    # Authenticate using DefaultAzureCredential\n    credential = DefaultAzureCredential()\n\n    # Create a KeyVaultAccessControlClient\n    access_control_client = KeyVaultAccessControlClient(vault_url=hsm_url, credential=credential)\n\n    print(f\"Listing role definitions for {hsm_url}...\")\n    role_definitions = access_control_client.list_role_definitions()\n    for role_def in role_definitions:\n        print(f\"  Role Name: {role_def.role_name}, ID: {role_def.id}\")\n\n    print(\"Successfully listed role definitions.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure that your environment is authenticated (e.g., via 'az login') \")\n    print(\"and the service principal/user has 'Managed HSM Administrator' or equivalent RBAC role on the HSM.\")\n","lang":"python","description":"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)."},"warnings":[{"fix":"Ensure 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.","message":"This 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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Refer to the `azure-identity` documentation for detailed authentication methods. For local development, ensure you run `az login` or set required service principal environment variables.","message":"Authentication 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Grant the appropriate RBAC roles directly on the Managed HSM resource to the identity used for authentication (user, service principal, or managed identity).","message":"Operations 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If 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`).","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to 3.9 or a newer supported version.","message":"Python 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.","severity":"breaking","affected_versions":"4.x.x (specifically from 4.6.0 onwards, building on earlier changes in related libraries that dropped 3.7 and 3.8 support)."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}