Azure Key Vault Administration client library for Python

Note: The Administration library only works with [Managed HSM][managed_hsm] – functions targeting a Key Vault will fail.

Azure Key Vault helps solve the following problems:

• Vault administration (this library) - role-based access control (RBAC), and vault-level backup and restore options
• Cryptographic key management (azure-keyvault-keys) - create, store, and control access to the keys used to encrypt your data
• Secrets management (azure-keyvault-secrets) - securely store and control access to tokens, passwords, certificates, API keys, and other secrets
• Certificate management (azure-keyvault-certificates) - create, manage, and deploy public and private SSL/TLS certificates

[Source code][library_src] | [Package (PyPI)][pypi_package_administration] | Package (Conda) | [API reference documentation][reference_docs] | [Product documentation][keyvault_docs] | [Samples][administration_samples]

Disclaimer

Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691. Python 3.9 or later is required to use this package. For more details, please refer to Azure SDK for Python version support policy.

Getting started

Install packages

Install [azure-keyvault-administration][pypi_package_administration] and [azure-identity][azure_identity_pypi] with [pip][pip]:

pip install azure-keyvault-administration azure-identity

[azure-identity][azure_identity] is used for Azure Active Directory authentication as demonstrated below.

Prerequisites

• An [Azure subscription][azure_sub]
• Python 3.9 or later
• An existing [Key Vault Managed HSM][managed_hsm]. If you need to create one, you can do so using the Azure CLI by following the steps in [this document][managed_hsm_cli].

Authenticate the client

In order to interact with the Azure Key Vault service, you will need an instance of either a KeyVaultAccessControlClient or KeyVaultBackupClient, as well as a vault url (which you may see as "DNS Name" in the Azure Portal) and a credential object. This document demonstrates using a [DefaultAzureCredential][default_cred_ref], which is appropriate for most scenarios, including local development and production environments. We recommend using a [managed identity][managed_identity] for authentication in production environments.

See [azure-identity][azure_identity] documentation for more information about other methods of authentication and their corresponding credential types.

Create a KeyVaultAccessControlClient

