Share via

Biblioteca de cliente da Administração Key Vault do Azure para Python – versão 4.3.0

  • Artigo

Nota: A biblioteca de Administração só funciona com o HSM Gerido – as funções direcionadas para um Key Vault falharão.

O Azure Key Vault ajuda a resolver os seguintes problemas:

  • Administração do cofre (esta biblioteca) – controlo de acesso baseado em funções (RBAC) e opções de cópia de segurança e restauro ao nível do cofre
  • Gestão de chaves criptográficas (azure-keyvault-keys) – criar, armazenar e controlar o acesso às chaves utilizadas para encriptar os seus dados
  • Gestão de segredos (azure-keyvault-secrets) – armazenar e controlar de forma segura o acesso a tokens, palavras-passe, certificados, chaves de API e outros segredos
  • Gestão de certificados (azure-keyvault-certificates) – criar, gerir e implementar certificados SSL/TLS públicos e privados

Código fonte | Pacote (PyPI) | Pacote (Conda) | Documentação | de referência da APIDocumentação do | produto Exemplos

Exclusão de Responsabilidade

O suporte de pacotes Python do SDK do Azure para Python 2.7 terminou a 01 de janeiro de 2022. Para obter mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.Python 3.7 ou posterior é necessário para utilizar este pacote. Para obter mais detalhes, veja Azure SDK for Python version support policy (Política de suporte de versões do Azure SDK para Python).

Introdução

Instalar pacotes

Instale azure-keyvault-administration e azure-identity com pip:

pip install azure-keyvault-administration azure-identity

azure-identity é utilizado para a autenticação do Azure Active Directory, conforme demonstrado abaixo.

Pré-requisitos

Autenticar o cliente

Para interagir com o serviço Key Vault do Azure, precisará de uma instância de KeyVaultAccessControlClient ou KeyVaultBackupClient, bem como de um url do cofre (que poderá ver como "Nome DNS" no portal do Azure) e um objeto de credencial. Este documento demonstra a utilização de um DefaultAzureCredential, que é adequado para a maioria dos cenários, incluindo ambientes de desenvolvimento local e de produção. Recomendamos a utilização de uma identidade gerida para autenticação em ambientes de produção.

Veja a documentação do azure-identity para obter mais informações sobre outros métodos de autenticação e os respetivos tipos de credenciais correspondentes.

Criar um KeyVaultAccessControlClient

Depois de configurar o seu ambiente para o DefaultAzureCredential para utilizar um método de autenticação adequado, pode fazer o seguinte para criar um cliente de controlo de acesso (substituindo o valor de vault_url pelo URL do HSM Gerido):

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

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

NOTA: Para um cliente assíncrono, importe azure.keyvault.administration.aio's KeyVaultAccessControlClient em vez disso.

Criar um KeyVaultBackupClient

Depois de configurar o seu ambiente para o DefaultAzureCredential utilizar um método de autenticação adequado, pode fazer o seguinte para criar um cliente de cópia de segurança (substituindo o valor de vault_url pelo URL do HSM Gerido):

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

credential = DefaultAzureCredential()

client = KeyVaultBackupClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

NOTA: Para um cliente assíncrono, importe azure.keyvault.administration.aio's KeyVaultBackupClient em vez disso.

Criar um KeyVaultSettingsClient

Depois de configurar o seu ambiente para o DefaultAzureCredential para utilizar um método de autenticação adequado, pode fazer o seguinte para criar um cliente de definições (substituindo o valor de vault_url pelo URL do HSM Gerido):

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

credential = DefaultAzureCredential()

client = KeyVaultSettingsClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

NOTA: Para um cliente assíncrono, importe azure.keyvault.administration.aio's KeyVaultSettingsClient em vez disso.

Conceitos-chave

Definição de função

Uma definição de função define as operações que podem ser executadas, como leitura, escrita e eliminação. Também pode definir as operações excluídas das operações permitidas.

Uma definição de função é especificada como parte de uma atribuição de função.

Atribuição de função

Uma atribuição de função é a associação de uma definição de função a um principal de serviço. Podem ser criados, listados, obtidos individualmente e eliminados.

KeyVaultAccessControlClient

A KeyVaultAccessControlClient gere definições de funções e atribuições de funções.

KeyVaultBackupClient

A KeyVaultBackupClient executa cópias de segurança de chaves completas, restauros de chaves completas e restauros seletivos de chaves.

KeyVaultSettingsClient

A KeyVaultSettingsClient gere as definições da conta HSM Gerida.

Exemplos

Esta secção contém fragmentos de código que abrangem tarefas comuns:

Listar todas as definições de função

Liste as definições de função disponíveis para atribuição.

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

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# this will list all role definitions available for assignment
role_definitions = client.list_role_definitions(KeyVaultRoleScope.GLOBAL)

for definition in role_definitions:
    print(definition.id)
    print(definition.role_name)
    print(definition.description)

Definir, obter e eliminar uma definição de função

set_role_definition pode ser utilizado para criar uma definição de função personalizada ou atualizar uma definição existente com o nome especificado.

import uuid
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import (
    KeyVaultAccessControlClient,
    KeyVaultDataAction,
    KeyVaultPermission,
    KeyVaultRoleScope
)

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# create a custom role definition
permissions = [KeyVaultPermission(allowed_data_actions=[KeyVaultDataAction.READ_HSM_KEY])]
created_definition = client.set_role_definition(KeyVaultRoleScope.GLOBAL, permissions=permissions)

