Biblioteca de clientes do Azure Key Vault Certificates para Python – versão 4.7.0

O Azure Key Vault ajuda a resolver os problemas a seguir:

• Gerenciamento de certificados (esta biblioteca) – criar, gerenciar e implantar certificados SSL/TLS públicos e privados
• Gerenciamento de chaves criptográficas (azure-keyvault-keys) – criar, armazenar e controlar o acesso às chaves usadas para criptografar seus dados
• Gerenciamento de segredos (azure-keyvault-secrets) – armazenar e controlar com segurança o acesso a tokens, senhas, certificados, chaves de API e outros segredos
• Administração do cofre (azure-keyvault-administration) – RBAC (controle de acesso baseado em função) e opções de backup e restauração no nível do cofre

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

Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691. É necessário ter o Python 3.7 ou posterior para usar esse pacote. Para obter mais detalhes, consulte a política de suporte do SDK do Azure para Python.

Introdução

Instalar o pacote

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

pip install azure-keyvault-certificates azure-identity

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

Pré-requisitos

• Uma assinatura do Azure
• Python 3.7 ou posterior
• Um Key Vault existente do Azure. Se você precisar criar um, poderá fazer isso usando a CLI do Azure seguindo as etapas neste documento.

Autenticar o cliente

Para interagir com o serviço Key Vault do Azure, você precisará de uma instância de um CertificateClient, bem como uma URL do cofre e um objeto de credencial. Este documento demonstra o uso de um DefaultAzureCredential, que é apropriado para a maioria dos cenários, incluindo ambientes locais de desenvolvimento e produção. É recomendável usar uma identidade gerenciada para autenticação em ambientes de produção.

Consulte a documentação de identidade do azure para obter mais informações sobre outros métodos de autenticação e seus tipos de credencial correspondentes.

Criar um cliente

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

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

NOTA: Para um cliente assíncrono, importe azure.keyvault.certificates.aioem CertificateClient vez disso.

Principais conceitos

CertificateClient

Com um CertificateClient , você pode obter certificados do cofre, criar novos certificados e novas versões de certificados existentes, atualizar metadados de certificado e excluir certificados. Você também pode gerenciar emissores de certificado, contatos e políticas de gerenciamento de certificados. Isso é ilustrado nos exemplos abaixo.

Exemplos

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

• Criar um certificado
• Recuperar um certificado
• Atualizar propriedades de um certificado existente
• Excluir um certificado
• Listar propriedades de certificados
• Operações assíncronas
• Criar um certificado de forma assíncrona
• Listar as propriedades de certificados de forma assíncrona

Criar um certificado

begin_create_certificate cria um certificado a ser armazenado no Key Vault do Azure. Se um certificado com o mesmo nome já existir, uma nova versão do certificado será criada. Antes de criar um certificado, uma política de gerenciamento para o certificado pode ser criada ou nossa política padrão será usada. Esse método retorna um sondador 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 você quiser verificar o status da criação do certificado, poderá chamar status() o sondador ou get_certificate_operation com o nome do certificado.

Recuperar um certificado

get_certificate recupera 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 recupera 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)

Excluir um certificado

begin_delete_certificate solicita Key Vault excluir um certificado, retornando um sondador que permite aguardar a conclusão da exclusão. A espera é útil quando o cofre tem a exclusão temporária habilitada e você deseja limpar (excluir permanentemente) o certificado assim que possível. Quando a exclusão reversível é desabilitada, begin_delete_certificate ela é 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 no Key Vault especificado.

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

Essa biblioteca inclui um conjunto completo de APIs assíncronas. Para usá-los, primeiro você deve instalar um transporte assíncrono, como aiohttp. Confira a documentação do azure-core para obter mais informações.

Clientes e credenciais assíncronos devem ser fechados quando não forem mais necessários. Esses objetos são gerenciadores de contexto assíncronos e definem métodos assíncronos 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 ser armazenado no Key Vault do Azure. Se um certificado com o mesmo nome já existir, uma nova versão do certificado será criada. Antes de criar um certificado, uma política de gerenciamento para o certificado pode ser criada ou nossa política padrão será usada. Aguardar create_certificate retornará o certificado criado se a criação for bem-sucedida e uma 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 as propriedades de certificados de forma assíncrona

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)

Solução de problemas

Consulte o azure-keyvault-certificatesguia de soluçã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 você tentar obter uma chave que não existe no cofre, CertificateClient aciona 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)

Registro em log

Essa biblioteca usa a biblioteca de log padrão para registro em log. Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível INFO.

O log detalhado do nível DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um 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 log de rastreamento de rede também pode ser habilitado para qualquer operação única:

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

Próximas etapas

Vários exemplos estão disponíveis no repositório gitHub do SDK do Azure para Python. Esses exemplos fornecem código de exemplo para cenários de Key Vault adicionais: | Arquivo | Descrição | |-------------|-------------| | hello_world.py (versão assíncrona) | criar/obter/atualizar/excluir certificados | | backup_restore_operations.py (versão assíncrona) | fazer backup e recuperar certificados | | import_certificate.py (versão assíncrona) | importar certificados formatados em PKCS nº 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 limpar certificados | | issuers.py (versão assíncrona) | gerenciar emissores de certificado | | contacts.py (versão assíncrona) | gerenciar contatos de certificado | | parse_certificate.py (versão assíncrona) | extrair a chave privada de um certificado |

Documentação adicional

Para obter uma documentação mais abrangente sobre Key Vault do Azure, consulte a documentação de referência da API.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o código de conduta ou entre em contato com opencode@microsoft.com para enviar outras perguntas ou comentários.