Conectar usuários e chamar uma API Web em um aplicativo Web Node.js de exemplo

Este guia usa um código de exemplo para mostrar como adicionar a autenticação e autorização em um aplicativo Web do Node.js. O aplicativo de exemplo conecta usuários em um aplicativo Web Node.js, que, em seguida, chama uma API do .NET. Você habilita a autenticação e autorização usando os detalhes do locatário externo. O aplicativo Web de exemplo usa a MSAL (Biblioteca de Autenticação da Microsoft) para Node para lidar com autenticação.

Neste artigo, você concluirá as seguintes tarefas:

• Registre e configure uma API Web no centro de administração do Microsoft Entra.

• Atualize um aplicativo Web de nó de exemplo e ASP.NET API Web para usar os detalhes do locatário externo.

• Executar e testar a API e o aplicativo Web de exemplo.

Pré-requisitos

• Conclua as etapas em no artigo Conectar usuários e chamar uma API em um aplicativo Web Node.js de exemplo. Este artigo mostra como conectar usuários usando um aplicativo Web do Node.js de exemplo.
• Visual Studio Code ou outro editor de código.
• Node.js.
• .NET 7.0 ou posterior.
• Um locatário externo. Para criar um, você pode utilizar 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 uma API Web

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

Registrar um aplicativo da API Web

1. Faça login no Centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de aplicativos.

2. 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.

3. Navegue até Identidade>Aplicativos>Registros do aplicativo.

4. Selecione + Novo Registro.

5. 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.

6. Selecione Registrar para criar o aplicativo.

7. 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 escopos de API

Essa API precisa expor permissões, que um cliente precisa adquirir para chamar a API:

Uma API precisa publicar um mínimo de um escopo, também chamado de permissão delegada, para que os aplicativos cliente obtenham um token de acesso para um usuário com êxito. Para publicar um escopo, siga estas etapas:

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

2. Em Gerenciar, selecione Expor uma API.

3. Na parte superior da página, ao lado do URI da ID do Aplicativo, selecione o link Adicionar para gerar um URI exclusivo para esse aplicativo.

4. Aceite o URI da ID do Aplicativo proposto, como api://{clientId}, e selecione Salvar. Quando o aplicativo Web solicita um token de acesso à API Web, ele adiciona esse URI como prefixo para cada escopo que você define para a API.

5. Em Escopos definidos por esta API, selecione Adicionar um escopo.

6. Digite os seguintes valores que definem um acesso de leitura à API e selecione Adicionar escopo para salvar as alterações:

   Propriedade	Valor
   Nome do escopo	ToDoList.Read
   Quem pode consentir	Somente administradores
   Nome de exibição de consentimento do administrador	Leia a lista de tarefas dos usuários usando a "TodoListApi"
   Descrição do consentimento do administrador	Permita que o aplicativo leia a lista de tarefas do usuário usando a TodoListApi".
   Estado	Enabled

7. Selecione Adicionar um escopo novamente e digite os seguintes valores que definem um escopo de acesso de leitura e gravação à API. Selecione Adicionar escopo para salvar as alterações:

   Propriedade	Valor
   Nome do escopo	ToDoList.ReadWrite
   Quem pode consentir	Somente administradores
   Nome de exibição de consentimento do administrador	Leia e grave listas ToDo usando “ToDoListApi”
   Descrição do consentimento do administrador	Permita que o aplicativo leia e grave na lista ToDo do usuário usando “ToDoListApi”
   Estado	Enabled

8. Em Gerenciar, selecione Manifesto para abrir o editor de manifesto da API.

9. Defina a propriedade accessTokenAcceptedVersion como 2.

10. Selecione Salvar.

Saiba mais sobre o princípio do privilégio mínimo ao publicar permissões para uma API Web.

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:

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

2. Em Gerenciar, selecione Funções do aplicativo.

3. 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"

4. 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

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

Use as etapas no artigo Configurar declarações opcionais para adicionar a declaração idtyp ao token de acesso:

• Para o Tipo de token, selecione Acesso.
• Na lista de declarações opcionais, selecione idtyp.

Conceder permissões de API para o aplicativo Web

Para conceder permissões de API ao aplicativo cliente (ciam-client-app), siga estas etapas:

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

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

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

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

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

6. Selecione a opção Permissões delegadas.

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

8. Selecione o botão Adicionar permissões. Neste ponto, você atribuiu as permissões corretamente. No entanto, como o locatário é um locatário do cliente, os próprios usuários consumidores 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 ambos os escopos.

9. Na lista Permissões configuradas, selecione as permissões ToDoList.Read e ToDoList.ReadWrite, uma de cada vez, e copie o URI completo da permissão para uso posterior. O URI de permissão completa é semelhante a api://{clientId}/{ToDoList.Read} ou api://{clientId}/{ToDoList.ReadWrite}.

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

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

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

   cd 2-Authorization\4-call-api-express\App
   

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

   npm install && npm update
   

Configurar a API e o aplicativo Web de exemplo

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

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

2. Localize o espaço reservado:

   • Enter_the_Application_Id_Here e substitua pela ID do Aplicativo (cliente) referente ao aplicativo registrado anteriormente.
   • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio 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 copiado anteriormente.
   • Enter_the_Web_Api_Application_Id_Here e substitua-o pela ID do aplicativo (cliente) da API Web copiado anteriormente.

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

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

2. 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 o exemplo de API e aplicativo Web

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

   cd 2-Authorization\4-call-api-express\API\ToDoListAPI
   dotnet run
   

2. Execute o cliente do aplicativo Web usando os seguintes comandos:

   cd 2-Authorization\4-call-api-express\App
   npm start
   

3. Abra o navegador e acesse http://localhost:3000.

4. Selecione o botão Entrar. Você é solicitado a fazer login.

   

5. Na página de entrada, digite seu endereço de Email, selecione Avançar, digite sua Senha e, em seguida, selecione Entrar. Se você não tiver uma conta, selecione o link Não tem uma conta? Crie uma, que iniciará o fluxo de inscrição.

6. Se você escolher a opção de inscrição, após preencher seu email, senha de uso único, nova senha e mais detalhes da conta, você concluirá todo o fluxo de inscrição. Você verá uma página semelhante à seguinte captura de tela. Você verá uma página semelhante se escolher a opção de entrada.

   

Chamar API

1. Para chamar a API, selecione o link Exibir sua lista de tarefas pendentes. Você verá uma página semelhante à seguinte captura de tela.

   

2. Manipule a lista de tarefas pendentes criando e removendo itens.

Como ele funciona

Você dispara uma chamada à API sempre que exibir, adicionar ou remover uma tarefa. Sempre que você dispara uma chamada à API, o aplicativo Web cliente adquire um token de acesso com as permissões necessárias (escopos) para chamar um ponto de extremidade de API. Por exemplo, para ler uma tarefa, o aplicativo Web cliente precisa adquirir um token de acesso com permissão/escopo ToDoList.Read.

O ponto de extremidade da API Web precisa verificar se as permissões ou escopos no token de acesso, fornecidos pelo aplicativo cliente, são válidos. Se o token de acesso for válido, o ponto de extremidade responderá à solicitação HTTP; caso contrário, ele responderá com um erro HTTP 401 Unauthorized.

Conteúdo relacionado

• Conecte usuários e chame uma API em seu aplicativo Web Node.js.
• Habilitar a redefinição de senha.
• Personalize a identidade visual padrão.
• Configure a entrada com o Google.