Autenticar aplicativos Python para serviços do Azure durante o desenvolvimento local usando entidades de serviço

2025-06-02

Ao criar aplicativos de nuvem, os desenvolvedores geralmente precisam executar e testar seus aplicativos localmente. Mesmo durante o desenvolvimento local, o aplicativo deve se autenticar em todos os serviços do Azure com os quais interage. Este artigo explica como configurar identidades de entidades de serviço dedicadas especificamente para uso durante o desenvolvimento local.

Um diagrama que mostra como um aplicativo em execução no desenvolvedor local obtém a entidade de serviço do aplicativo de um arquivo .env e, em seguida, usa essa identidade para se conectar aos recursos do Azure.

Entidades de serviço de aplicativo dedicadas para desenvolvimento local dão suporte ao princípio do privilégio mínimo limitando o acesso somente aos recursos do Azure exigidos pelo aplicativo durante o desenvolvimento. O uso de um principal de serviço de aplicativo dedicado reduz o risco de acesso indesejado a outros recursos e ajuda a evitar bugs relacionados a permissões durante a transição para o ambiente de produção, onde permissões mais amplas podem levar a problemas.

Ao registrar aplicativos para desenvolvimento local no Azure, é recomendável:

Crie registros de aplicativo separados para cada desenvolvedor: isso fornece a cada desenvolvedor sua própria entidade de serviço, evitando a necessidade de compartilhar credenciais e habilitando um controle de acesso mais granular.
Crie registros de aplicativo separados para cada aplicativo: isso garante que cada aplicativo tenha apenas as permissões necessárias, reduzindo a superfície de ataque potencial.

Para habilitar a autenticação durante o desenvolvimento local, defina variáveis de ambiente com as credenciais da entidade de serviço de aplicativo. O SDK do Azure para Python detecta essas variáveis e as usa para autenticar solicitações nos serviços do Azure.

1 – Registrar o aplicativo no Azure

Os objetos de principal de serviço de aplicativo são criados quando você registra um aplicativo no Azure. Esse registro pode ser executado usando o portal do Azure ou a CLI do Azure. O processo de registro cria um registro de aplicativo no Microsoft Entra ID (antigo Azure Active Directory) e gera um objeto de entidade de serviço para o aplicativo. O objeto do principal de serviço é usado para autenticar o aplicativo aos serviços do Azure. O processo de registro do aplicativo também gera um segredo do cliente (senha) para o aplicativo. Esse segredo é usado para autenticar o aplicativo nos serviços do Azure. O segredo do cliente nunca é armazenado no controle do código-fonte, mas sim em um .env arquivo no diretório do aplicativo. O .env arquivo é lido pelo aplicativo em runtime para definir variáveis de ambiente que o SDK do Azure para Python usa para autenticar o aplicativo. As etapas a seguir mostram como registrar um aplicativo no Azure e criar uma entidade de serviço para o aplicativo. As etapas são mostradas para a CLI do Azure e o portal do Azure.

CLI do Azure
Portal do Azure

É possível executar os comandos da CLI do Azure no Azure Cloud Shell ou em uma estação de trabalho com a CLI do Azure instalada.

Primeiro, use o comando az ad sp create-for-rbac para criar uma nova entidade de serviço para o aplicativo. O comando também cria o registro do aplicativo para o aplicativo ao mesmo tempo.

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

A saída desse comando é semelhante à seguinte. Anote esses valores ou mantenha essa janela aberta, já que você precisará desses valores nas próximas etapas e não poderá exibir o valor da senha (segredo do cliente) novamente. No entanto, você pode adicionar uma nova senha mais tarde, sem invalidar a entidade de serviço ou as senhas existentes, se necessário.

{
  "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "displayName": "<service-principal-name>",
  "password": "Ee5Ff~6Gg7.-Hh8Ii9Jj0Kk1Ll2Mm3_Nn4Oo5Pp6",
  "tenant": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}

Em seguida, você precisa obter o appID valor e armazená-lo em uma variável. Esse valor é usado para definir variáveis de ambiente em seu ambiente de desenvolvimento local para que o SDK do Azure para Python possa se autenticar no Azure usando a entidade de serviço.

APP_ID=$(az ad sp list \
  --all \
  --query "[?displayName=='$SERVICE_PRINCIPAL_NAME'].appId | [0]" \
  --output tsv)

Entre no portal do Azure e siga estas etapas.

