Azure Key Vault Security Domain Client Library

Warnings

• breaking As a beta library (`1.0.0b1`), `azure-keyvault-securitydomain` is subject to breaking changes in future releases before reaching general availability. APIs, models, and behaviors may change without backward compatibility guarantees.
  Fix: Monitor release notes for subsequent versions and update code as necessary. Test thoroughly when upgrading.
• gotcha This library is specifically designed for Azure Key Vault Managed HSMs, not standard Azure Key Vaults. Attempting to use it with a standard Key Vault will result in errors.
  Fix: Ensure you are interacting with an Azure Key Vault Managed HSM resource. Create one if necessary via Azure CLI or Azure Portal.
• gotcha Authentication with Azure services, including Managed HSM, requires proper configuration for `DefaultAzureCredential`. In development, this often means logging in via Azure CLI or setting environment variables (`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`). In production, Managed Identities are recommended.
  Fix: Refer to the `azure-identity` documentation for setting up appropriate credentials for your environment. Ensure your identity has the necessary RBAC roles (e.g., 'Managed HSM Security Domain Contributor') on the Managed HSM.
• gotcha Security domain operations (e.g., download, upload) are long-running and return `LROPoller` objects. You must call `.result()` on the poller to wait for the operation to complete and retrieve the final result or status.
  Fix: Always call `.result()` on the `LROPoller` returned by `begin_download`, `begin_upload`, etc., to get the operation's outcome. Example: `security_domain = client.begin_download(...).result()`.
• breaking Azure Key Vault is shifting to Azure Role-Based Access Control (RBAC) as the default access control model, deprecating older vault access policies. While this isn't a direct API change in `azure-keyvault-securitydomain`, it critically impacts how permissions are granted to your application's identity accessing the Managed HSM. Older API versions will be retired by February 27, 2027.
  Fix: Migrate access control for your Managed HSMs to Azure RBAC and ensure your deployment scripts use API version `2026-02-01` or later for Key Vault/Managed HSM creation and management. Review and assign appropriate RBAC roles.
• gotcha Actual `begin_download` and `begin_upload` operations require a collection of RSA public keys (certificates) and a 'quorum' to encrypt/decrypt the security domain using Shamir's Secret Sharing Algorithm. Generating and managing these keys securely is a complex prerequisite.
  Fix: Generate the required number of RSA key pairs (typically 3-10) and manage their private keys securely offline. Extract the public keys (e.g., from self-signed certificates) and pass them to the `certificate_info` parameter, along with the `quorum` (minimum number of private keys needed for decryption).
• gotcha Typing issues have been reported for `azure-keyvault-securitydomain` with specific `pyright` versions (e.g., 1.1.408). This could lead to static analysis failures or runtime issues in environments with strict type checking.
  Fix: Monitor for library updates that address typing fixes. If encountering issues, temporarily adjust `pyright` configuration or type-checking strictness, or contribute fixes to the Azure SDK for Python.

Install

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

Imports

• SecurityDomainClient

  from azure.keyvault.securitydomain import SecurityDomainClient

• DefaultAzureCredential

  from azure.identity import DefaultAzureCredential

• SecurityDomainJsonWebKey

  from azure.keyvault.securitydomain.models import SecurityDomainJsonWebKey

  Used for representing JWK for security domain operations.
• SecurityDomain

  from azure.keyvault.securitydomain.models import SecurityDomain

  Model for a security domain object, often returned by download operations.
• SecurityDomainOperationStatus

  from azure.keyvault.securitydomain.models import SecurityDomainOperationStatus

  Model for the status of a security domain operation.

Quickstart

This quickstart demonstrates how to instantiate the `SecurityDomainClient` using `DefaultAzureCredential` for authentication. It highlights the prerequisites for performing actual security domain operations like downloading, which include an Azure Key Vault Managed HSM and specific key management for encryption.

import os
from azure.identity import DefaultAzureCredential
from azure.keyvault.securitydomain import SecurityDomainClient

# Set your Managed HSM URL as an environment variable
# Example: 'https://my-managed-hsm.managedhsm.azure.net/'
VAULT_URL = os.environ.get("AZURE_MANAGEDHSM_URL", "<your-managed-hsm-url>")

# --- Prerequisites for actual operations ---
# For actual download/upload, you would need:
# 1. An active Azure subscription.
# 2. An existing Azure Key Vault Managed HSM (not a standard Key Vault).
# 3. RSA key pairs (public keys for 'sd_wrapping_keys') and a specified quorum.
# 4. Proper RBAC permissions for your identity to perform security domain operations.
#    (e.g., 'Managed HSM Security Domain Contributor' role).

if VAULT_URL == '<your-managed-hsm-url>':
    print("Please set the AZURE_MANAGEDHSM_URL environment variable or replace the placeholder.")
    exit(1)

try:
    # Authenticate using DefaultAzureCredential
    # This will try various methods: environment variables, managed identity, Azure CLI, etc.
    credential = DefaultAzureCredential()
    
    # Create a SecurityDomainClient
    client = SecurityDomainClient(vault_url=VAULT_URL, credential=credential)
    print(f"Successfully created SecurityDomainClient for: {VAULT_URL}")

    # --- Example: (Conceptual) Download a security domain ---
    # This operation requires 'certificate_info' (public keys) and 'quorum'.
    # It's a long-running operation, so 'begin_download' returns a poller.
    # For a real scenario, 'certs_object' would be a list of SecurityDomainJsonWebKey objects
    # and 'quorum' would be an integer.
    # Example: certs_object = [SecurityDomainJsonWebKey(...), ...]
    #          quorum = 2
    # poller = client.begin_download(certificate_info=certs_object, quorum=quorum)
    # security_domain = poller.result()
    # print("Security Domain downloaded.")

    # For demonstration, we'll just show client creation and a dummy print.
    print("Client created. Actual security domain operations require a Managed HSM and specific certificate setup.")

except Exception as e:
    print(f"An error occurred: {e}")