Guia de início rápido: adquira um token e chame o Microsoft Graph de um aplicativo de console do Node.js

Artigo
12/13/2023

Neste início rápido, você baixa e executa 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 serviço do Windows pode ser executado com uma identidade de aplicativo, em vez da identidade de um 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

Registe-se e descarregue a aplicação de exemplo

Siga os passos abaixo para começar.

Passo 1: Registar a candidatura

Gorjeta

As etapas neste artigo podem variar ligeiramente com base no portal a partir do qual você começou.

Para registar a sua aplicação e adicionar as informações de registo da aplicação à sua solução manualmente, siga os passos a seguir:

Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicativos.
Navegue até Registros do aplicativo Identity>Applications>.
Selecione Novo registo.
Introduza um Nome para a sua aplicação, por exemplo msal-node-cli. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.
Selecione Registar.
Em Gerenciar, selecione Certificados & segredos.
Em Segredos do cliente, selecione Novo segredo do cliente, insira um nome e selecione Adicionar. Registre o valor secreto em um local seguro para uso em uma etapa posterior.
Em Gerenciar, selecione Permissões>de API Adicionar uma permissão. Selecione Microsoft Graph.
Selecione Permissões de aplicação.
Em Nó Usuário, selecione User.Read.All e, em seguida, selecione Adicionar permissões.

Etapa 2: Baixe o projeto de exemplo Node.js

Baixe o exemplo de código

Etapa 3: Configurar o projeto de exemplo Node.js

Extraia o arquivo zip para uma pasta local próxima à raiz do disco, por exemplo, C:/Azure-Samples.
Edite .env e substitua os valores dos campos TENANT_ID, CLIENT_IDe CLIENT_SECRET pelo seguinte trecho:
```
"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- é o ID do aplicativo (cliente) do aplicativo que você registrou anteriormente. Encontre esse ID na Visão geral do registro do aplicativo.
- Enter_the_Tenant_Id_Here- substitua esse valor pelo ID do locatário ou nome do locatário (por exemplo, contoso.microsoft.com). Encontre esses valores na Visão geral do registro do aplicativo.
- Enter_the_Client_Secret_Here - Substitua esse valor pelo segredo do cliente que você criou anteriormente. Para gerar uma nova chave, use Certificados & segredos nas configurações de registro do aplicativo.
Usar um segredo de texto sem formatação no código-fonte representa um risco de segurança maior para seu aplicativo. Embora o exemplo neste guia de início rápido use um segredo de cliente de texto simples, é apenas para simplificar. Recomendamos o uso de credenciais de certificado em vez de segredos de cliente em seus aplicativos cliente confidenciais, especialmente os aplicativos que você pretende implantar na produção.
Edite .env e substitua o ID do Microsoft Entra e os pontos de extremidade do Microsoft Graph pelos seguintes valores:
- Para o ponto de extremidade 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/.

Se você tentar executar o aplicativo neste ponto, você receberá HTTP 403 - Erro proibido : Insufficient privileges to complete the operation. Este erro acontece porque qualquer permissão apenas para aplicações requer o consentimento do administrador: um Administrador de Aplicações ou um Administrador Global tem de dar o seu consentimento para a sua aplicação. Selecione uma das opções abaixo, dependendo da sua função:

Administradores

Se lhe forem atribuídas as funções de Administrador de Aplicações ou Administrador Global, aceda à página Permissões de API no Registo de Aplicações do portal do Azure e selecione Conceder consentimento de administrador para {Nome do Inquilino} (onde {Nome do Inquilino} é o nome do seu diretório).

Usuários padrão

Se for um utilizador padrão do seu inquilino, terá de pedir a um Administrador Global para conceder consentimento de administrador para a sua aplicação. Para fazer isso, forneça 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 pelo ID do Locatário ou Nome do Locatário (por exemplo, contoso.microsoft.com)
Enter_the_Application_Id_Here - é o ID da Aplicação (cliente) que registou.

Etapa 5: Executar o aplicativo

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

npm install

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

node . --op getUsers

Você deve ver na saída do console algum fragmento JSON representando uma lista de usuários no diretório do Microsoft Entra.

Sobre o código

Abaixo, alguns dos aspetos importantes da aplicação de exemplo são discutidos.

Nó MSAL

MSAL Node é a biblioteca usada para entrar usuários e solicitar tokens usados para acessar uma API protegida pela plataforma de identidade da Microsoft. Conforme descrito, esse 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 neste caso é conhecido como fluxo de credenciais de cliente OAuth 2.0. Para obter mais informações sobre como usar o MSAL Node com aplicativos daemon, consulte Cenário: aplicativo Daemon.

Você pode instalar o MSAL Node executando o seguinte comando npm.

npm install @azure/msal-node --save

Inicialização da MSAL

Pode adicionar a referência para MSAL, adicionando o código seguinte:

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

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

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:	Description
`clientId`	É o ID de Aplicação (cliente) da aplicação registada no portal do Azure. Pode encontrar este valor na página Descrição geral da aplicação no portal do Azure.
`authority`	O ponto final STS para o utilizador autenticar. Geralmente `https://login.microsoftonline.com/{tenant}` para nuvem pública, onde {tenant} é o nome do seu locatário ou seu ID de locatário.
`clientSecret`	É o segredo do cliente criado para o aplicativo no portal do Azure.

Para obter mais informações, consulte a documentação de referência para ConfidentialClientApplication

Solicitar tokens

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

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

const tokenResponse = await cca.acquireTokenByClientCredential(tokenRequest);

Em que: Description

tokenRequest Contém os escopos solicitados. Para clientes confidenciais, isso deve usar o formato semelhante para {Application ID URI}/.default indicar que os escopos que estão sendo solicitados são os definidos estaticamente no objeto de aplicativo definido no portal do Azure (para o Microsoft Graph, {Application ID URI} aponta para https://graph.microsoft.com). Para APIs Web personalizadas, {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.

Em que:	Description
`tokenRequest`	Contém os escopos solicitados. Para clientes confidenciais, isso deve usar o formato semelhante para `{Application ID URI}/.default` indicar que os escopos que estão sendo solicitados são os definidos estaticamente no objeto de aplicativo definido no portal do Azure (para o Microsoft Graph, `{Application ID URI}` aponta para `https://graph.microsoft.com`). Para APIs Web personalizadas, `{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 comunicar um problema ou quiser saber mais sobre as suas opções de suporte, consulte Ajuda e suporte para programadores.

Próximos passos

Para saber mais sobre o desenvolvimento de aplicativos daemon/console com o MSAL Node, consulte o tutorial:

Aplicativo Daemon que chama APIs da Web