Autenticar aplicações Python nos serviços do Azure durante o desenvolvimento local usando princípios de serviço

2025-06-02

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

Um diagrama mostrando como um aplicativo em execução no desenvolvedor local obtém a entidade de serviço de 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 de menor privilégio, limitando o acesso apenas aos recursos do Azure exigidos pelo aplicativo durante o desenvolvimento. O uso de uma entidade de serviço de aplicativo dedicada reduz o risco de acesso não intencional a outros recursos e ajuda a evitar bugs relacionados a permissões durante a transição para a produção, onde permissões mais amplas podem levar a problemas.

Ao registrar aplicativos para desenvolvimento local no Azure, é recomendado:

Crie registros de aplicativos separados para cada desenvolvedor: isso fornece a cada desenvolvedor sua própria entidade de serviço, evitando a necessidade de compartilhar credenciais e permitindo um controle de acesso mais granular.
Crie registros de aplicativos 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 do aplicativo. O SDK do Azure para Python deteta essas variáveis e as usa para autenticar solicitações para serviços do Azure.

1 - Registar a aplicação no Azure

Os objetos principais do 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 (anteriormente Azure Ative Directory) e gera um objeto principal de serviço para o aplicativo. O objeto principal de serviço é usado para autenticar o aplicativo nos 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 tempo de execução 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

Os comandos da CLI do Azure podem ser executados 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 um novo principal de serviço para o aplicativo. O comando também cria o registo da aplicação ao mesmo tempo.

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

A saída deste comando é semelhante à seguinte. Anote esses valores ou mantenha essa janela aberta, pois você precisará desses valores nas próximas etapas e não poderá visualizar 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)

Inicie sessão no portal do Azure e siga estas etapas.

Instruções	Captura de ecrã
No portal do Azure: Insira registros de aplicativos na barra de pesquisa na parte superior do portal do Azure. Selecione o item rotulado Registros de aplicativos sob o título Serviços no menu que aparece abaixo da barra de pesquisa.
Na página Registos da aplicação, selecione + Novo registo.
Na página Registar uma candidatura, preencha o formulário da seguinte forma. Nome → Insira um nome para o registro do aplicativo no Azure. Recomenda-se que esse nome inclua o nome do aplicativo, o usuário para o qual o registro do aplicativo é feito e um identificador como 'dev' para indicar que esse registro de aplicativo é para uso no desenvolvimento local. Tipos de conta suportados → Contas apenas neste diretório organizacional. Selecione Registrar para registrar seu aplicativo e criar a entidade de serviço do aplicativo.
Na página de Registo de Aplicação para a sua aplicação: ID do aplicativo (cliente) → Esta é a ID do 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 do diretório (locatário) → Esse valor também será necessário para seu aplicativo quando ele se autenticar no Azure. Copie esse valor para um local temporário em um editor de texto, ele também 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 & segredos, selecione + Novo segredo do cliente.
A caixa de diálogo Adicionar um segredo do cliente aparecerá no lado direito da página. Nesta caixa de diálogo: Descrição → Insira um valor de Atual. Expira → Selecione um valor de 24 meses. Selecione Adicionar para adicionar o segredo.
Na página Certificados & segredos, você verá 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 esse segredo de cliente, mas não verá esse valor novamente.

2 - Criar um grupo de segurança 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) de que o aplicativo precisa no desenvolvimento local, em vez de atribuir as funções a objetos de entidade de serviço individuais. Isto oferece as seguintes vantagens:

Todos os desenvolvedores têm a garantia de ter as mesmas funções atribuídas, uma vez 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 Microsoft Entra para o aplicativo.
Se um novo programador se juntar à equipa, um novo principal de serviço de aplicação é criado para o programador e adicionado ao grupo, assegurando que o programador tenha as permissões adequadas para trabalhar na aplicação.

CLI do Azure
Portal do Azure

