Chamar uma API em um aplicativo daemon do Node.js de exemplo

Artigo
04/16/2024

Este guia usa um aplicativo daemon do Node.js de exemplo para mostrar como um aplicativo daemon adquire um token para chamar uma API Web. O Microsoft Entra protege a API Web.

Um aplicativo daemon adquire token em seu próprio nome (não em nome de um usuário). Os usuários não podem interagir com um aplicativo daemon porque ele requer a própria identidade. Esse tipo de aplicativo solicita um token de acesso usando sua identidade de aplicativo e apresentando sua ID de aplicativo, credenciais (senha ou certificado) e URI de ID do aplicativo para o External ID.

Um aplicativo daemon usa a concessão das credenciais de cliente do OAuth 2.0 padrão. Para simplificar o processo de aquisição do token, o exemplo que usamos neste artigo usa a MSAL Node (Biblioteca de Autenticação da Microsoft para Node).

Pré-requisitos

Visual Studio Code ou outro editor de código.
Node.js.
.NET 7.0 ou posterior.
Um locatário externo. Se você ainda não tiver um, inscreva-se para uma avaliação gratuita.

Registrar um aplicativo daemon e uma API Web

Nesta etapa, você cria o daemon e o registro de aplicativo de API Web, além de especificar os escopos da API Web.

Registrar um aplicativo da API Web

Faça login no Centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de aplicativos.
Se tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o seu locatário externo no menu Diretórios + assinaturas.
Navegue até Identidade>Aplicativos>Registros do aplicativo.
Selecione + Novo Registro.
Na página Registrar um aplicativo que aparece, insira as informações de registro do aplicativo:
1. Na seção Nome, insira algo fácil de lembrar para ser exibido aos usuários do aplicativo, por exemplo, ciam-ToDoList-api.
2. Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional.
Selecione Registrar para criar o aplicativo.
O painel Visão geral do aplicativo é exibido quando o registro for concluído. Registre a ID do Diretório (locatário) e a ID do aplicativo (cliente) a ser usada no código-fonte do aplicativo.

Configurar funções de aplicativo

Uma API precisa publicar pelo menos uma função de aplicativo, também chamada de Permissão de Aplicativo, para que os aplicativos cliente possam obter um token de acesso em nome deles próprios. As permissões de aplicativo são o tipo de permissões que as APIs devem publicar quando desejam permitir que os aplicativos cliente se autentiquem com êxito como eles mesmos e não precisem conectar usuários. Para publicar uma permissão de aplicativo, siga estas etapas:

Na página Registros de aplicativo, selecione o aplicativo que você criou (como ciam-ToDoList-api) para abrir sua página Visão geral.
Em Gerenciar, selecione Funções do aplicativo.

Selecione Criar função do aplicativo, insira os seguintes valores e selecione Aplicar para salvar suas alterações:

Propriedade	Valor
Nome de exibição	ToDoList.Read.All
Tipos de membro permitidos	Aplicativos
Valor	ToDoList.Read.All
Descrição	Permitir que o aplicativo leia a lista ToDo de cada usuário usando "TodoListApi"

Selecione Criar função de aplicativo novamente, insira os seguintes valores para a segunda função de aplicativo e selecione Aplicar para salvar suas alterações:

Propriedade	Valor
Nome de exibição	ToDoList.ReadWrite.All
Tipos de membro permitidos	Aplicativos
Valor	ToDoList.ReadWrite.All
Descrição	Permitir que o aplicativo leia e grave na lista ToDo de cada usuário usando 'TodoListApi'

Configurar declarações opcionais

Os tokens retornados pela identidade da Microsoft são mantidos menores para garantir o desempenho ideal pelos clientes que os solicitam. Como resultado, várias declarações não estão mais presentes no token por padrão e devem ser solicitadas especificamente por aplicativo. Para este aplicativo, inclua a declaração opcional idtyp para ajudar a API Web a determinar se um token é um token de aplicativo ou aplicativo+usuário. Embora você possa usar uma combinação de declarações scp e funções para a mesma finalidade, o uso da declaração idtyp é a maneira mais fácil de diferenciar um token de aplicativo e um token de aplicativo+ usuário. Por exemplo, o valor dessa declaração é app quando o token é um token somente de aplicativo.

