Azure Key Vault Administration Client Library for Python

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Grant the appropriate RBAC roles directly on the Managed HSM resource to the identity used for authentication (user, service principal, or managed identity).
• gotcha 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.
  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`).
• breaking 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.
  Fix: Upgrade your Python environment to 3.9 or a newer supported version.

Install

• pip install azure-keyvault-administration azure-identity Install with pip

Imports

• 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

  For asynchronous operations, import clients from the `aio` namespace. The synchronous client is the default.

Quickstart

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.")