O comando az ad group create é usado para criar grupos de segurança no Microsoft Entra ID. Os parâmetros --display-name e --main-nickname são necessários. O nome dado ao grupo deve ser baseado no nome do aplicativo. Também é útil incluir uma frase como 'local-dev' no nome do grupo para indicar o propósito 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ê precisa da ID do objeto da entidade de serviço do aplicativo, que é diferente da ID do aplicativo. Utilize o az ad sp list para listar as entidades de serviço disponíveis. O --filter comando parameter aceita filtros de estilo OData e pode ser usado para filtrar a lista conforme mostrado. O --query parâmetro limita as colunas apenas à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 ecrã
Navegue para a página Microsoft Entra ID no portal do Azure digitando Microsoft Entra ID na caixa de pesquisa na parte superior da página e selecionando Microsoft Entra ID nos 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 a partir do nome do aplicativo. Também é útil incluir uma cadeia de caracteres como local-dev no nome do grupo para indicar a finalidade do grupo. Descrição do grupo → Uma descrição do objetivo do grupo. Selecione o link Sem membros selecionados em Membros para adicionar membros ao grupo.
No diálogo Adicionar membros: Use a caixa de pesquisa para filtrar a lista de nomes principais na lista. Selecione os principais serviços de aplicação para desenvolvimento local desta aplicação. À medida que os objetos são selecionados, eles ficarão acinzentados e serão movidos para a lista de Itens selecionados na parte inferior da caixa de diálogo. Quando terminar, selecione o botão Selecionar .
De volta à página Novo grupo , selecione Criar para criar o grupo. O grupo será criado e você será levado de volta 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.

Nota

Por padrão, a criação de grupos de segurança do Microsoft Entra é limitada a determinadas funções privilegiadas em um diretório. Se não conseguir criar um grupo, contacte um administrador do seu diretório. Se não conseguir adicionar membros a um grupo existente, contacte o proprietário do grupo ou um administrador de diretório. Para saber mais, consulte Gerir grupos do Microsoft Entra e associação a grupos.

3 - Atribuir funções à aplicação

Em seguida, você precisa determinar quais funções (permissões) 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 Microsoft Entra criado na etapa 2. As funções podem ser atribuídas em um recurso, grupo de recursos ou escopo de 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 do Azure em um único grupo de recursos.

CLI do Azure
Portal do Azure

Um utilizador, grupo ou principal de serviço de aplicativo é atribuído a um papel no Azure usando o comando az role assignment create. Você pode especificar um grupo com sua ID de objeto. Você pode especificar um principal de serviço de aplicativo com o 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"

![!NOTA] Para impedir que o Git Bash trate /subscriptions/... como um caminho de arquivo, adicione ./ à string do parâmetro scope e use aspas duplas ao redor de 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 o principal de serviço de aplicação com o appId de 00001111-aaaa-2222-bbbb-3333cccc4444 tenha acesso de leitura, gravação e exclusão aos contêineres e dados de blob do Armazenamento do Azure em todas as contas de armazenamento no grupo de recursos msdocs-python-sdk-auth-example na subscrição com o ID aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e, você atribuiria o principal de serviço de aplicação ao papel de Colaborador de Dados de Blob do Armazenamento usando o comando a seguir.

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 ecrã
Localize o grupo de recursos para seu aplicativo pesquisando o nome do grupo de recursos 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 sob o 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 de Controlo de Acesso (IAM): Selecione o separador Atribuição de funções. 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 para o grupo de recursos. Use a caixa de pesquisa para filtrar a lista para um tamanho mais gerenciável. Este exemplo mostra como filtrar por funções de Armazenamento Blob. Selecione a função que pretende 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 Utilizador, grupo ou principal de serviço em Atribuir acesso a. Selecione + 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. Selecione Selecionar na parte inferior da caixa de diálogo para continuar.
O grupo Microsoft Entra é exibido como selecionado no ecrã Adicionar atribuição de função. Selecione Rever + atribuir para ir para a página final e, em seguida, Rever + atribuir novamente para concluir o processo.

4 - Definir variáveis de ambiente de desenvolvimento local

O DefaultAzureCredential objeto procurará as informações do principal do serviço num conjunto de variáveis de ambiente em tempo de execução. 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 .env arquivo 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 .env arquivo nunca é verificado no controle do código-fonte, pois contém a chave secreta do aplicativo para o Azure. O ficheiro .gitignore padrão para Python exclui automaticamente o ficheiro .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 .env arquivo no diretório raiz do aplicativo. Defina os valores das variáveis 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 de 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

Finalmente, no código de inicialização do seu aplicativo, use a python-dotenv biblioteca para ler as variáveis de ambiente do .env arquivo 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 em seu aplicativo

Para autenticar objetos cliente do Azure SDK no Azure, a sua aplicação deve usar a classe DefaultAzureCredentialazure.identity do pacote. Nesse cenário, DefaultAzureCredential detetará se as variáveis de ambiente AZURE_CLIENT_ID, AZURE_TENANT_ID e AZURE_CLIENT_SECRET estão definidas e lerá essas variáveis para obter as informações do principal de serviço da aplicação, 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 de cliente do SDK do Azure em seu aplicativo, você deseja:

Importe a DefaultAzureCredential classe do azure.identity módulo.
Crie um DefaultAzureCredential objeto.
Passe o DefaultAzureCredential objeto para o construtor de objeto de 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)

Comentários

Esta página foi útil?