Início Rápido: adquirir um token e chamar o Microsoft Graph de um aplicativo daemon Python
Neste guia de início rápido, você baixará e executará um exemplo de código que demonstra como um aplicativo Python pode obter um token de acesso usando a identidade do aplicativo para chamar a API do Microsoft Graph e exibir uma lista de usuários no diretório. O exemplo de código demonstra como um trabalho autônomo ou um serviço Windows pode ser executado com uma identidade de aplicativo, em vez de uma identidade do usuário.
Pré-requisitos
Para executar este exemplo, você precisa de:
Registrar e baixar o aplicativo de início rápido
Etapa 1: Registre seu aplicativo
Dica
As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.
Para registrar seu aplicativo e adicionar as informações de registro do aplicativo à solução manualmente, siga estas etapas:
- Entre no Centro de administração do Microsoft Entra.
- Se você tiver acesso a vários locatários, use o ícone Configurações
no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas. - Navegue até Identidade>Aplicativos>Registros de aplicativo e selecione Novo registro.
- Insira um Nome para seu aplicativo, por exemplo,
Daemon-console. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde. - Selecione Registrar.
- Em Gerenciar, selecione Certificados e segredos.
- Em Segredos do cliente, selecione Novo segredo do cliente, insira um nome e selecione Adicionar. Registre o valor secreto em uma localização segura para uso em uma etapa posterior.
- Em Gerenciar, selecione Permissões de API>Adicionar uma permissão. Selecione Microsoft Graph.
- Selecione Permissões de aplicativo.
- No nó Usuário, selecione User.Read.All e selecione Adicionar permissões.
Etapa 2: Baixar o projeto Python
Baixe o projeto do daemon do Python
Etapa 3: Configurar o projeto Python
Extraia o arquivo zip para uma pasta local mais próxima da raiz do disco, por exemplo, C:\Azure-Samples.
Procure a subpasta 1-Call-MsGraph-WithSecret.
Edite parameters.json e substitua os valores dos campos
authority,client_idesecretpelo seguinte trecho:"authority": "https://login.microsoftonline.com/Enter_the_Tenant_Id_Here", "client_id": "Enter_the_Application_Id_Here", "secret": "Enter_the_Client_Secret_Here"Em que:
Enter_the_Application_Id_Here- é a ID do aplicativo (cliente) que você registrou.Enter_the_Tenant_Id_Here– substitua esse valor pela ID do locatário ou pelo Nome do locatário (por exemplo, contoso.microsoft.com)Enter_the_Client_Secret_Here– substitua esse valor pelo segredo do cliente criado na etapa 1.
Dica
Para encontrar os valores da ID do aplicativo (cliente), ID de diretório (locatário), acesse a página Visão Geral do Centro de administração do Microsoft Entra. Para gerar uma nova chave, acesse a página Certificados e segredos.
Etapa 4: Consentimento do administrador
Se você tentar executar o aplicativo neste ponto, receberá o erro HTTP 403 – Proibido: Insufficient privileges to complete the operation. Esse erro acontece porque qualquer permissão somente do aplicativo exige o Consentimento do administrador: um Administrador Global do seu diretório precisa dar consentimento ao seu aplicativo. Selecione uma das opções abaixo, dependendo de sua função:
Administrator de locatário global
Se você for um administrador de locatários global, acesse a página Permissões de API em Registros do aplicativo no Centro de administração do Microsoft Entra e selecione Fornecer o consentimento do administrador para {Nome do Locatário} (em que {Nome do Locatário} é o nome do seu diretório).
Usuário padrão
Se você é um usuário padrão do seu locatário, solicite ao Administrador global que forneça consentimento do administrador para seu aplicativo. Para fazer isso, dê a seguinte URL ao administrador:
https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here
Em que:
Enter_the_Tenant_Id_Here– substitua esse valor pela ID do locatário ou pelo Nome do locatário (por exemplo, contoso.microsoft.com)Enter_the_Application_Id_Here- é a ID do aplicativo (cliente) que você registrou anteriormente.
Etapa 5: Executar o aplicativo
Você precisará instalar as dependências deste exemplo uma só vez.
pip install -r requirements.txt
Em seguida, execute o aplicativo via prompt de comando ou console:
python confidential_client_secret_sample.py parameters.json
Você deverá ver na saída do console um fragmento JSON que representa uma lista de usuários no diretório do Microsoft Entra.
Importante
Este aplicativo de início rápido usa um segredo do cliente para se identificar como cliente confidencial. Como o segredo do cliente é adicionado como texto sem formatação a seus arquivos de projeto, por motivos de segurança, é recomendável que você use um certificado, em vez de um segredo do cliente, antes de considerar o aplicativo como aplicativo de produção. Para obter mais informações sobre como usar um certificado, confira estas instruções no mesmo repositório GitHub deste exemplo, mas na segunda pasta 2-Call-MsGraph-WithCertificate.
Mais informações
MSAL Python
MSAL Python é a biblioteca usada para conectar usuários e solicitar tokens usados para acessar uma API protegida pela plataforma de identidade da Microsoft. Conforme descrito, este início rápido solicita tokens usando a identidade do próprio aplicativo, em vez de permissões delegadas. O fluxo de autenticação usado nesse caso é conhecido como fluxo OAuth de credenciais do cliente . Para obter mais informações sobre como usar a MSAL Python com aplicativos daemon, consulte este artigo.
Instale a MSAL Python executando o seguinte comando de pip.
pip install msal
Inicialização da MSAL
Você pode adicionar a referência da MSAL adicionando o seguinte código:
import msal
Em seguida, inicialize a MSAL usando o seguinte código:
app = msal.ConfidentialClientApplication(
config["client_id"], authority=config["authority"],
client_credential=config["secret"])
| Em que: | Descrição |
|---|---|
config["secret"] |
O segredo do cliente criado no aplicativo no Centro de administração do Microsoft Entra. |
config["client_id"] |
É a ID do aplicativo (cliente) do aplicativo registrado no Centro de administração do Microsoft Entra. Você pode encontrar esse valor na página Visão Geral do aplicativo no Centro de administração do Microsoft Entra. |
config["authority"] |
O ponto de extremidade do STS para o usuário autenticar. Normalmente, https://login.microsoftonline.com/{tenant} para a nuvem pública, em que {tenant} é o nome do seu locatário ou o ID do seu locatário. |
Para obter mais informações, confira a documentação de referência do ConfidentialClientApplication.
Solicitando tokens
Para solicitar um token usando a identidade do aplicativo, use o método AcquireTokenForClient:
result = None
result = app.acquire_token_silent(config["scope"], account=None)
if not result:
logging.info("No suitable token exists in cache. Let's get a new one from AAD.")
result = app.acquire_token_for_client(scopes=config["scope"])
| Em que: | Descrição |
|---|---|
config["scope"] |
Contém os escopos solicitados. Para os clientes confidenciais, ele deve usar um formato semelhante a {Application ID URI}/.default para indicar que os escopos solicitados são os estaticamente definidos no objeto do aplicativo definido no Centro de administração do Microsoft Entra (no caso do Microsoft Graph, {Application ID URI} aponta para https://graph.microsoft.com). Para as APIs Web personalizadas, o {Application ID URI} é definido na seção Expor uma API em Registros do aplicativo no Centro de administração do Microsoft Entra. |
Para obter mais informações, confira a documentação de referência do AcquireTokenForClient.
Ajuda e suporte
Se precisar de ajuda, quiser relatar um problema ou desejar saber mais sobre as opções de suporte, confira Ajuda e suporte para desenvolvedores.
Próximas etapas
Para saber mais sobre aplicativos daemon, confira a página de aterrissagem do cenário.