Início Rápido:Adquirir um token e chamar a API do Microsoft Graph de um aplicativo de console Node.js

Neste guia de início rápido, você baixará e executará um exemplo de código que demonstra como um aplicativo de console Node.js 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.

Este guia de início rápido usa a Biblioteca de Autenticação da Microsoft para Node.js (nó MSAL) com a concessão de credenciais do cliente.

Pré-requisitos

• Node.js
• Visual Studio Code ou outro editor de código

Registrar e baixar o aplicativo de exemplo

Siga as etapas abaixo para começar.

Etapa 1: Registrar o 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:

1. Entre no Centro de administração do Microsoft Entra pelo menos como um Administrador de Aplicativo.
2. Navegue até Identidade>Aplicativos>Registros do aplicativo.
3. Selecione Novo registro.
4. Insira um Nome para seu aplicativo, por exemplo, msal-node-cli. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.
5. Selecione Registrar.
6. Em Gerenciar, selecione Certificados e segredos.
7. 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.
8. Em Gerenciar, selecione Permissões de API>Adicionar uma permissão. Selecione Microsoft Graph.
9. Selecione Permissões de aplicativo.
10. No nó Usuário, selecione User.Read.All e selecione Adicionar permissões.

Etapa 2: Baixar o projeto de exemplo do Node.js

Baixe o exemplo de código

Etapa 3: Configurar o projeto de exemplo do Node.js

1. Extraia o arquivo zip para uma pasta local próxima da raiz do disco, por exemplo, C:\Azure-Samples.

2. Edite .env e substitua os valores dos campos TENANT_ID, CLIENT_ID e CLIENT_SECRET pelo seguinte snippet:

   "TENANT_ID": "Enter_the_Tenant_Id_Here",
   "CLIENT_ID": "Enter_the_Application_Id_Here",
   "CLIENT_SECRET": "Enter_the_Client_Secret_Here"
   

   Em que:

   • Enter_the_Application_Id_Here – é a ID do Aplicativo (cliente) do aplicativo que você registrou anteriormente. Localize essa ID no painel Visão geral do registro de aplicativo.
   • Enter_the_Tenant_Id_Here – substitua esse valor pela ID do Locatário ou pelo Nome do locatário (por exemplo, contoso.microsoft.com). Localize esses valores no painel Visão geral do registro de aplicativo.
   • Enter_the_Client_Secret_Here – substitua esse valor pelo segredo do cliente criado anteriormente. Para gerar uma nova chave, use segredos de Certificados e segredos nas configurações de registro do aplicativo.

   O uso de um segredo de texto não criptografado no código-fonte representa um risco de segurança maior para seu aplicativo. Embora o exemplo neste início rápido use um segredo do cliente de texto não criptografado, é apenas para simplificar. É recomendável usar credenciais de certificado em vez de segredos do cliente nos seus aplicativos cliente confidenciais, especialmente os aplicativos que você pretende implantar na produção.

3. Edite .env e substitua os pontos de extremidade da ID do Microsoft Entra e do Microsoft Graph pelos seguintes valores:

   • Para o ponto de extremidade do Microsoft Entra, substitua Enter_the_Cloud_Instance_Id_Here por https://login.microsoftonline.com.
   • Para o ponto de extremidade do Microsoft Graph, substitua Enter_the_Graph_Endpoint_Here por https://graph.microsoft.com/.

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: alguém a quem tenha sido atribuída no mínimo a função de Administrador do Aplicativo precisa dar consentimento ao seu aplicativo. Selecione uma das opções abaixo, dependendo de sua função:

Administradores

Se foi atribuída a você, no mínimo, a função de Administrador de Aplicativo, acesse a página Permissões de API no Registro de Aplicativo do portal do Azure e selecione Dar consentimento do administrador para {Tenant Name} (em que {Tenant Name} é o nome do seu diretório).

Usuários padrão

Se você for um usuário padrão do seu locatário, precisará solicitar a um administrador de aplicativos em nuvem que conceda consentimento administrativo 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.

Etapa 5: Executar o aplicativo

Localize a pasta raiz do exemplo (em que package.json reside) em um prompt de comando ou console. Você precisará instalar as dependências que o aplicativo de exemplo exige antes de executá-lo pela primeira vez:

npm install

Em seguida, execute o aplicativo via prompt de comando ou console:

node . --op getUsers

Você deverá ver na saída do console um fragmento JSON que representa uma lista de usuários no diretório do Microsoft Entra.

Observações sobre o código

Abaixo, alguns aspectos importantes do aplicativo de exemplo são discutidos.

Nó MSAL

MSAL Node é 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 guia de início rápido solicita tokens por permissões de aplicativo (usando a própria identidade do aplicativo), em vez de permissões delegadas. O fluxo de autenticação usado nesse caso é conhecido como fluxo de credenciais do cliente OAuth 2.0. Para obter mais informações sobre como usar o MSAL Node com aplicativos daemon, confira Cenário: aplicativo daemon.

Instale o MSAL Node executando o comando npm a seguir.

npm install @azure/msal-node --save

Inicialização da MSAL

Você pode adicionar a referência da MSAL adicionando o seguinte código:

const msal = require('@azure/msal-node');

Em seguida, inicialize a MSAL usando o seguinte código:

const msalConfig = {
    auth: {
        clientId: "Enter_the_Application_Id_Here",
        authority: "https://login.microsoftonline.com/Enter_the_Tenant_Id_Here",
        clientSecret: "Enter_the_Client_Secret_Here",
   }
};
const cca = new msal.ConfidentialClientApplication(msalConfig);

Em que:	Descrição
clientId	É a ID do aplicativo (cliente) relativa ao aplicativo registrado no portal do Azure. Você pode encontrar esse valor na página Visão Geral do aplicativo no portal do Azure.
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.
clientSecret	É o segredo do cliente criado para o aplicativo no portal do Azure.

Para saber mais, confira a documentação de referência do ConfidentialClientApplication

Solicitando tokens

Para solicitar um token usando a identidade do aplicativo, use o método acquireTokenByClientCredential:

const tokenRequest = {
    scopes: [ 'https://graph.microsoft.com/.default' ],
};

const tokenResponse = await cca.acquireTokenByClientCredential(tokenRequest);

Em que:	Descrição
tokenRequest	Contém os escopos solicitados. Para 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 de aplicativo definido no portal do Azure (no caso do Microsoft Graph, {Application ID URI} aponta para https://graph.microsoft.com). Para APIs Web personalizadas, o {Application ID URI} é definido na seção Expor uma API no Registro de aplicativo do portal do Azure.
tokenResponse	A resposta contém um token de acesso para os escopos solicitados.

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 o desenvolvimento de aplicativos daemon/de console com o MSAL Node, confira o tutorial:

Aplicativo daemon que chama APIs Web