# update the custom role definition
permissions = [
    KeyVaultPermission(allowed_data_actions=[], denied_data_actions=[KeyVaultDataAction.READ_HSM_KEY])
]
updated_definition = client.set_role_definition(
    KeyVaultRoleScope.GLOBAL, permissions=permissions, role_name=created_definition.name
)

# get the custom role definition
definition = client.get_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)

# delete the custom role definition
deleted_definition = client.delete_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)

Listar todas as atribuições de funções

Antes de criar uma nova atribuição de função no fragmento seguinte, liste todas as atribuições de funções atuais:

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

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# this will list all role assignments
role_assignments = client.list_role_assignments(KeyVaultRoleScope.GLOBAL)

for assignment in role_assignments:
    print(assignment.name)
    print(assignment.principal_id)
    print(assignment.role_definition_id)

Criar, obter e eliminar uma atribuição de função

Atribuir uma função a um principal de serviço. Isto requer um ID de definição de função e um ID de objeto do principal de serviço. Pode utilizar um ID da lista obtida de definições de função para as primeiras e uma atribuição da principal_id lista obtida no fragmento acima para este último.

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

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# Replace <role-definition-id> with the id of a definition from the fetched list from an earlier example
role_definition_id = "<role-definition-id>"
# Replace <service-principal-object-id> with the principal_id of an assignment returned from the previous example
principal_id = "<service-principal-object-id>"

# first, let's create the role assignment
role_assignment = client.create_role_assignment(KeyVaultRoleScope.GLOBAL, role_definition_id, principal_id)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

# now, we get it
role_assignment = client.get_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

# finally, we delete this role assignment
role_assignment = client.delete_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

Efetuar uma cópia de segurança de chave completa

Crie uma cópia de segurança de toda a sua coleção de chaves. O arquivo de cópias de segurança para cópias de segurança de chaves completas é um contentor de armazenamento de blobs com a autenticação Assinatura de Acesso Partilhado.

Para obter mais detalhes sobre como criar um token de SAS com o BlobServiceClient, veja o exemplo aqui. Em alternativa, é possível gerar um token de SAS no Explorador de Armazenamento

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

credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

# blob storage container URL, for example https://<account name>.blob.core.windows.net/backup
blob_storage_url = "<your-blob-storage-url>"
sas_token = "<your-sas-token>"  # replace with a sas token to your storage account

# Backup is a long-running operation. The client returns a poller object whose result() method
# blocks until the backup is complete, then returns an object representing the backup operation.
backup_poller = client.begin_backup(blob_storage_url, sas_token)
backup_operation = backup_poller.result()

# this is the Azure Storage Blob URL of the backup
print(backup_operation.folder_url)

Executar um restauro de chave completa

Restaure toda a sua coleção de chaves a partir de uma cópia de segurança. A origem de dados para um restauro de chave completa é um blob de armazenamento acedido através da autenticação Assinatura de Acesso Partilhado. Também precisará do azure_storage_blob_container_uri fragmento acima.

Para obter mais detalhes sobre como criar um token de SAS com o BlobServiceClient, veja o exemplo aqui. Em alternativa, é possível gerar um token de SAS no Explorador de Armazenamento

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

credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

sas_token = "<your-sas-token>"  # replace with a sas token to your storage account

# URL to a storage blob, for example https://<account name>.blob.core.windows.net/backup/mhsm-account-2020090117323313
blob_url = "<your-blob-url>"

# Restore is a long-running operation. The client returns a poller object whose wait() method
# blocks until the restore is complete.
restore_poller = client.begin_restore(blob_url, sas_token)
restore_poller.wait()

Resolução de problemas

Veja o azure-keyvault-administrationguia de resolução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Geral

Key Vault clientes geram exceções definidas no azure-core. Por exemplo, se tentar obter uma atribuição de função que não existe, KeyVaultAccessControlClient gera ResourceNotFoundError:

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

try:
    client.get_role_assignment("/", "which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

Os clientes da biblioteca de Administração só podem ser utilizados para realizar operações num HSM gerido, pelo que tentar fazê-lo num Key Vault irá gerar um erro.

Passos seguintes

Estão disponíveis vários exemplos no repositório do GitHub do Azure SDK para Python. Estes exemplos fornecem código de exemplo para cenários de Key Vault adicionais: | Ficheiro | Descrição | |-------------|-------------| | access_control_operations.py | criar/atualizar/eliminar definições de função e atribuições de funções | | access_control_operations_async.py | criar/atualizar/eliminar definições de função e atribuições de funções com um cliente assíncrono | | backup_restore_operations.py | cópia de segurança completa e restauro | | backup_restore_operations_async.py | cópia de segurança completa e restauro com um cliente assíncrono | | settings_operations.py | definições de Key Vault de lista e atualização | | settings_operations_async.py | listar e atualizar definições de Key Vault com um cliente assíncrono |

Documentação adicional

Para obter documentação mais extensa sobre o Azure Key Vault, veja a documentação de referência da API.

Para obter documentação mais extensa sobre o HSM Gerido, veja a documentação do serviço.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, veja a Code of Conduct FAQ (FAQ do Código de Conduta) ou envie um e-mail para opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões