azure.keyvault.administration package

class azure.keyvault.administration.ApiVersion(value)

Key Vault API versions supported by this package

V7_2 = '7.2'

V7_3_PREVIEW = '7.3-preview'

this is the default version

class azure.keyvault.administration.KeyVaultAccessControlClient(vault_url: str, credential: TokenCredential, **kwargs: Any)

Manages role-based access to Azure Key Vault.

Parameters

• vault_url (str) – URL of the vault the client will manage. This is also called the vault’s “DNS Name”.

• credential – an object which can provide an access token for the vault, such as a credential from azure.identity

close() → None

Close sockets opened by the client.

Calling this method is unnecessary when using the client as a context manager.

create_role_assignment(scope: Union[str, KeyVaultRoleScope], definition_id: str, principal_id: str, **kwargs: Any) → KeyVaultRoleAssignment

Create a role assignment.

Parameters

• scope (str or KeyVaultRoleScope) – scope the role assignment will apply over. KeyVaultRoleScope defines common broad scopes. Specify a narrower scope as a string.

• definition_id (str) – ID of the role’s definition

• principal_id (str) – Azure Active Directory object ID of the principal which will be assigned the role. The principal can be a user, service principal, or security group.

Keyword Arguments

name (str or uuid.UUID) – a name for the role assignment. Must be a UUID.

Return type

KeyVaultRoleAssignment

delete_role_assignment(scope: Union[str, KeyVaultRoleScope], name: Union[str, UUID], **kwargs: Any) → None

Delete a role assignment.

Parameters

• scope (str or KeyVaultRoleScope) – the assignment’s scope, for example “/”, “/keys”, or “/keys/<specific key identifier>” KeyVaultRoleScope defines common broad scopes. Specify a narrower scope as a string.

• name (str or uuid.UUID) – the role assignment’s name.

Returns

None

delete_role_definition(scope: Union[str, KeyVaultRoleScope], name: Union[str, UUID], **kwargs: Any) → None

Deletes a custom role definition.

Parameters

• scope (str or KeyVaultRoleScope) – scope of the role definition. KeyVaultRoleScope defines common broad scopes. Specify a narrower scope as a string. Managed HSM only supports ‘/’, or KeyVaultRoleScope.GLOBAL.

• name (str or uuid.UUID) – the role definition’s name.

Returns

None

get_role_assignment(scope: Union[str, KeyVaultRoleScope], name: Union[str, UUID], **kwargs: Any) → KeyVaultRoleAssignment

Get a role assignment.

Parameters

• scope (str or KeyVaultRoleScope) – the assignment’s scope, for example “/”, “/keys”, or “/keys/<specific key identifier>” KeyVaultRoleScope defines common broad scopes. Specify a narrower scope as a string.

• name (str or uuid.UUID) – the role assignment’s name.

Return type

KeyVaultRoleAssignment

get_role_definition(scope: Union[str, KeyVaultRoleScope], name: Union[str, UUID], **kwargs: Any) → KeyVaultRoleDefinition

Get the specified role definition.

Parameters

• scope (str or KeyVaultRoleScope) – scope of the role definition. KeyVaultRoleScope defines common broad scopes. Specify a narrower scope as a string. Managed HSM only supports ‘/’, or KeyVaultRoleScope.GLOBAL.

• name (str or uuid.UUID) – the role definition’s name.

Return type

KeyVaultRoleDefinition

list_role_assignments(scope: Union[str, KeyVaultRoleScope], **kwargs: Any) → ItemPaged[KeyVaultRoleAssignment]

List all role assignments for a scope.

Parameters

scope (str or KeyVaultRoleScope) – scope of the role assignments. KeyVaultRoleScope defines common broad scopes. Specify a narrower scope as a string.

Return type

ItemPaged[KeyVaultRoleAssignment]

list_role_definitions(scope: Union[str, KeyVaultRoleScope], **kwargs: Any) → ItemPaged[KeyVaultRoleDefinition]

List all role definitions applicable at and above a scope.

Parameters

scope (str or KeyVaultRoleScope) – scope of the role definitions. KeyVaultRoleScope defines common broad scopes. Specify a narrower scope as a string.

Return type

ItemPaged[KeyVaultRoleDefinition]

set_role_definition(scope: Union[str, KeyVaultRoleScope], **kwargs: Any) → KeyVaultRoleDefinition

Creates or updates a custom role definition.

To update a role definition, specify the definition’s name.

Parameters

scope (str or KeyVaultRoleScope) – scope of the role definition. KeyVaultRoleScope defines common broad scopes. Specify a narrower scope as a string. Managed HSM only supports ‘/’, or KeyVaultRoleScope.GLOBAL.

Keyword Arguments

