Chamar uma API numa aplicação daemon de exemplo Node.js
Este artigo utiliza um exemplo Node.js aplicação daemon para lhe mostrar como uma aplicação daemon adquire um token para chamar uma API Web. Microsoft Entra ID para clientes protege a API Web.
Uma aplicação daemon adquire um token em nome próprio (não em nome de um utilizador). Os utilizadores não podem interagir com uma aplicação daemon porque requer a sua própria identidade. Este tipo de aplicação pede um token de acesso através da respetiva identidade de aplicação e apresenta o ID da aplicação, a credencial (palavra-passe ou certificado) e o URI do ID da aplicação para O ID Externo.
Uma aplicação daemon utiliza a concessão de credenciais de cliente OAuth 2.0 padrão. Para simplificar o processo de aquisição do token, o exemplo que utilizamos neste artigo utiliza a Biblioteca de Autenticação da Microsoft para Nó (Nó MSAL).
Pré-requisitos
.NET 7.0 ou posterior.
Visual Studio Code ou outro editor de código.
Microsoft Entra ID do inquilino dos clientes. Se ainda não tiver uma, inscreva-se numa avaliação gratuita.
Registar uma aplicação daemon e uma API Web
Neste passo, vai criar o daemon e os registos de aplicações da API Web e especificar os âmbitos da API Web.
Registar uma aplicação API Web
Inicie sessão no centro de administração do Microsoft Entra como, pelo menos, um Programador de Aplicações.
Se tiver acesso a vários inquilinos, utilize o filtro
Diretórios + subscrições no menu superior para mudar para o inquilino do cliente.Navegue paraAplicações> de Identidade>Registos de aplicações.
Selecione + Novo registo.
Na página Registar uma aplicação apresentada, introduza as informações de registo da aplicação:
Na secção Nome, introduza um nome de aplicação relevante que será apresentado aos utilizadores da aplicação, por exemplo ciam-ToDoList-api.
Em Tipos de conta suportados, selecione Contas apenas neste diretório organizacional.
Selecione Registar para criar a aplicação.
O painel Descrição Geral da aplicação é apresentado quando o registo estiver concluído. Registe o ID do Diretório (inquilino) e o ID da Aplicação (cliente) a utilizar no código fonte da aplicação.
Configurar funções de aplicação
Uma API tem de publicar um mínimo de uma função de aplicação para aplicações, também denominada Permissão de Aplicação, para que as aplicações cliente obtenham um token de acesso como elas próprias. As permissões da aplicação são o tipo de permissões que as APIs devem publicar quando pretendem permitir que as aplicações cliente se autentiquem com êxito como si mesmas e não precisem de iniciar sessão dos utilizadores. Para publicar uma permissão de aplicação, siga estes passos:
Na página Registos de aplicações, selecione a aplicação que criou (como ciam-ToDoList-api) para abrir a respetiva página Descrição geral.
Em Gerir, selecione Funções de aplicação.
Selecione Criar função de aplicação e, em seguida, introduza os seguintes valores e, em seguida, selecione Aplicar para guardar as alterações:
Propriedade Valor Nome a apresentar ToDoList.Read.All Tipos de membros permitidos Aplicações Valor ToDoList.Read.All Description Permitir que a aplicação leia a lista toDo de todos os utilizadores com a "TodoListApi" Selecione Criar função de aplicação novamente e, em seguida, introduza os seguintes valores para a segunda função de aplicação e, em seguida, selecione Aplicar para guardar as alterações:
Propriedade Valor Nome a apresentar ToDoList.ReadWrite.All Tipos de membros permitidos Aplicações Valor ToDoList.ReadWrite.All Description Permitir que a aplicação leia e escreva a lista ToDo de todos os utilizadores com a "ToDoListApi"
Configurar afirmações opcionais
Os tokens devolvidos pela identidade da Microsoft são mantidos mais pequenos para garantir um desempenho ideal por parte dos clientes que os solicitam. Como resultado, várias afirmações já não estão presentes no token por predefinição e têm de ser pedidas especificamente por aplicação. Para esta aplicação, inclui a afirmação opcional idtyp para ajudar a API Web a determinar se um token é um token de aplicação ou um token de aplicação+utilizador. Embora uma combinação de afirmações de scp e funções possa ser utilizada para o mesmo fim, a utilização da afirmação idtyp é a forma mais fácil de distinguir um token de aplicação e um token de aplicação+utilizador. Por exemplo, o valor desta afirmação é a aplicação quando o token é um token apenas de aplicação.
Utilize os seguintes passos para configurar a afirmação opcional do idtyp :
Em Gerir, selecione Configuração de tokens.
Selecione Adicionar afirmação opcional.
Em Tipo de token, selecione Access.
Selecione o idtyp de afirmação opcional.
Selecione Adicionar para guardar as alterações.
Registar a aplicação daemon
Para permitir que a sua aplicação inicie sessão de utilizadores com Microsoft Entra, Microsoft Entra ID para os clientes tem de ter conhecimento da aplicação que criar. O registo da aplicação estabelece uma relação de confiança entre a aplicação e Microsoft Entra. Quando regista uma aplicação, o ID Externo gera um identificador exclusivo conhecido como ID de Aplicação (cliente), um valor utilizado para identificar a sua aplicação ao criar pedidos de autenticação.
Os passos seguintes mostram-lhe como registar a sua aplicação no centro de administração do Microsoft Entra:
Inicie sessão no centro de administração do Microsoft Entra como, pelo menos, um Programador de Aplicações.
Se tiver acesso a vários inquilinos, utilize o filtro
Diretórios + subscrições no menu superior para mudar para o inquilino do cliente.Navegue paraAplicações> de Identidade>Registos de aplicações.
Selecione + Novo registo.
Na página Registar uma aplicação apresentada;
- Introduza um Nome de aplicação relevante que seja apresentado aos utilizadores da aplicação, por exemplo ciam-client-app.
- Em Tipos de conta suportados, selecione Contas apenas neste diretório organizacional.
Selecione Registar.
O painel Descrição Geral da aplicação é apresentado após o registo com êxito. Registe o ID da Aplicação (cliente) a ser utilizado no código fonte da aplicação.
Criar um segredo do cliente
Crie um segredo do cliente para a aplicação registada. A aplicação utiliza o segredo do cliente para provar a sua identidade quando pede tokens.
- Na página Registos de aplicações, selecione a aplicação que criou (como ciam-client-app) para abrir a respetiva página Descrição geral.
- Em Gerir, selecione Segredos de certificados&.
- Selecione Novo segredo do cliente.
- Na caixa Descrição , introduza uma descrição para o segredo do cliente (por exemplo, segredo do cliente da aplicação ciam).
- Em Expira, selecione uma duração para a qual o segredo é válido (de acordo com as regras de segurança da sua organização) e, em seguida, selecione Adicionar.
- Registe o Valor do segredo. Irá utilizar este valor para configuração num passo posterior.
Nota
O valor do segredo não será apresentado novamente e não será recuperável por nenhum meio, depois de navegar para fora da página Certificados e segredos , por isso certifique-se de que o grava.
Para maior segurança, considere utilizar certificados em vez de segredos do cliente.
Conceder permissões de API à aplicação daemon
Na página Registos de aplicações, selecione a aplicação que criou, como ciam-client-app.
Em Gerir, selecione Permissões de API.
Em Permissões configuradas, selecione Adicionar uma permissão.
Selecione o separador As Minhas APIs .
Na lista de APIs, selecione a API, como ciam-ToDoList-api.
Selecione a opção Permissões de aplicação . Selecionamos esta opção à medida que a aplicação inicia sessão como ela própria e não como utilizadores.
Na lista de permissões, selecione TodoList.Read.All, ToDoList.ReadWrite.All (utilize a caixa de pesquisa, se necessário).
Selecione o botão Adicionar permissões .
Neste momento, atribuiu as permissões corretamente. No entanto, uma vez que a aplicação daemon não permite que os utilizadores interajam com a mesma, os próprios utilizadores não podem consentir estas permissões. Para resolver este problema, como administrador tem de dar consentimento a estas permissões em nome de todos os utilizadores no inquilino:
- Selecione Conceder consentimento ao administrador para <o seu nome> de inquilino e, em seguida, selecione Sim.
- Selecione Atualizar e, em seguida, verifique se Concedido para <o seu nome> de inquilino aparece em Estado para ambas as permissões.
Clonar ou transferir a aplicação daemon de exemplo e a API Web
Para obter o código de exemplo da aplicação Web, pode realizar uma das seguintes tarefas:
Transfira o ficheiro .zip ou clone a aplicação Web de exemplo a partir do GitHub ao executar o seguinte comando:
git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
Se optar por transferir o ficheiro .zip , extraia o ficheiro de aplicação de exemplo para uma pasta onde o comprimento total do caminho seja de 260 ou menos carateres.
Instalar dependências do projeto
Abra uma janela da consola e altere para o diretório que contém o Node.js aplicação de exemplo:
cd 2-Authorization\3-call-api-node-daemon\AppExecute os seguintes comandos para instalar dependências de aplicações:
npm install && npm update
Configurar a aplicação daemon de exemplo e a API
Para utilizar o registo da aplicação no exemplo da aplicação Web cliente:
No seu editor de código, abra o
App\authConfig.jsficheiro.Localize o marcador de posição:
Enter_the_Application_Id_Heree substitua-o pelo ID da Aplicação (cliente) da aplicação daemon que registou anteriormente.Enter_the_Tenant_Subdomain_Heree substitua-o pelo subdomínio diretório (inquilino). Por exemplo, se o domínio primário do inquilino forcontoso.onmicrosoft.com, utilizecontoso. Se não tiver o seu nome de inquilino, saiba como ler os detalhes do inquilino.Enter_the_Client_Secret_Heree substitua-o pelo valor do segredo da aplicação daemon que copiou anteriormente.Enter_the_Web_Api_Application_Id_Heree substitua-o pelo ID da Aplicação (cliente) da API Web que copiou anteriormente.
Para utilizar o registo da aplicação no exemplo de API Web:
No seu editor de código, abra o
API\ToDoListAPI\appsettings.jsonficheiro.Localize o marcador de posição:
Enter_the_Application_Id_Heree substitua-o pelo ID da Aplicação (cliente) da API Web que copiou.Enter_the_Tenant_Id_Heree substitua-o pelo ID do Diretório (inquilino) que copiou anteriormente.Enter_the_Tenant_Subdomain_Heree substitua-o pelo subdomínio diretório (inquilino). Por exemplo, se o domínio primário do inquilino forcontoso.onmicrosoft.com, utilizecontoso. Se não tiver o seu nome de inquilino, saiba como ler os detalhes do inquilino.
Executar e testar a aplicação daemon de exemplo e a API
Abra uma janela da consola e, em seguida, execute a API Web com os seguintes comandos:
cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI dotnet runExecute o cliente da aplicação Web com os seguintes comandos:
2-Authorization\3-call-api-node-daemon\App node . --op getToDos
Se a aplicação daemon e a API Web forem executadas com êxito, deverá ver algo semelhante à seguinte matriz JSON na janela da consola
{
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 funciona
A aplicação Node.js utiliza a concessão de credenciais de cliente OAuth 2.0 para adquirir um token de acesso para si e não para o utilizador. O token de acesso que a aplicação pede contém as permissões representadas como funções. O fluxo de credenciais do cliente utiliza este conjunto de permissões em vez de âmbitos de utilizador para tokens de aplicações. Expôs estas permissões de aplicação na API Web anteriormente e, em seguida, concedeu-as à aplicação daemon.
Do lado da API, a API Web tem de verificar se o token de acesso tem as permissões necessárias (permissões de aplicação). 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 final da API Web deve estar preparado para aceitar chamadas de utilizadores e aplicações. Por conseguinte, deve ter uma forma de responder a cada pedido em conformidade. Por exemplo, uma chamada de um utilizador através de permissões/âmbitos delegados recebe a lista de tarefas de dados do utilizador. Por outro lado, uma chamada de uma aplicação através de permissões/funções de aplicação pode receber a lista de tarefas completa. No entanto, neste artigo, estamos apenas a fazer uma chamada de aplicação, pelo que não precisávamos de configurar permissões/âmbitos delegados.