Use as seguintes etapas para configurar a declaração opcional idtyp:

Na página Registros de aplicativo, para a qual você deseja configurar a declaração opcional, comociam-client-app, para abrir sua página Visão geral.
Em Gerenciar, selecione Configuração de token.
Escolha Adicionar declaração opcional.
Em Tipo de token, escolha Acesso.
Selecione a declaração opcional idtyp.
Selecione Adicionar para salvar as alterações.

Registrar um aplicativo daemon

Para permitir a entrada de usuários com o Microsoft Entra no seu aplicativo, a ID externa do Microsoft Entra deve estar ciente do aplicativo criado. O registro do aplicativo estabelece uma relação de confiança entre o aplicativo e o Microsoft Entra. Quando você registra um aplicativo, o External ID gera um identificador exclusivo conhecido como ID do Aplicativo (cliente), um valor usado para identificar seu aplicativo ao criar solicitações de autenticação.

As etapas a seguir mostram como registrar seu aplicativo no centro de administração do Microsoft Entra:

Faça login no Centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de aplicativos.
Se tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o seu locatário externo no menu Diretórios + assinaturas.
Navegue até Identidade>Aplicativos>Registros do aplicativo.
Selecione + Novo Registro.
Na página Registrar um aplicativo que aparece;
1. Insira um Nome de aplicativo relevante que será exibido aos usuários do aplicativo, por exemplo,ciam-client-app.
2. Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional.
Selecione Registrar.
O painel Visão geral do aplicativo será exibido após o registro bem-sucedido. Grave a ID do aplicativo (cliente) que será usada no código-fonte do aplicativo.

Criar um segredo do cliente

Crie um segredo do cliente para o aplicativo registrado. O aplicativo usa o segredo do cliente para confirmar sua identidade ao solicitar tokens.

Na página Registros de aplicativo, selecione o aplicativo que você criou (como ciam-client-app) para abrir sua página Visão geral.
Em Gerenciar, selecione Certificados e segredos.
Selecione Novo segredo do cliente.
Na caixa Descrição, insira uma descrição para o segredo do cliente (por exemplo, ciam app client secret).
Em Expira, selecione o período pelo qual o segredo será válido (conforme as regras de segurança da sua organização) e selecione Adicionar.
Registre o Valor do segredo. Você usará esse valor para uma configuração em uma etapa posterior. O valor secreto não será exibido novamente e não poderá ser recuperado de forma nenhuma depois que você sair dos Certificados e segredos. Certifique-se de registrá-lo.

Conceder permissões de API para o aplicativo daemon

Na página Registros de aplicativo, selecione o aplicativo que você criou, como ciam-client-app.
Em Gerenciar, selecione Permissões de API.
Em Permissões Configuradas, selecione Adicionar uma permissão.
Selecione a guia APIs que a minha organização usa.
Na lista de APIs, selecione a API como ciam-ToDoList-api.
Selecione a opção Permissões de aplicativo. Selecionamos essa opção pois o aplicativo entra como ele mesmo, não como um usuário.
Na lista de permissões, selecione TodoList.Read.All, ToDoList.ReadWrite.ALL (use a caixa de pesquisa, se necessário).
Selecione o botão Adicionar permissões.
Neste ponto, você atribuiu as permissões corretamente. No entanto, como o aplicativo daemon não permite que os usuários interajam com ele, os próprios usuários não podem consentir com essas permissões. Para resolver esse problema, você, como administrador, deve consentir com essas permissões em nome de todos os usuários no locatário:
1. Selecione Dar consentimento de administrador para <nome do seu locatário> e selecione Sim.
2. Selecione Atualizar e verifique se Concedido para <nome do seu locatário> aparece em Status para ambas as permissões.

Clonar ou baixar o aplicativo daemon de exemplo e a API Web

Para obter o aplicativo de exemplo, você pode cloná-lo do GitHub ou baixá-lo como um arquivo .zip.

