Quickstart: Azure Key Vault certificate client library for PythonQuickstart: Azure Key Vault certificate client library for Python

Começa com a biblioteca de clientes do Azure Key Vault para python.Get started with the Azure Key Vault certificate client library for Python. Siga os passos abaixo para instalar a embalagem e experimente o código de exemplo para tarefas básicas.Follow the steps below to install the package and try out example code for basic tasks. Ao utilizar o Key Vault para armazenar certificados, evita armazenar certificados no seu código, o que aumenta a segurança da sua aplicação.By using Key Vault to store certificates, you avoid storing certificates in your code, which increases the security of your app.

Documentação de | referência da API Código fonte da biblioteca | Pacote (Índice de Pacote Python)API reference documentation | Library source code | Package (Python Package Index)

Pré-requisitosPrerequisites

Este quickstart pressupõe que está a executar o Azure CLI numa janela do terminal Linux.This quickstart assumes you are running Azure CLI in a Linux terminal window.

Configurar o ambiente localSet up your local environment

Este quickstart está a utilizar a biblioteca Azure Identity com o Azure CLI para autenticar o utilizador nos Serviços Azure.This quickstart is using Azure Identity library with Azure CLI to authenticate user to Azure Services. Os desenvolvedores também podem usar Visual Studio ou Visual Studio Code para autenticar as suas chamadas, para mais informações, ver Autenticar o cliente com a biblioteca de clientes da Azure IdentityDevelopers can also use Visual Studio or Visual Studio Code to authenticate their calls, for more information, see Authenticate the client with Azure Identity client library

Iniciar sessão no AzureSign in to Azure

  1. Execute o comando login.Run the login command.

    az login
    

    Se o CLI conseguir abrir o seu navegador predefinido, fá-lo-á e carregará uma página de inscrição do Azure.If the CLI can open your default browser, it will do so and load an Azure sign-in page.

    Caso contrário, abra uma página do navegador https://aka.ms/devicelogin e introduza o código de autorização exibido no seu terminal.Otherwise, open a browser page at https://aka.ms/devicelogin and enter the authorization code displayed in your terminal.

  2. Inicie sessão com as credenciais da sua conta no browser.Sign in with your account credentials in the browser.

Instalar as embalagensInstall the packages

  1. Num terminal ou pedido de comando, crie uma pasta de projeto adequada e, em seguida, crie e ative um ambiente virtual Python como descrito em ambientes virtuais Use PythonIn a terminal or command prompt, create a suitable project folder, and then create and activate a Python virtual environment as described on Use Python virtual environments

  2. Instalar a biblioteca de identidade do Diretório Ativo Azure:Install the Azure Active Directory identity library:

    pip install azure.identity
    
  3. Instale a biblioteca do cliente do certificado Key Vault:Install the Key Vault certificate client library:

    pip install azure-keyvault-certificates
    

Criar um grupo de recursos e cofre chaveCreate a resource group and key vault

  1. Utilize o az group create comando para criar um grupo de recursos:Use the az group create command to create a resource group:

    az group create --name KeyVault-PythonQS-rg --location eastus
    

    Pode mudar o "Eastus" para um local mais próximo de si, se preferir.You can change "eastus" to a location nearer to you, if you prefer.

  2. Utilize az keyvault create para criar o cofre da chave:Use az keyvault create to create the key vault:

    az keyvault create --name <your-unique-keyvault-name> --resource-group KeyVault-PythonQS-rg
    

    Substitua <your-unique-keyvault-name> por um nome único em todo o Azure.Replace <your-unique-keyvault-name> with a name that's unique across all of Azure. Normalmente, usa o seu nome pessoal ou da empresa juntamente com outros números e identificadores.You typically use your personal or company name along with other numbers and identifiers.

  3. Crie uma variável ambiental que forneça o nome do Cofre chave ao código:Create an environment variable that supplies the name of the Key Vault to the code:

    set KEY_VAULT_NAME=<your-unique-keyvault-name>
    

Conceder acesso ao seu cofre chaveGrant access to your key vault

Crie uma política de acesso para o cofre-chave que concede permissão de certificado à sua conta de utilizadorCreate an access policy for your key vault that grants certificate permission to your user account

az keyvault set-policy --name <YourKeyVaultName> --upn user@domain.com --certificate-permissions delete get list create

Definir variáveis de ambienteSet environment variables

Esta aplicação está a usar o nome do cofre como uma variável ambiental chamada KEY_VAULT_NAME .This application is using key vault name as an environment variable called KEY_VAULT_NAME.

WindowsWindows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShellWindows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS ou LinuxmacOS or Linux

export KEY_VAULT_NAME=<your-key-vault-name>

Criar o código de amostraCreate the sample code

A biblioteca de clientes do Azure Key Vault para Python permite-lhe gerir certificados.The Azure Key Vault certificate client library for Python allows you to manage certificates. A seguinte amostra de código demonstra como criar um cliente, definir um certificado, recuperar um certificado e apagar um certificado.The following code sample demonstrates how to create a client, set a certificate, retrieve a certificate, and delete a certificate.

Crie um ficheiro chamado kv_certificates.py que contenha este código.Create a file named kv_certificates.py that contains this code.

import os
from azure.keyvault.certificates import CertificateClient, CertificatePolicy,CertificateContentType, WellKnownIssuerNames 
from azure.identity import DefaultAzureCredential

keyVaultName = os.environ["KEY_VAULT_NAME"]
KVUri = "https://" + keyVaultName + ".vault.azure.net"

credential = DefaultAzureCredential()
client = CertificateClient(vault_url=KVUri, credential=credential)

certificateName = input("Input a name for your certificate > ")

print(f"Creating a certificate in {keyVaultName} called '{certificateName}' ...")

