Partilhar via

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

  • Artigo

Este guia usa um exemplo de aplicativo daemon Node.js para mostrar como um aplicativo daemon adquire um token de acesso para chamar uma API da Web.

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

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

Pré-requisitos

  • Um locatário externo. Para criar um, escolha um dos seguintes métodos:
    • (Recomendado) Use a extensão de ID Externa do Microsoft Entra para configurar um locatário externo diretamente no Visual Studio Code.
    • Crie um novo locatário externo no centro de administração do Microsoft Entra.

Registrar um aplicativo daemon e uma API da Web

Nesta etapa, você cria o daemon e os registros do aplicativo da API da Web e especifica os escopos da sua API da Web.

Registrar um aplicativo de API da Web

  1. Entre no centro de administração do Microsoft Entra como pelo menos um desenvolvedor de aplicativos.

  2. Se tiver acesso a vários inquilinos, utilize o ícone Definições no menu superior para mudar para o inquilino externo a partir do menu Diretórios + subscrições.

  3. Navegue até Registros do aplicativo Identity>Applications>.

  4. Selecione + Novo registo.

  5. Na página Registar uma candidatura apresentada, introduza as informações de registo da sua candidatura:

    1. Na seção Nome, insira um nome de aplicativo significativo que será exibido para os usuários do aplicativo, por exemplo , ciam-ToDoList-api.

    2. Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional.

  6. Selecione Registar para criar a aplicação.

  7. O painel Visão geral do aplicativo é exibido quando o registro é concluído. Registre o ID do diretório (locatário) e o ID do aplicativo (cliente) a serem usados no código-fonte do aplicativo.

Configurar funções do aplicativo

Uma API precisa publicar um mínimo de uma função de aplicativo para aplicativos, também chamada de Permissão de Aplicativo, para que os aplicativos cliente obtenham um token de acesso como eles mesmos. 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 entrar usuários. Para publicar uma permissão de aplicativo, execute estas etapas:

  1. Na página Registros de aplicativos, selecione o aplicativo que você criou (como ciam-ToDoList-api) para abrir sua página Visão geral.

  2. Em Gerir, selecione Funções da aplicação.

  3. Selecione Criar função de aplicativo, insira os seguintes valores e selecione Aplicar para salvar as alterações:

    Property valor
    Display name ToDoList.Read.All
    Tipos de membros permitidos Aplicações
    Value ToDoList.Read.All
    Description Permita que o aplicativo leia a lista de ToDo de cada usuário usando o 'TodoListApi'

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

    Property valor
    Display name ToDoList.ReadWrite.All
    Tipos de membros permitidos Aplicações
    Value ToDoList.ReadWrite.All
    Description Permita que o aplicativo leia e escreva a lista de ToDo de cada usuário usando o 'ToDoListApi'

Configurar afirmações opcionais

Você pode idtyp declaração opcional para ajudar a API da Web a determinar se um token é um token de aplicativo ou um token de aplicativo + de usuário. Embora você possa usar uma combinação de declarações scp e roles para a mesma finalidade, usar a 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 app.

Registrar o aplicativo daemon

Para permitir que seu aplicativo entre usuários com o Microsoft Entra, a ID Externa do Microsoft Entra deve estar ciente do aplicativo criado. O registo da aplicação estabelece uma relação de confiança entre a aplicação e o Microsoft Entra. Quando você registra um aplicativo, o ID externo 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:

  1. Entre no centro de administração do Microsoft Entra como pelo menos um desenvolvedor de aplicativos.

  2. Se tiver acesso a vários inquilinos, utilize o ícone Definições no menu superior para mudar para o inquilino externo a partir do menu Diretórios + subscrições.

  3. Navegue até Registros do aplicativo Identity>Applications>.

  4. Selecione + Novo registo.

  5. Na página Registar uma candidatura que aparece;

    1. Insira um Nome de aplicativo significativo que é exibido para os usuários do aplicativo, por exemplo, ciam-client-app.
    2. Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional.

  6. Selecione Registar.

  7. O painel Visão geral do aplicativo é exibido após o registro bem-sucedido. Registre o ID do aplicativo (cliente) a ser usado no código-fonte do aplicativo.

Criar um segredo do cliente

