Partilhar via

Biblioteca de cliente de Certificados do Azure Key Vault para Python – versão 4.7.0

  • Artigo

O Azure Key Vault ajuda a resolver os seguintes problemas:

  • Gestão de certificados (esta biblioteca) – criar, gerir e implementar certificados SSL/TLS públicos e privados
  • 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) – armazene e controle de forma segura o acesso a tokens, palavras-passe, certificados, chaves de API e outros segredos
  • Administração do cofre (azure-keyvault-administration) – controlo de acesso baseado em funções (RBAC) e opções de cópia de segurança e restauro ao nível do cofre

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. O 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 o pacote

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

pip install azure-keyvault-certificates azure-identity

A azure-identity é utilizada 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 um CertificateClient, bem como de um URL do cofre e de 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 e produção locais. 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 cliente

Depois de configurar o ambiente para o DefaultAzureCredential para utilizar um método de autenticação adequado, pode fazer o seguinte para criar um cliente de certificado (substituindo o valor de VAULT_URL pelo URL do cofre):

VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = CertificateClient(vault_url=VAULT_URL, credential=credential)

NOTA: Em vez disso, para um cliente assíncrono, importe azure.keyvault.certificates.aio's CertificateClient .

Conceitos-chave

CertificateClient

Com um CertificateClient , pode obter certificados do cofre, criar novos certificados e novas versões de certificados existentes, atualizar metadados de certificado e eliminar certificados. Também pode gerir emissores de certificados, contactos e políticas de gestão de certificados. Isto é ilustrado nos exemplos abaixo.

Exemplos

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

Criar um certificado

begin_create_certificate cria um certificado para ser armazenado no Key Vault do Azure. Se já existir um certificado com o mesmo nome, é criada uma nova versão do certificado. Antes de criar um certificado, pode ser criada uma política de gestão para o certificado ou a nossa política predefinida. Este método devolve um poller de operação de execução prolongada.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient, CertificatePolicy

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

create_certificate_poller = certificate_client.begin_create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_poller.result())

Se quiser verificar o estado da criação do certificado, pode chamar status() o poller ou get_certificate_operation com o nome do certificado.

Obter um certificado

get_certificate obtém a versão mais recente de um certificado armazenado anteriormente no Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

certificate = certificate_client.get_certificate("cert-name")

print(certificate.name)
print(certificate.properties.version)
print(certificate.policy.issuer_name)

get_certificate_version obtém uma versão específica de um certificado.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate_version(certificate_name="cert-name", version="cert-version")

print(certificate.name)
print(certificate.properties.version)

Atualizar propriedades de um certificado existente

update_certificate_properties atualiza um certificado armazenado anteriormente no Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# we will now disable the certificate for further use
updated_certificate= certificate_client.update_certificate_properties(
    certificate_name="cert-name", enabled=False
)

print(updated_certificate.name)
print(updated_certificate.properties.enabled)

Eliminar um certificado

begin_delete_certificate pedidos Key Vault eliminar um certificado, devolvendo um poller que lhe permite aguardar a conclusão da eliminação. Aguardar é útil quando o cofre tem a eliminação recuperável ativada e pretende remover (eliminar permanentemente) o certificado o mais rapidamente possível. Quando a eliminação recuperável é desativada, begin_delete_certificate a própria é permanente.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

deleted_certificate_poller = certificate_client.begin_delete_certificate("cert-name")

deleted_certificate = deleted_certificate_poller.result()
print(deleted_certificate.name)
print(deleted_certificate.deleted_on)

Listar propriedades de certificados

list_properties_of_certificates lista as propriedades de todos os certificados na Key Vault especificada.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

certificates = certificate_client.list_properties_of_certificates()

for certificate in certificates:
    # this list doesn't include versions of the certificates
    print(certificate.name)

Operações assíncronas

Esta biblioteca inclui um conjunto completo de APIs assíncronas. Para utilizá-las, primeiro tem de instalar um transporte assíncrono, como o aiohttp. Veja a documentação do azure-core para obter mais informações.

Os clientes assíncrono e as credenciais devem ser fechados quando já não forem necessários. Estes objetos são gestores de contexto assíncrono e definem métodos assíncronas close . Por exemplo:

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()

# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

Criar um certificado de forma assíncrona

create_certificate cria um certificado a armazenar no Key Vault do Azure. Se já existir um certificado com o mesmo nome, é criada uma nova versão do certificado. Antes de criar um certificado, pode ser criada uma política de gestão para o certificado ou a nossa política predefinida. A aguardar create_certificate devolve o certificado criado se a criação for bem-sucedida e um CertificateOperation , se não for.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
from azure.keyvault.certificates import CertificatePolicy

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

create_certificate_result = await certificate_client.create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_result)

Listar assíncronamente as propriedades dos certificados

list_properties_of_certificates lista todas as propriedades dos certificados no cofre do cliente:

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

certificates = certificate_client.list_properties_of_certificates()
async for certificate in certificates:
    print(certificate.name)

Resolução de problemas

Veja o azure-keyvault-certificatesguia 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 chave que não existe no cofre, CertificateClient gera ResourceNotFoundError:

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    certificate_client.get_certificate("which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

Registo

Esta biblioteca utiliza a biblioteca de registo padrão para registo. As informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível da INFORMAÇÃO.

O registo de nível de DEBUG detalhado, incluindo os corpos de pedido/resposta e os cabeçalhos não retotados, pode ser ativado num cliente com o logging_enable argumento :

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
import sys
import logging

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

credential = DefaultAzureCredential()

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CertificateClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

O registo de rastreio de rede também pode ser ativado para qualquer operação única:

certificate = certificate_client.get_certificate(certificate_name="cert-name", logging_enable=True)

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 | |-------------|-------------| | hello_world.py (versão assíncrona) | criar/obter/atualizar/eliminar certificados | | backup_restore_operations.py (versão assíncrona) | criar cópias de segurança e recuperar certificados | | import_certificate.py (versão assíncrona) | importar certificados com formato PKCS#12 (PFX) e PEM para Key Vault | | list_operations.py (versão assíncrona) | listar certificados | | recover_purge_operations.py (versão assíncrona) | recuperar e remover certificados | | issuers.py (versão assíncrona) | gerir emissores de certificados | | contacts.py (versão assíncrona) | gerir contactos de certificado | | parse_certificate.py (versão assíncrona) | extrair a chave privada de um certificado |

Documentação adicional

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

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