• name (str or uuid.UUID) – the role definition’s name, a UUID. When this argument has a value, the client will create a new role definition with this name or update an existing role definition, if one exists with the given name. When this argument has no value, a new role definition will be created with a generated name.

• role_name (str) – the role’s display name. If unspecified when creating or updating a role definition, the role name will be set to an empty string.

• description (str) – a description of the role definition. If unspecified when creating or updating a role definition, the description will be set to an empty string.

• permissions (Iterable[KeyVaultPermission]) – the role definition’s permissions. If unspecified when creating or updating a role definition, the role definition will have no action permissions.

• assignable_scopes (Iterable[str] or Iterable[KeyVaultRoleScope]) – the scopes for which the role definition can be assigned.

Returns

The created or updated role definition

Return type

KeyVaultRoleDefinition

property vault_url

class azure.keyvault.administration.KeyVaultBackupClient(vault_url: str, credential: TokenCredential, **kwargs: Any)

Performs Key Vault backup and restore operations.

Parameters

• vault_url (str) – URL of the vault on which the client will operate. This is also called the vault’s “DNS Name”.

• credential – an object which can provide an access token for the vault, such as a credential from azure.identity

begin_backup(blob_storage_url: str, sas_token: str, **kwargs: Any) → LROPoller[KeyVaultBackupResult]

Begin a full backup of the Key Vault.

Parameters

• blob_storage_url (str) – URL of the blob storage container in which the backup will be stored, for example https://<account>.blob.core.windows.net/backup

• sas_token (str) – a Shared Access Signature (SAS) token authorizing access to the blob storage resource

Keyword Arguments

continuation_token (str) – a continuation token to restart polling from a saved state

Returns

An LROPoller instance. Call result() on this object to wait for the operation to complete and get a KeyVaultBackupResult.

Return type

LROPoller[KeyVaultBackupResult]

Example

Create a vault backup

# begin a vault backup
backup_poller = backup_client.begin_backup(container_uri, sas_token)

# check if the backup completed
done = backup_poller.done()

# block until the backup completes
# result() returns an object with a URL of the backup
backup_operation = backup_poller.result()

begin_restore(folder_url: str, sas_token: str, **kwargs: Any) → LROPoller

Restore a Key Vault backup.

This method restores either a complete Key Vault backup or when key_name has a value, a single key.

Parameters

• folder_url (str) – URL of the blob holding the backup. This would be the folder_url of a KeyVaultBackupResult returned by begin_backup(), for example https://<account>.blob.core.windows.net/backup/mhsm-account-2020090117323313

• sas_token (str) – a Shared Access Signature (SAS) token authorizing access to the blob storage resource

Keyword Arguments

• continuation_token (str) – a continuation token to restart polling from a saved state

• key_name (str) – name of a single key in the backup. When set, only this key will be restored.

Return type

LROPoller

Examples

Restore a vault backup

# begin a full vault restore
restore_poller = backup_client.begin_restore(folder_url, sas_token)

# check if the restore completed
done = restore_poller.done()

# wait for the restore to complete
restore_poller.wait()

Restore a single key

# begin a restore of a single key from a backed up vault
restore_poller = backup_client.begin_restore(folder_url, sas_token, key_name=key_name)

# check if the restore completed
done = restore_poller.done()

# wait for the restore to complete
restore_poller.wait()

close() → None

Close sockets opened by the client.

Calling this method is unnecessary when using the client as a context manager.

property vault_url

class azure.keyvault.administration.KeyVaultBackupResult(**kwargs: Any)

A Key Vault full backup operation result

Variables

folder_url (str) – URL of the Azure Blob Storage container containing the backup

class azure.keyvault.administration.KeyVaultDataAction(value)

Supported permissions for data actions.

BACKUP_HSM_KEYS = 'Microsoft.KeyVault/managedHsm/keys/backup/action'

Backup HSM keys.

CREATE_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/create'

Create an HSM key.

DECRYPT_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/decrypt/action'

Decrypt using an HSM key.

DELETE_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/delete'

Delete an HSM key.

DELETE_ROLE_ASSIGNMENT = 'Microsoft.KeyVault/managedHsm/roleAssignments/delete/action'

Delete role assignment.

DELETE_ROLE_DEFINITION = 'Microsoft.KeyVault/managedHsm/roleDefinitions/delete/action'

Delete role definition.

DOWNLOAD_HSM_SECURITY_DOMAIN = 'Microsoft.KeyVault/managedHsm/securitydomain/download/action'

Download an HSM security domain.

DOWNLOAD_HSM_SECURITY_DOMAIN_STATUS = 'Microsoft.KeyVault/managedHsm/securitydomain/download/read'

Check status of HSM security domain download.

ENCRYPT_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/encrypt/action'

Encrypt using an HSM key.

EXPORT_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/export/action'

Export an HSM key.

GET_ROLE_ASSIGNMENT = 'Microsoft.KeyVault/managedHsm/roleAssignments/read/action'

Get role assignment.

IMPORT_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/import/action'

Import an HSM key.

PURGE_DELETED_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/deletedKeys/delete'

Purge a deleted HSM key.

RANDOM_NUMBERS_GENERATE = 'Microsoft.KeyVault/managedHsm/rng/action'

Generate random numbers.

READ_DELETED_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/deletedKeys/read/action'

Read deleted HSM key.

READ_HSM_BACKUP_STATUS = 'Microsoft.KeyVault/managedHsm/backup/status/action'

Read an HSM backup status.

READ_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/read/action'

Read HSM key metadata.

READ_HSM_RESTORE_STATUS = 'Microsoft.KeyVault/managedHsm/restore/status/action'

Read an HSM restore status.

READ_HSM_SECURITY_DOMAIN_STATUS = 'Microsoft.KeyVault/managedHsm/securitydomain/upload/read'

Check the status of the HSM security domain exchange file.

READ_HSM_SECURITY_DOMAIN_TRANSFER_KEY = 'Microsoft.KeyVault/managedHsm/securitydomain/transferkey/read'

Download an HSM security domain transfer key.

READ_ROLE_DEFINITION = 'Microsoft.KeyVault/managedHsm/roleDefinitions/read/action'

Get role definition.

RECOVER_DELETED_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/deletedKeys/recover/action'

Recover deleted HSM key.

RELEASE_KEY = 'Microsoft.KeyVault/managedHsm/keys/release/action'

Release an HSM key using Secure Key Release.

RESTORE_HSM_KEYS = 'Microsoft.KeyVault/managedHsm/keys/restore/action'

Restore HSM keys.

SIGN_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/sign/action'

Sign using an HSM key.

START_HSM_BACKUP = 'Microsoft.KeyVault/managedHsm/backup/start/action'

Start an HSM backup.

START_HSM_RESTORE = 'Microsoft.KeyVault/managedHsm/restore/start/action'

Start an HSM restore.

UNWRAP_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/unwrap/action'

Unwrap using an HSM key.

UPLOAD_HSM_SECURITY_DOMAIN = 'Microsoft.KeyVault/managedHsm/securitydomain/upload/action'

Upload an HSM security domain.

VERIFY_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/verify/action'

Verify using an HSM key.

WRAP_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/wrap/action'

Wrap using an HSM key.

WRITE_HSM_KEY = 'Microsoft.KeyVault/managedHsm/keys/write/action'

Update an HSM key.

WRITE_ROLE_ASSIGNMENT = 'Microsoft.KeyVault/managedHsm/roleAssignments/write/action'

Create or update role assignment.

WRITE_ROLE_DEFINITION = 'Microsoft.KeyVault/managedHsm/roleDefinitions/write/action'

Create or update role definition.

class azure.keyvault.administration.KeyVaultPermission(**kwargs: Any)

Role definition permissions.

Variables

• actions (list[str]) – Action permissions that are granted.

• not_actions (list[str]) – Action permissions that are excluded but not denied. They may be granted by other role definitions assigned to a principal.

• data_actions (list[str]) – Data action permissions that are granted.

• not_data_actions (list[str]) – Data action permissions that are excluded but not denied. They may be granted by other role definitions assigned to a principal.

class azure.keyvault.administration.KeyVaultRoleAssignment(**kwargs: Any)

Represents the assignment to a principal of a role over a scope

Variables

• name (str) – the assignment’s name

• properties (KeyVaultRoleAssignmentProperties) – the assignment’s properties

• role_assignment_id (str) – unique identifier for the assignment

• type (str) – type of the assignment

class azure.keyvault.administration.KeyVaultRoleAssignmentProperties(**kwargs: Any)

Properties of a role assignment

Variables

• principal_id (str) – ID of the principal the assignment applies to. This maps to an Active Directory user, service principal, or security group.

• role_definition_id (str) – ID of the scope’s role definition

• scope (str) – the scope of the assignment

class azure.keyvault.administration.KeyVaultRoleDefinition(**kwargs: Any)

The definition of a role over one or more scopes

Variables

• assignable_scopes (list[str]) – scopes the role can be assigned over

• description (str) – description of the role definition

• id (str) – unique identifier for this role definition

• name (str) – the role definition’s name

• permissions (list[KeyVaultPermission]) – permissions defined for the role

• role_name (str) – the role’s name

• role_type (str) – type of the role

• type (str) – type of the role definition

class azure.keyvault.administration.KeyVaultRoleScope(value)

Collection of well known role scopes. This list is not exhaustive.

GLOBAL = '/'

use this if you want role assignments to apply to everything on the resource

KEYS = '/keys'

use this if you want role assignments to apply to all keys

Subpackages

• azure.keyvault.administration.aio package