Autenticar para Azure recursos de aplicativos Python hospedados localmente

Os aplicativos hospedados fora do Azure, como em um ambiente local ou em um data center de terceiros, devem usar uma entidade de serviço de aplicativo por meio de Microsoft Entra ID para autenticar nos serviços do Azure. Nas seções a seguir, você aprenderá:

Como registrar um aplicativo no Microsoft Entra para criar um principal de serviço
Como atribuir as funções às permissões de escopo
Como autenticar-se usando uma entidade de serviço direto do código do seu aplicativo

O uso de entidades de serviço de aplicativo dedicadas permite que você aderir ao princípio de privilégio mínimo ao acessar recursos do Azure. As permissões são limitadas aos requisitos específicos do aplicativo durante o desenvolvimento, impedindo o acesso acidental a recursos Azure destinados a outros aplicativos ou serviços. Essa abordagem também ajuda a evitar problemas quando o aplicativo é movido para produção, garantindo que ele não seja super privilegiado no ambiente de desenvolvimento.

Um registro de aplicativo diferente deve ser criado para cada ambiente em que o aplicativo está hospedado. Isso permite que permissões de recurso específicas do ambiente sejam configuradas para cada principal de serviço e garantir que um aplicativo implantado em um ambiente não interaja com recursos do Azure que fazem parte de outro ambiente.

Registrar o aplicativo no Azure

Os objetos do service principal do aplicativo são criados por meio de um registro no Azure usando o portal do Azure ou o Azure CLI.

Azure portal
Azure CLI

No portal Azure, use a barra de pesquisa para navegar até a página App registrations.
Na página App registrations, selecione + Novo registro.
Na página Registrar um aplicativo:
- Para o campo Nome, insira um valor descritivo que inclui o nome do aplicativo e o ambiente de destino.
- Para os Tipos de conta com suporte, selecione Contas somente neste diretório organizacional (somente cliente da Microsoft – Locatário único) ou qualquer opção que melhor atenda às suas necessidades.
Selecione Registrar para registrar seu aplicativo e criar a entidade de serviço.

Uma captura de tela mostrando como criar um registro de aplicativo no portal do Azure.
Na página Registro do aplicativo , copie a ID do aplicativo (cliente) e a ID do diretório (locatário) e cole-as em um local temporário para uso posterior nas configurações do código do aplicativo.
Selecione Adicionar um certificado ou um secreto para configurar credenciais para seu aplicativo.
Na página Certificados e segredos, selecione + Novo segredo do cliente.
No painel de submenu Adicionar um segredo do cliente que se abre:
- Para a Descrição, insira um valor para Atual.
- Para o valor de expiração , deixe o valor padrão recomendado de 180 dias.
- Selecione Adicionar para adicionar o segredo.
Na página Certificados e segredos, copie a propriedade Value do segredo do cliente para uso em uma etapa futura.

Observação

O valor do segredo do cliente só é exibido uma vez depois que o registro do aplicativo é criado. Você pode adicionar mais segredos do cliente sem invalidar esse segredo do cliente, mas não há como exibir esse valor novamente.

Azure CLI comandos podem ser executados no Azure Cloud Shell ou em uma estação de trabalho com o Azure CLI instalado.

Use o comando az ad sp create-for-rbac para criar um registro de aplicativos e a entidade de serviço do aplicativo.

az ad sp create-for-rbac --name <service-principal-name>

A saída desse comando é semelhante ao seguinte JSON:

{
  "appId": "00000000-0000-0000-0000-000000000000",
  "displayName": "<service-principal-name>",
  "password": "abcdefghijklmnopqrstuvwxyz",
  "tenant": "11111111-1111-1111-1111-111111111111"
}

Copie essa saída em um arquivo temporário em um editor de texto, pois você precisará desses valores em uma etapa futura.

Observação

O valor do segredo do cliente só é exibido uma vez depois que o registro do aplicativo é criado. Você pode adicionar mais segredos do cliente sem invalidar esse segredo do cliente, mas não há como exibir esse valor novamente.

Atribuir funções ao principal de serviço do aplicativo

Em seguida, determine quais funções (permissões) seu aplicativo precisa em quais recursos e atribua essas funções à entidade de serviço que você criou. As funções podem ser atribuídas no escopo de um recurso, de um grupo de recursos ou de uma assinatura. Este exemplo mostra como atribuir funções no escopo do grupo de recursos, já que a maioria dos aplicativos agrupa todos os seus recursos Azure em um único grupo de recursos.

Azure portal
Azure CLI

No portal Azure, navegue até a página Overview do grupo de recursos que contém seu aplicativo.
Selecione Controle de acesso (IAM) na navegação à esquerda.
Na página controle de acesso (IAM), selecione + Adicionar e escolha Adicionar atribuição de função no menu suspenso. A página Adicionar atribuição de função fornece várias guias para configurar e atribuir funções.
Na guia Função , use a caixa de pesquisa para localizar a função que você deseja atribuir. Selecione a função e escolha Avançar.
Na guia Membros :
- Para atribuir acesso ao valor, selecione Usuário, grupo ou entidade de serviço .
- Para o valor Membros, escolha + Selecionar membros para abrir o painel de seleção Selecionar membros.
- Pesquise a entidade de serviço que você criou anteriormente e selecione-a nos resultados filtrados. Escolha Selecionar para escolher o grupo e fechar o painel de menu.
- Selecione Examinar + atribuir na parte inferior da guia Membros .
Na guia Revisão + atribuição , selecione Examinar + atribuir na parte inferior da página.

Use o comando az role definition list para obter os nomes das funções às quais uma entidade de serviço pode ser atribuída:

az role definition list \
    --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
    --output table

Use o comando az role assignment create para atribuir uma função a um principal do serviço de aplicativo.
```
az role assignment create \
    --assignee "<app-Id>" \
    --role "<role-name>" \
    --resource-group "<resource-group-name>"
```
Para obter informações sobre como atribuir permissões no nível do recurso ou da assinatura usando o Azure CLI, consulte atribuir funções do Azure usando o Azure CLI.

Definir as variáveis de ambiente do aplicativo

Durante a execução, determinadas credenciais da biblioteca Azure Identity, como DefaultAzureCredential, EnvironmentCredential e ClientSecretCredential, pesquisam informações do principal de serviço por convenção nas variáveis de ambiente. Há várias maneiras de configurar variáveis de ambiente ao trabalhar com Python, dependendo de suas ferramentas e ambiente.

Independentemente da abordagem escolhida, configure as seguintes variáveis de ambiente para uma entidade de serviço:

AZURE_CLIENT_ID: usado para identificar o aplicativo registrado no Azure.
AZURE_TENANT_ID: O ID do locatário do Microsoft Entra.
AZURE_CLIENT_SECRET: a credencial secreta que foi gerada para o aplicativo.

Em Visual Studio Code, as variáveis de ambiente podem ser definidas no arquivo launch.json localizado na pasta .vscode do projeto. Esses valores são extraídos automaticamente quando o aplicativo é iniciado. No entanto, essas configurações não viajam com seu aplicativo durante a implantação, portanto, você precisa configurar variáveis de ambiente em seu ambiente de hospedagem de destino.

{
    "configurations": [
        {
            "env": {
                "AZURE_CLIENT_ID": "<your-client-id>",
                "AZURE_TENANT_ID": "<your-tenant-id>",
                "AZURE_CLIENT_SECRET": "<your-client-secret>"
            }
        }
    ]
}

Na linha de comando Windows, você pode definir variáveis de ambiente no nível do usuário usando os seguintes comandos:

setx AZURE_CLIENT_ID "<your-client-id>"
setx AZURE_TENANT_ID "<your-tenant-id>"
setx AZURE_CLIENT_SECRET "<your-client-secret>"

As variáveis de ambiente no nível do sistema também poderão ser definidas se você executar o prompt de comando como administrador e adicionar o /m sinalizador:

setx AZURE_CLIENT_ID "<your-client-id>" /m
setx AZURE_TENANT_ID "<your-tenant-id>" /m
setx AZURE_CLIENT_SECRET "<your-client-secret>" /m

O PowerShell também pode ser usado para definir variáveis de ambiente no nível do usuário ou do sistema:

Use os seguintes comandos para definir as variáveis de ambiente no nível do usuário usando o PowerShell:

[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "<your-client-id>", "User")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "<your-tenant-id>", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "<your-client-secret>", "User")

As variáveis de ambiente no nível do sistema também poderão ser definidas usando o PowerShell se você abri-lo com a opção "Executar como Administrador":

[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "<your-client-id>", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "<your-tenant-id>", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "<your-client-secret>", "Machine")

Ao usar Gunicorn para executar Python aplicativos Web em um ambiente de servidor UNIX, variáveis de ambiente para um aplicativo podem ser especificadas usando a diretiva EnvironmentFile no arquivo gunicorn.service, conforme mostrado abaixo:

[Unit]
Description=gunicorn daemon
After=network.target

[Service]
User=www-user
Group=www-data
WorkingDirectory=/path/to/python-app
EnvironmentFile=/path/to/python-app/py-env/app-environment-variables
ExecStart=/path/to/python-app/py-env/bin/gunicorn --config config.py wsgi:app

[Install]
WantedBy=multi-user.target

O arquivo especificado na EnvironmentFile diretiva deve conter uma lista de variáveis de ambiente com seus valores, conforme mostrado abaixo:

AZURE_CLIENT_ID=<your-client-id>
AZURE_TENANT_ID=<your-tenant-id>
AZURE_CLIENT_SECRET=<your-client-secret>

Autenticar nos serviços do Azure a partir do seu aplicativo

A biblioteca azure-identity fornece várias credenciais—implementações de TokenCredential adaptadas para dar suporte a diferentes cenários e fluxos de autenticação do Microsoft Entra. As etapas a seguir demonstram como usar ClientSecretCredential ao trabalhar com entidades de serviço localmente e em produção.

Implementar o código

Comece adicionando o pacote ao seu aplicativo.

pip install azure-identity

Em seguida, para qualquer código Python que crie um objeto cliente Azure SDK em seu aplicativo, você deve:

Importar a classe ClientSecretCredential do módulo azure.identity.
Importe o os módulo para ler variáveis de ambiente.
Leia as variáveis de ambiente para obter a ID do cliente, a ID do locatário e o segredo do cliente.
Crie um ClientSecretCredential objeto passando a ID do locatário, a ID do cliente e o segredo do cliente.
Passe o objeto ClientSecretCredential para o construtor do objeto cliente Azure SDK.

Um exemplo dessa abordagem é mostrado no segmento de código a seguir.

import os
from azure.identity import ClientSecretCredential
from azure.storage.blob import BlobServiceClient

tenant_id = os.environ.get("AZURE_TENANT_ID")
client_id = os.environ.get("AZURE_CLIENT_ID")
client_secret = os.environ.get("AZURE_CLIENT_SECRET")

credential = ClientSecretCredential(tenant_id, client_id, client_secret)

blob_service_client = BlobServiceClient(
    account_url="https://<my_account_name>.blob.core.windows.net",
    credential=credential)

Comentários

Esta página foi útil?

Last updated on 2026-03-11