Para clonar o exemplo, abra um prompt de comando e navegue até onde deseja criar o projeto e insira o seguinte comando:
```
git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
```
Baixar o arquivo .zip. Extraia-o para um caminho de arquivo em que o comprimento do nome seja menor que 260 caracteres.

Instalar as dependências do projeto

Abra uma janela do console e altere para o diretório que contém o aplicativo de amostra Node.js:
```
cd 2-Authorization\3-call-api-node-daemon\App
```
Execute os seguintes comandos para instalar as dependências do aplicativo:
```
npm install && npm update
```

Configurar o aplicativo daemon de exemplo e a API

Para usar o registro de aplicativo no exemplo de aplicativo Web do cliente:

No seu editor de código, abra o arquivo App\authConfig.js.
Localize o espaço reservado:
- Enter_the_Application_Id_Here e substitua pela ID do Aplicativo (cliente) referente ao aplicativo daemon registrado anteriormente.
- Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio do diretório (locatário). Por exemplo, se o domínio primário do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o nome do locatário, saiba como ler os detalhes do locatário.
- Enter_the_Client_Secret_Here e substitua-o pelo valor do segredo do aplicativo daemon copiado anteriormente.
- Enter_the_Web_Api_Application_Id_Here e substitua-o pela ID do aplicativo (cliente) da API Web que você copiou anteriormente.

Para usar o registro de aplicativo no exemplo de API Web:

No seu editor de código, abra o arquivo API\ToDoListAPI\appsettings.json.
Localize o espaço reservado:
- Enter_the_Application_Id_Here e substitua-o pela ID do aplicativo (cliente) da API Web que você copiou.
- Enter_the_Tenant_Id_Here e substitua-o pela ID do diretório (locatário) que você copiou anteriormente.
- Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio do diretório (locatário). Por exemplo, se o domínio primário do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o nome do locatário, saiba como ler os detalhes do locatário.

Executar e testar a API e o aplicativo daemon de exemplo

Abra uma janela do console e execute a API Web usando os seguintes comandos:
```
cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
dotnet run
```

Execute o cliente do aplicativo Web usando os seguintes comandos:

2-Authorization\3-call-api-node-daemon\App
node . --op getToDos

Se o aplicativo daemon e a API Web forem executados com êxito, você deverá ver algo semelhante à seguinte matriz JSON na janela do console

{
    "id": 1,
    "owner": "3e8....-db63-43a2-a767-5d7db...",
    "description": "Pick up grocery"
},
{
    "id": 2,
    "owner": "c3cc....-c4ec-4531-a197-cb919ed.....",
    "description": "Finish invoice report"
},
{
    "id": 3,
    "owner": "a35e....-3b8a-4632-8c4f-ffb840d.....",
    "description": "Water plants"
}

Como ele funciona

O aplicativo Node.js usa a concessão de credenciais de cliente do OAuth 2.0 para adquirir um token de acesso para si mesmo e não para o usuário. O token de acesso que o aplicativo solicita contém as permissões representadas como funções. O fluxo de credenciais do cliente usa esse conjunto de permissões no lugar de escopos de usuário para tokens de aplicativos. Você expôs essas permissões de aplicativo na API da Web anteriormente e, em seguida, concedeu-as ao aplicativo daemon.

No lado da API, a API Web deve verificar se o token de acesso tem as permissões necessárias (permissões de aplicativo). A API Web não pode aceitar um token de acesso que não tenha as permissões necessárias.

Acesso a dados

Um ponto de extremidade da API Web deve estar preparado para aceitar chamadas de usuários e aplicativos. Portanto, ele deve ter uma maneira de responder a cada solicitação adequadamente. Por exemplo, uma chamada de um usuário por meio de permissões/escopos delegados recebe a lista de tarefas pendentes de dados do usuário. Por outro lado, uma chamada de um aplicativo por meio de permissões/funções de aplicativo pode receber toda a lista de tarefas pendentes. No entanto, neste artigo, estamos fazendo apenas uma chamada de aplicativo. Portanto, não precisamos configurar permissões/escopos delegados.