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

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

Neste artigo, você conclui as seguintes tarefas:

• Registre e configure uma API da 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.

• Execute e teste o aplicativo Web e a API de exemplo.

Pré-requisitos

• Conclua as etapas em Entrar usuários e chamar uma API no artigo de exemplo Node.js aplicativo Web. Este artigo mostra como iniciar sessão de utilizadores utilizando um exemplo de aplicação Web Node.js.
• Visual Studio Code ou outro editor de código.
• Node.js.
• .NET 7.0 ou posterior.
• 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.

Registar uma API Web

Nesta etapa, você cria os registros do aplicativo Web e da API Web e especifica os escopos da 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 escopos de API

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

Uma API precisa publicar no mínimo 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 aplicativos, selecione o aplicativo de API que você criou (ciam-ToDoList-api) para abrir sua página Visão geral.

2. Em Gerenciar, selecione Expor uma API.

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

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

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

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

   Property	valor
   Nome do âmbito	ToDoList.Leia
   Quem pode consentir	Apenas administradores
   Nome a apresentar do consentimento do administrador	Leia a lista de ToDo dos usuários usando o 'TodoListApi'
   Descrição do consentimento do administrador	Permita que o aplicativo leia a lista de ToDo do usuário usando o 'TodoListApi'.
   Estado	Ativado

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

   Property	valor
   Nome do âmbito	ToDoList.ReadWrite
   Quem pode consentir	Apenas administradores
   Nome a apresentar do consentimento do administrador	Leia e escreva a lista de ToDo dos usuários usando o 'ToDoListApi'
   Descrição do consentimento do administrador	Permitir que o aplicativo leia e escreva a lista de ToDo do usuário usando o 'ToDoListApi'
   Estado	Ativado

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

9. Defina accessTokenAcceptedVersion a propriedade como 2.

10. Selecione Guardar.

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

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.

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 ao aplicativo Web

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

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 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 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 é locatário de um 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 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 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 total é semelhante a api://{clientId}/{ToDoList.Read} ou api://{clientId}/{ToDoList.ReadWrite}.

Clonar ou baixar aplicativo Web de exemplo e 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
  

• Transfira o ficheiro .zip. 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 do console e mude 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 dependências de aplicativos Web:

   npm install && npm update
   

Configurar o aplicativo Web e a API de exemplo

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

1. Abra uma janela do console e execute a API da 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 vá para http://localhost:3000.

4. Selecione o botão Entrar . Ser-lhe-á pedido para iniciar sessão.

   

5. Na página de início de sessão, escreva o seu endereço de e-mail, selecione Seguinte, escreva a sua Palavra-passe e, em seguida, selecione Iniciar sessão. Se você não tiver uma conta, selecione Sem conta? Crie um link, que inicia o fluxo de inscrição.

6. Se você escolher a opção de inscrição, depois de preencher seu e-mail, senha única, nova senha e mais detalhes da conta, você conclui todo o fluxo de inscrição. Você verá uma página semelhante à captura de tela a seguir. Você verá uma página semelhante se escolher a opção de login.

   

Chamar a API

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

   

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

Como funciona

Você aciona uma chamada de API sempre que visualiza, adiciona ou remove uma tarefa. Cada vez que você aciona uma chamada de API, o aplicativo Web cliente adquire um token de acesso com as permissões (escopos) necessárias para chamar um ponto de extremidade de API. Por exemplo, para ler uma tarefa, o aplicativo Web cliente deve adquirir um token de acesso com ToDoList.Read permissão/escopo.

O ponto de extremidade da API da 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 401 Unauthorized erro HTTP.

Conteúdos relacionados

• Inicie sessão de utilizadores e chame uma API na sua própria aplicação Web Node.js.
• Habilite a redefinição de senha.
• Personalize a marca padrão.
• Configure o início de sessão com o Google.