Instruções	Captura de tela
No portal do Azure: Insira registros de aplicativos na caixa de pesquisa na parte superior do portal do Azure. Selecione o item rotulado Registros de aplicativo sob o título Serviços no menu que aparece abaixo da barra de pesquisa.
Na página Registros de aplicativo, selecione + Novo registro.
Na página Registrar um aplicativo, preencha o formulário conforme segue. Nome → Insira um nome para o registro de aplicativo no Azure. É recomendável que esse nome inclua o nome do aplicativo, o usuário para o qual o registro do aplicativo é e um identificador como 'dev' para indicar que esse registro de aplicativo é para uso no desenvolvimento local. Tipos de conta compatíveis → Contas somente neste diretório organizacional. Selecione Registrar para registrar seu aplicativo e criar a entidade de serviço de aplicativo.
Na página Registro de aplicativo do seu aplicativo: ID do aplicativo (cliente) → Esse é o ID de aplicativo que o aplicativo usará para acessar o Azure durante o desenvolvimento local. Copie esse valor para um local temporário em um editor de texto, pois você precisará dele em uma etapa futura. ID de diretório (locatário) → Esse valor também será necessário para seu aplicativo quando ele for autenticado no Azure. Copie esse valor para um local temporário em um editor de texto, pois ele será necessário em uma etapa futura. Credenciais do cliente → Você deve definir as credenciais do cliente para o aplicativo antes que seu aplicativo possa se autenticar no Azure e usar os serviços do Azure. Selecione Adicionar um certificado ou segredo para adicionar credenciais ao seu aplicativo.
Na página Certificados e segredos, selecione + Novo segredo do cliente.
A caixa de diálogo Adicionar um segredo de cliente será exibida do lado direito da página. Nesta caixa de diálogo: Descrição → Inserir um valor de Atual. Expira → Selecione um valor de 24 meses. Selecione Adicionar para adicionar o segredo.
Na página Certificados e segredos, será mostrado o valor do segredo do cliente. Copie esse valor para um local temporário em um editor de texto, pois você precisará dele em uma etapa futura. IMPORTANTE: esta é a única vez que você verá esse valor. Depois de sair ou atualizar esta página, você não poderá ver esse valor novamente. Você pode adicionar mais segredos de cliente sem invalidar o segredo anterior, mas não verá esse valor novamente.

2 – Criar um grupo de segurança do Microsoft Entra para desenvolvimento local

Como normalmente há vários desenvolvedores que trabalham em um aplicativo, é recomendável criar um grupo de segurança do Microsoft Entra para encapsular as funções (permissões) que o aplicativo precisa no desenvolvimento local, em vez de atribuir as funções a objetos de entidade de serviço individuais. As vantagens oferecidas são:

Cada desenvolvedor deve ter as mesmas funções atribuídas, já que as funções são atribuídas no nível do grupo.
Se uma nova função for necessária para o aplicativo, ela só precisará ser adicionada ao grupo do Microsoft Entra para o aplicativo.
Se um novo desenvolvedor ingressar na equipe, um novo principal de serviço de aplicativo será criado para o desenvolvedor e adicionado ao grupo, garantindo que o desenvolvedor tenha as permissões corretas para trabalhar no aplicativo.

CLI do Azure
Portal do Azure

O comando az ad group create é usado para criar grupos de segurança no ID do Microsoft Entra. Os parâmetros --display-name e --main-nickname são obrigatórios. O nome fornecido ao grupo deve ter como base o nome do aplicativo. Também é interessante incluir uma frase como “desenvolvimento local” no nome do grupo para indicar a finalidade do grupo.

GROUP_DISPLAY_NAME="<group-name>"
GROUP_MAIL_NICKNAME="<group-mail-nickname>"
GROUP_DESCRIPTION="<group-description>"
az ad group create \
  --display-name $GROUP_DISPLAY_NAME \
  --mail-nickname $GROUP_MAIL_NICKNAME \
  --description $GROUP_DESCRIPTION

Para adicionar membros ao grupo, você precisará da ID do objeto da entidade de serviço do aplicativo, que é diferente da ID do aplicativo. Use az ad sp list para listar as entidades de serviço disponíveis. O comando de parâmetro --filter aceita filtros de estilo OData e pode ser usado para filtrar a lista, conforme mostrado. O parâmetro --query limita as colunas somente às de interesse.

SP_OBJECT_ID=$(az ad sp list \
  --filter "startswith(displayName,'$GROUP_DISPLAY_NAME')" \
  --query "[0].id" \
  --output tsv)

O comando az ad group member add pode ser usado para adicionar membros a grupos.