policy = CertificatePolicy.get_default()
poller = client.begin_create_certificate(certificate_name=certificateName, policy=policy)
certificate = poller.result()

print(" done.")

print(f"Retrieving your certificate from {keyVaultName}.")

retrieved_certificate = client.get_certificate(certificateName)

print(f"Certificate with name '{retrieved_certificate.name}' was found'.")
print(f"Deleting your certificate from {keyVaultName} ...")

poller = client.begin_delete_certificate(certificateName)
deleted_certificate = poller.result()

print(" done.")

Executar o códigoRun the code

Certifique-se de que o código na secção anterior está num ficheiro denominado kv_certificates.py.Make sure the code in the previous section is in a file named kv_certificates.py. Em seguida, executar o código com o seguinte comando:Then run the code with the following command:

python kv_certificates.py
  • Se encontrar permissões, certifique-se de que executou o az keyvault set-policy comando.If you encounter permissions errors, make sure you ran the az keyvault set-policy command.
  • A ree execução do código com o mesmo nome-chave pode produzir o erro, "(Conflict) Certificate encontra-se atualmente num estado eliminado, mas recuperável."Re-running the code with the same key name may produce the error, "(Conflict) Certificate is currently in a deleted but recoverable state." Use um nome chave diferente.Use a different key name.

Detalhes do códigoCode details

Autenticar e criar um clienteAuthenticate and create a client

Neste arranque rápido, o utilizador com sessão é utilizado para autenticar o cofre de chaves, que é o método preferido para o desenvolvimento local.In this quickstart, logged in user is used to authenticate to key vault, which is preferred method for local development. Para aplicações implantadas no Azure, a identidade gerida deve ser atribuída ao Serviço de Aplicações ou Máquina Virtual, para obter mais informações, consulte a Visão Geral da Identidade Gerida.For applications deployed to Azure, managed identity should be assigned to App Service or Virtual Machine, for more information, see Managed Identity Overview.

Por exemplo, o nome do seu cofre-chave é expandido para o cofre uri chave, no formato "https:// <your-key-vault-name> .vault.azure.net".In below example, the name of your key vault is expanded to the key vault URI, in the format "https://<your-key-vault-name>.vault.azure.net". Este exemplo está a usar a classe 'DefaultAzureCredential()' que permite usar o mesmo código em diferentes ambientes com diferentes opções para fornecer identidade.This example is using 'DefaultAzureCredential()' class, which allows to use the same code across different environments with different options to provide identity. Para mais informações, consulte a Autenticação Credencial Azure Padrão.For more information, see Default Azure Credential Authentication.

credential = DefaultAzureCredential()
client = CertificateClient(vault_url=KVUri, credential=credential)

Guardar um certificadoSave a certificate

Uma vez obtido o objeto cliente para o cofre de chaves, pode criar um certificado utilizando o método begin_create_certificate:Once you've obtained the client object for the key vault, you can create a certificate using the begin_create_certificate method:

policy = CertificatePolicy.get_default()
poller = client.begin_create_certificate(certificate_name=certificateName, policy=policy)
certificate = poller.result()

Aqui, o certificado requer uma política obtida com o método CertificatePolicy.get_default.Here, the certificate requires a policy obtained with the CertificatePolicy.get_default method.

Chamar um begin_create_certificate método gera uma chamada assíncrona para a API AZURE REST para o cofre de chaves.Calling a begin_create_certificate method generates an asynchronous call to the Azure REST API for the key vault. A chamada assíncrona devolve um objeto poller.The asynchronous call returns a poller object. Para esperar pelo resultado da operação, ligue para o método do result poller.To wait for the result of the operation, call the poller's result method.

Ao lidar com o pedido, a Azure autentica a identidade do autor da chamada (o principal do serviço) utilizando o objeto de credencial que forneceu ao cliente.When handling the request, Azure authenticates the caller's identity (the service principal) using the credential object you provided to the client.

Recuperar um certificadoRetrieve a certificate

Para ler um certificado da Key Vault, utilize o método get_certificate:To read a certificate from Key Vault, use the get_certificate method:

retrieved_certificate = client.get_certificate(certificateName)

Pode também verificar se o certificado foi definido com o certificado de comando Azure CLI az keyvault.You can also verify that the certificate has been set with the Azure CLI command az keyvault certificate show.

Apagar um certificadoDelete a certificate

Para eliminar um certificado, utilize o método begin_delete_certificate:To delete a certificate, use the begin_delete_certificate method:

poller = client.begin_delete_certificate(certificateName)
deleted_certificate = poller.result()

O begin_delete_certificate método é assíncrona e devolve um objeto poller.The begin_delete_certificate method is asynchronous and returns a poller object. Chamar o método do poller result espera pela sua conclusão.Calling the poller's result method waits for its completion.

Pode verificar se o certificado é eliminado com o certificado de comando Azure CLI az keyvault.You can verify that the certificate is deleted with the Azure CLI command az keyvault certificate show.

Uma vez eliminado, um certificado permanece em estado de aussitado mas recuperável por um tempo.Once deleted, a certificate remains in a deleted but recoverable state for a time. Se voltar a executar o código, utilize um nome de certificado diferente.If you run the code again, use a different certificate name.

Limpar os recursosClean up resources

Se também quiser experimentar segredos e chaves,pode reutilizar o Key Vault criado neste artigo.If you want to also experiment with secrets and keys, you can reuse the Key Vault created in this article.

Caso contrário, quando terminar com os recursos criados neste artigo, utilize o seguinte comando para eliminar o grupo de recursos e todos os seus recursos contidos:Otherwise, when you're finished with the resources created in this article, use the following command to delete the resource group and all its contained resources:

az group delete --resource-group KeyVault-PythonQS-rg

Passos seguintesNext steps