After configuring your environment for the [DefaultAzureCredential][default_cred_ref] to use a suitable method of authentication, you can do the following to create an access control client (replacing the value of vault_url with your Managed HSM's URL):

<!-- SNIPPET:access_control_operations.create_an_access_control_client -->

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient

MANAGED_HSM_URL = os.environ["MANAGED_HSM_URL"]
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(vault_url=MANAGED_HSM_URL, credential=credential)

<!-- END SNIPPET -->

NOTE: For an asynchronous client, import azure.keyvault.administration.aio's KeyVaultAccessControlClient instead.

Create a KeyVaultBackupClient

After creating a user-assigned [managed identity][managed_identity] and [granting it access to your Managed HSM][managed_identity_backup_setup], you can do the following to create a backup client (setting the value of CLIENT_ID to your managed identity's client ID):

<!-- SNIPPET:backup_restore_operations.create_a_backup_restore_client -->

from azure.identity import ManagedIdentityCredential
from azure.keyvault.administration import KeyVaultBackupClient

MANAGED_HSM_URL = os.environ["MANAGED_HSM_URL"]
MANAGED_IDENTITY_CLIENT_ID = os.environ["CLIENT_ID"]
credential = ManagedIdentityCredential(client_id=MANAGED_IDENTITY_CLIENT_ID)
client = KeyVaultBackupClient(vault_url=MANAGED_HSM_URL, credential=credential)

<!-- END SNIPPET -->

Using the ManagedIdentityCredential is preferred in order to enable authenticating backup and restore operations with Managed Identity. Any other azure-identity credential could be provided instead if SAS tokens are used in these operations.

See [azure-identity][managed_identity_ref] documentation for more information on Managed Identity authentication.

NOTE: For an asynchronous client, import azure.keyvault.administration.aio's KeyVaultBackupClient instead.

Create a KeyVaultSettingsClient

After configuring your environment for the [DefaultAzureCredential][default_cred_ref] to use a suitable method of authentication, you can do the following to create a settings client (replacing the value of vault_url with your Managed HSM's URL):

<!-- SNIPPET:settings_operations.create_a_settings_client -->

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultSettingsClient

MANAGED_HSM_URL = os.environ["MANAGED_HSM_URL"]
credential = DefaultAzureCredential()
client = KeyVaultSettingsClient(vault_url=MANAGED_HSM_URL, credential=credential)

<!-- END SNIPPET -->

NOTE: For an asynchronous client, import azure.keyvault.administration.aio's KeyVaultSettingsClient instead.

Key concepts

Role definition

A role definition defines the operations that can be performed, such as read, write, and delete. It can also define the operations that are excluded from allowed operations.

A role definition is specified as part of a role assignment.

Role assignment

A role assignment is the association of a role definition to a service principal. They can be created, listed, fetched individually, and deleted.

KeyVaultAccessControlClient

A KeyVaultAccessControlClient manages role definitions and role assignments.

KeyVaultBackupClient

A KeyVaultBackupClient performs full key backups, full key restores, and selective key restores.

Pre-Backup Operation

A pre-backup operation represents a long-running operation that checks if it is possible to perform a full key backup.

Backup Operation

A backup operation represents a long-running operation for a full key backup.

Pre-Restore Operation

A pre-restore operation represents a long-running operation that checks if it is possible to perform a full key restore from a backup.

Restore Operation

A restore operation represents a long-running operation for both a full key and selective key restore.

KeyVaultSettingsClient

A KeyVaultSettingsClient manages Managed HSM account settings.

Examples

This section contains code snippets covering common tasks:

• Access control
  • List all role definitions
  • Set, get, and delete a role definition
  • List all role assignments
  • Create, get, and delete a role assignment
• Backup and restore
  • Run a pre-backup check
  • Perform a full key backup
  • Run a pre-restore check
  • Perform a full key restore
  • Perform a selective key restore

List all role definitions

list_role_definitions can be used by a KeyVaultAccessControlClient to list the role definitions available for assignment.

<!-- SNIPPET:access_control_operations.list_role_definitions -->

from azure.keyvault.administration import KeyVaultRoleScope

role_definitions = client.list_role_definitions(scope=KeyVaultRoleScope.GLOBAL)
for definition in role_definitions:
    print(f"Role name: {definition.role_name}; Role definition name: {definition.name}")

<!-- END SNIPPET -->

Set, get, and delete a role definition

set_role_definition can be used by a KeyVaultAccessControlClient to either create a custom role definition or update an existing definition with the specified unique name (a UUID).

<!-- SNIPPET:access_control_operations.create_a_role_definition -->

from azure.keyvault.administration import KeyVaultDataAction, KeyVaultPermission, KeyVaultRoleScope

role_name = "customRole"
scope = KeyVaultRoleScope.GLOBAL
permissions = [KeyVaultPermission(data_actions=[KeyVaultDataAction.CREATE_HSM_KEY])]
role_definition = client.set_role_definition(scope=scope, role_name=role_name, permissions=permissions)

<!-- END SNIPPET --> <!-- SNIPPET:access_control_operations.update_a_role_definition -->

new_permissions = [
    KeyVaultPermission(
        data_actions=[KeyVaultDataAction.READ_HSM_KEY],
        not_data_actions=[KeyVaultDataAction.CREATE_HSM_KEY]
    )
]
unique_definition_name = role_definition.name
updated_definition = client.set_role_definition(
    scope=scope, name=unique_definition_name, role_name=role_name, permissions=new_permissions
)

<!-- END SNIPPET -->

get_role_definition can be used by a KeyVaultAccessControlClient to fetch a role definition with the specified scope and unique name.

<!-- SNIPPET:access_control_operations.get_a_role_definition -->