az ad group member add \
    --group $GROUP_DISPLAY_NAME \
    --member-id $SP_OBJECT_ID

Instruções	Captura de tela
Navegue até a página ID do Microsoft Entra no portal do Azure digitando ID do Microsoft Entra na caixa de pesquisa na parte superior da página e selecionando ID do Microsoft Entra em serviços.
Na página Microsoft Entra ID, selecione Grupos no menu à esquerda.
Na página Todos os grupos, selecione Novo grupo.
Na página Novo grupo: Tipo de grupo → Segurança Nome do grupo → Um nome para o grupo de segurança, normalmente criado com base no nome do aplicativo. Também é interessante incluir uma cadeia de caracteres como desenvolvimento local no nome do grupo para indicar a finalidade do grupo. Descrição do grupo → Uma descrição da finalidade do grupo. Selecione o link Nenhum membro selecionado em Membros para adicionar membros ao grupo.
Na caixa de diálogo Adicionar membros: Use a caixa de pesquisa para filtrar a lista de nomes principais na lista. Selecione as entidades de serviço de aplicativo para desenvolvimento local para este aplicativo. Conforme os objetos são selecionados, eles ficarão esmaecidos e serão movidos para a lista Itens selecionados na parte inferior da caixa de diálogo. Depois de concluir, escolha o botão Selecionar.
De volta à página Novo grupo, selecione Criar para criar o grupo. O grupo será criado e você retorna para a página Todos os grupos. Pode levar até 30 segundos para que o grupo apareça e talvez seja necessário atualizar a página devido ao cache no portal do Azure.

Observação

Por padrão, a criação de grupos de segurança do Microsoft Entra é limitada a determinadas funções com privilégio em um diretório. Se não for possível criar um grupo, entre em contato com um administrador do seu diretório. Se você não puder adicionar membros a um grupo existente, entre em contato com o proprietário do grupo ou com um administrador de diretório. Para saber mais, consulte Gerenciar grupos do Microsoft Entra e associação de grupo.

3 – Atribuir funções ao aplicativo

Em seguida, você precisa determinar as funções (permissões) de que seu aplicativo precisa em quais recursos e atribuir essas funções ao seu aplicativo. Neste exemplo, as funções são atribuídas ao grupo do Microsoft Entra criado na etapa 2. As funções podem ser atribuídas a um recurso, grupo de recursos ou escopo de assinatura. Este exemplo mostra como atribuir funções no escopo do grupo de recursos, uma vez que a maioria dos aplicativos agrupa todos os seus recursos do Azure em um único grupo de recursos.

CLI do Azure
Portal do Azure

Um usuário, grupo ou entidade de serviço de aplicativo recebe uma função no Azure usando o comando az role assignment create. Você pode especificar um grupo com o ID de objeto. Você pode especificar uma entidade de serviço de aplicativo com seu appId.

RESOURCE_GROUP_NAME=<resource-group-name>
SUBSCRIPTION_ID=$(az account show --query id --output tsv)
ROLE_NAME=<role-name>
az role assignment create \
  --assignee "$APP_ID" \
  --scope "./subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP_NAME" \
  --role "$ROLE_NAME"

![!OBSERVAÇÃO] Para impedir que o Git Bash trate /subscriptions/... como um caminho de arquivo, adicione no início ./ à string do parâmetro scope e use aspas duplas em toda a string.

Para obter os nomes de função que podem ser atribuídos, use o comando az role definition list.

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

Por exemplo, para permitir que a entidade de serviço do aplicativo com o appId de 00001111-aaaa-2222-bbbb-3333cccc4444 tenha acesso de leitura, gravação e exclusão aos contêineres de blob do Azure Storage e aos dados em todas as contas de armazenamento no grupo de recursos msdocs-python-sdk-auth-example na assinatura com ID aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e, você deve atribuir a entidade de serviço do aplicativo à função de Colaborador de Dados de Blob de Armazenamento usando o seguinte comando.

az role assignment create --assignee 00001111-aaaa-2222-bbbb-3333cccc4444 \
    --scope "./subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-python-sdk-auth-example" \
    --role "Storage Blob Data Contributor"

Para obter informações sobre como atribuir permissões no nível de recurso ou assinatura usando a CLI do Azure, consulte o artigo Atribuir funções do Azure usando a CLI do Azure.