Crie um segredo de cliente para o aplicativo registrado. O aplicativo usa o segredo do cliente para provar sua identidade quando solicita tokens.

  1. Na página Registros de aplicativos, selecione o aplicativo que você criou (como ciam-client-app) para abrir a página Visão geral.
  2. Em Gerenciar, selecione Certificados & segredos.
  3. Selecione Novo segredo do cliente.
  4. Na caixa Descrição, insira uma descrição para o segredo do cliente (por exemplo, segredo do cliente do aplicativo ciam).
  5. 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.
  6. Registre o valor do segredo. Você usará esse valor para configuração em uma etapa posterior. O valor secreto não será exibido novamente e não poderá ser recuperado por nenhum meio, depois que você navegar para longe dos Certificados e segredos. Certifique-se de gravá-lo.

Conceder permissões de API para o aplicativo daemon

  1. Na página Registros de aplicativos, selecione o aplicativo que você criou, como ciam-client-app.

  2. Em Gerenciar, selecione Permissões de API.

  3. Em Permissões configuradas, selecione Adicionar uma permissão.

  4. Selecione a guia APIs que minha organização usa .

  5. Na lista de APIs, selecione a API, como ciam-ToDoList-api.

  6. Selecione a opção Permissões do aplicativo. Selecionamos essa opção quando o aplicativo entra como ele mesmo, mas não em nome de um usuário.

  7. Na lista de permissões, selecione TodoList.Read.All, ToDoList.ReadWrite.All (use a caixa de pesquisa, se necessário).

  8. Selecione o botão Adicionar permissões .

  9. 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 Conceder consentimento de administrador para <o nome> do seu inquilino e, em seguida, selecione Sim.
    2. Selecione Atualizar e verifique se Concedido para <o nome> do locatário aparece em Status para ambas as permissões.

Clone ou baixe o aplicativo daemon de exemplo e a API da 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 digite o seguinte comando:

    git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git

  • Como alternativa, baixe os exemplos .zip arquivo e, em seguida, extraia-o para um caminho de arquivo onde o comprimento do nome é inferior a 260 caracteres.

Instalar dependências do projeto

  1. Abra uma janela de console e mude para o diretório que contém o aplicativo de exemplo Node.js:

    cd 2-Authorization\3-call-api-node-daemon\App

  2. Execute os seguintes comandos para instalar as dependências do aplicativo:

    npm install && npm update

Configurar o aplicativo de daemon de exemplo e a API

Para usar seu registro de aplicativo no exemplo de aplicativo Web cliente:

  1. No editor de códigos, abra o App\authConfig.js arquivo.

  2. Encontre o espaço reservado:

    • Enter_the_Application_Id_Here e substitua-o pelo ID do aplicativo (cliente) do aplicativo daemon que você registrou anteriormente.

    • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o nome do inquilino, saiba como ler os detalhes do inquilino.

    • Enter_the_Client_Secret_Here e substitua-o pelo valor secreto do aplicativo daemon copiado anteriormente.

    • Enter_the_Web_Api_Application_Id_Here e substitua-o pelo ID do aplicativo (cliente) da API da Web que você copiou anteriormente.

Para usar seu registro de aplicativo no exemplo de API da Web:

  1. No editor de códigos, abra o API\ToDoListAPI\appsettings.json arquivo.

  2. Encontre o espaço reservado:

    • Enter_the_Application_Id_Here e substitua-o pelo ID do aplicativo (cliente) da API da Web que você copiou.

    • Enter_the_Tenant_Id_Here e substitua-o pelo ID do diretório (locatário) copiado anteriormente.

    • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o nome do inquilino, saiba como ler os detalhes do inquilino.

Executar e testar o aplicativo de daemon de exemplo e a API

  1. Abra uma janela do console e execute a API da Web usando os seguintes comandos:

    cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
dotnet run

  2. 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 da Web forem executados com êxito, você 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 funciona

O aplicativo Node.js usa a concessão de credenciais de cliente 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 aplicativo. 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 da Web deve verificar se o token de acesso tem as permissões necessárias (permissões de aplicativo). A API da 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 de API Web deve estar preparado para aceitar chamadas de usuários e aplicativos. Por conseguinte, deve ter uma forma de responder a cada pedido em conformidade. 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. No entanto, neste artigo, estamos fazendo apenas uma chamada de aplicativo, portanto, não precisamos configurar permissões/escopos delegados.

Conteúdos relacionados