Instruções	Captura de tela
Localize o grupo de recursos do aplicativo pesquisando pelo nome do grupo de recursos e usando a caixa de pesquisa na parte superior do portal do Azure. Navegue até o grupo de recursos selecionando o nome do grupo de recursos no título Grupos de recursos na caixa de diálogo.
Na página do grupo de recursos, selecione Controle de acesso (IAM) no menu à esquerda.
Na página Controle de acesso (IAM): Selecione a guia Atribuições de função. Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu suspenso resultante.
A página Adicionar atribuição de função lista todas as funções que podem ser atribuídas ao grupo de recursos. Use a caixa de pesquisa para filtrar a lista para obter um tamanho mais gerenciável. Este exemplo mostra como filtrar as funções do Blob de Armazenamento. Selecione a função que você deseja atribuir. Selecione Avançar para ir para a próxima tela.
A próxima página Adicionar atribuição de função permite especificar a qual usuário atribuir a função. Selecione Usuário, grupo ou entidade de serviço em Atribuir acesso a. Selecionar + Selecionar membros em Membros Uma caixa de diálogo é aberta no lado direito do portal do Azure.
Na caixa de diálogo Selecionar membros: A caixa de texto Selecionar pode ser usada para filtrar a lista de usuários e grupos em sua assinatura. Se necessário, digite os primeiros caracteres do grupo de desenvolvimento local do Microsoft Entra que você criou para o aplicativo. Selecione o grupo de desenvolvimento local do Microsoft Entra associado ao seu aplicativo. Para continuar, selecione Selecionar na parte inferior da caixa de diálogo.
O grupo Microsoft Entra é exibido como selecionado na tela Adicionar atribuição da função. Selecione Revisar + atribuir para ir para a página final e, em seguida, Revisar + atribuir novamente para concluir o processo.

4 - Definir variáveis de ambiente de desenvolvimento local

O objeto DefaultAzureCredential procurará as informações da entidade de serviço em um conjunto de variáveis de ambiente no runtime. Como a maioria dos desenvolvedores trabalha em vários aplicativos, é recomendável usar um pacote como python-dotenv para acessar o ambiente a partir de um arquivo .env armazenado no diretório do aplicativo durante o desenvolvimento. Isso define o escopo das variáveis de ambiente usadas para autenticar o aplicativo no Azure, de modo que elas só possam ser usadas por esse aplicativo.

O arquivo .env nunca é verificado no controle do código-fonte, pois contém a chave secreta do aplicativo para o Azure. O arquivo .gitignore padrão para Python exclui automaticamente o arquivo .env do check-in.

Para usar o pacote python-dotenv, primeiro instale o pacote em seu aplicativo.

pip install python-dotenv

Em seguida, crie um arquivo .env no diretório raiz do aplicativo. Defina os valores da variável de ambiente com os valores obtidos do processo de registro do aplicativo da seguinte maneira:

AZURE_CLIENT_ID → O valor da ID do aplicativo.
AZURE_TENANT_ID → O valor da ID do locatário.
AZURE_CLIENT_SECRET → A senha/credencial gerada para o aplicativo.

AZURE_CLIENT_ID=00001111-aaaa-2222-bbbb-3333cccc4444
AZURE_TENANT_ID=aaaabbbb-0000-cccc-1111-dddd2222eeee
AZURE_CLIENT_SECRET=Ee5Ff~6Gg7.-Hh8Ii9Jj0Kk1Ll2Mm3_Nn4Oo5Pp6

Por fim, no código de inicialização do aplicativo, use a biblioteca python-dotenv para ler as variáveis de ambiente do arquivo .env na inicialização.

from dotenv import load_dotenv

if ( os.environ['ENVIRONMENT'] == 'development'):
    print("Loading environment variables from .env file")
    load_dotenv(".env")

5 – Implementar DefaultAzureCredential no seu aplicativo

Para autenticar objetos clientes do SDK do Azure no Azure, seu aplicativo deve usar a classe DefaultAzureCredential do pacote azure.identity. Nesse cenário, DefaultAzureCredential detectará as variáveis de ambiente AZURE_CLIENT_ID, AZURE_TENANT_ID e AZURE_CLIENT_SECRET será definido e lerá essas variáveis para obter as informações da entidade de serviço do aplicativo com as quais se conectar ao Azure.

Comece adicionando o pacote azure.identity ao seu aplicativo.

pip install azure-identity

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

Importar a classe DefaultAzureCredential do módulo azure.identity.
Crie um objeto DefaultAzureCredential.
Passar o objeto DefaultAzureCredential para o construtor do objeto do cliente do SDK do Azure.

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

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

# Acquire a credential object
token_credential = DefaultAzureCredential()

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