Share via

Iniciar sessão de utilizadores e chamar uma API na aplicação Web de exemplo Node.js

  • Artigo

Este guia de procedimentos utiliza um exemplo Node.js aplicação Web para lhe mostrar como adicionar autenticação e autorização. O exemplo de aplicação inicia sessão de utilizadores numa aplicação Web Node.js, que, em seguida, chama uma API .NET. Pode ativar a autenticação e autorização com o seu ID de Microsoft Entra para os detalhes do inquilino dos clientes. A aplicação Web de exemplo utiliza a Biblioteca de Autenticação da Microsoft (MSAL) para o Node para processar a autenticação.

Neste artigo, irá concluir as seguintes tarefas:

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

  • Registe e configure uma aplicação Web cliente no centro de administração do Microsoft Entra.

  • Crie um fluxo de utilizador de inscrição e início de sessão no centro de administração do Microsoft Entra e, em seguida, associe uma aplicação Web cliente ao mesmo.

  • Atualize uma aplicação Web node de exemplo e ASP.NET API Web para utilizar o ID Externo para os detalhes do inquilino dos clientes.

  • Execute e teste a aplicação Web de exemplo e a API.

Pré-requisitos

Registar uma aplicação Web e uma API Web

Neste passo, vai criar a Web e os registos de aplicações da API Web e especificar os âmbitos da sua API Web.

Registar uma aplicação API Web

  1. Inicie sessão no centro de administração do Microsoft Entra como, pelo menos, um Programador de Aplicações.

  2. Se tiver acesso a vários inquilinos, utilize o filtro Diretórios + subscrições no menu superior para mudar para o inquilino do cliente.

  3. Navegue paraAplicações> de Identidade>Registos de aplicações.

  4. Selecione + Novo registo.

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

    1. Na secção Nome, introduza um nome de aplicação relevante que será apresentado aos utilizadores da aplicação, por exemplo ciam-ToDoList-api.

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

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

  7. 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 âmbitos de API

Esta API tem de expor as permissões, que um cliente tem de adquirir para chamar a API:

Uma API precisa de publicar um mínimo de um âmbito, também denominado Permissão Delegada, para que as aplicações cliente obtenham um token de acesso para um utilizador com êxito. Para publicar um âmbito, siga estes passos:

  1. Na página Registos de aplicações, selecione a aplicação API que criou (ciam-ToDoList-api) para abrir a respetiva página Descrição Geral.

  2. Em Gerir, selecione Expor uma API.

  3. Na parte superior da página, junto a URI do ID da Aplicação, selecione a ligação Adicionar para gerar um URI exclusivo para esta aplicação.

  4. Aceite o URI de ID da Aplicação proposto, como api://{clientId}, e selecione Guardar. Quando a aplicação Web pede um token de acesso para a API Web, adiciona o URI como o prefixo para cada âmbito que definir para a API.

  5. Em Âmbitos definidos por esta API, selecione Adicionar um âmbito.

  6. Introduza os seguintes valores que definem um acesso de leitura à API e, em seguida, selecione Adicionar âmbito para guardar as alterações:

    Propriedade Valor
    Nome do âmbito ToDoList.Read
    Quem pode consentir Apenas administradores
    Nome a apresentar do consentimento do administrador Ler a lista ToDo dos utilizadores com a "TodoListApi"
    Descrição do consentimento do administrador Permitir que a aplicação leia a lista toDo do utilizador com a "TodoListApi".
    Estado Ativado

  7. Selecione Adicionar um âmbito novamente e introduza os seguintes valores que definem um âmbito de acesso de leitura e escrita à API. Selecione Adicionar âmbito para guardar as alterações:

    Propriedade Valor
    Nome do âmbito ToDoList.ReadWrite
    Quem pode consentir Apenas administradores
    Nome a apresentar do consentimento do administrador Ler e escrever a lista toDo dos utilizadores com a "ToDoListApi"
    Descrição do consentimento do administrador Permitir que a aplicação leia e escreva a lista toDo do utilizador com "ToDoListApi"
    Estado Ativado

  8. Em Gerir, selecione Manifesto para abrir o editor de manifestos 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 Web.

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:

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

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

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

  4. 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 scp e funções possa ser utilizada para a mesma finalidade, 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 é aplicação quando o token é um token apenas de aplicação.

Utilize os seguintes passos para configurar a afirmação opcional do idtyp :

  1. Em Gerir, selecione Configuração do token.

  2. Selecione Adicionar afirmação opcional.

  3. Em Tipo de token, selecione Access.

  4. Selecione o idtyp de afirmação opcional.

  5. Selecione Adicionar para guardar as alterações.

Registar a aplicação Web

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:

  1. Inicie sessão no centro de administração do Microsoft Entra como, pelo menos, um Programador de Aplicações.

  2. Se tiver acesso a vários inquilinos, utilize o filtro Diretórios + subscrições no menu superior para mudar para o inquilino do cliente.

  3. Navegue paraAplicações> de Identidade>Registos de aplicações.

  4. Selecione + Novo registo.

  5. Na página Registar uma aplicação apresentada;

    1. Introduza um Nome de aplicação relevante que seja apresentado aos utilizadores da aplicação, por exemplo ciam-client-app.
    2. Em Tipos de conta suportados, selecione Contas apenas neste diretório organizacional.

  6. Selecione Registar.

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

Para especificar o seu tipo de aplicação para o registo de aplicações, siga estes passos:

  1. Em Gerir, selecione Autenticação.
  2. Na página Configurações da plataforma , selecione Adicionar uma plataforma e, em seguida, selecione opção Web .
  3. Para os URIs de Redirecionamento, introduzahttp://localhost:3000/auth/redirect
  4. Selecione Configurar para guardar as alterações.
  5. Na página Configurações da plataforma , na Web, selecione Adicionar URI e, em seguida, introduza http://localhost:3000/
  6. Selecione Guardar para guardar as alterações e certifique-se de que ambos os URIs estão listados.

Criar um segredo do cliente

Crie um segredo de cliente para a aplicação registada. A aplicação utiliza o segredo do cliente para provar a sua identidade quando pede tokens.

  1. Na página Registos de aplicações, selecione a aplicação que criou (como ciam-client-app) para abrir a página Descrição geral.
  2. Em Gerir, selecione Segredos de certificados&.
  3. Selecione Novo segredo do cliente.
  4. Na caixa Descrição , introduza uma descrição para o segredo do cliente (por exemplo, segredo do cliente da aplicação 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. 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 é recuperável por qualquer meio, depois de navegar para longe da página Certificados e segredos , por isso certifique-se de que o grava.
Para uma segurança melhorada, considere utilizar certificados em vez de segredos do cliente.

Conceder permissões de API à aplicação Web

Para conceder permissões à API da aplicação cliente (ciam-client-app), siga estes passos:

  1. Na página Registos de aplicações, selecione a aplicação que criou (como ciam-client-app) para abrir a página Descrição geral.

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

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

  4. Selecione o separador APIs da Microsoft .

  5. Na secção APIs da Microsoft mais utilizadas , selecione Microsoft Graph.

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

  7. Na secção Selecionar permissões , procure e selecione permissões openid e offline_access .

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

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

  10. Selecione o separador As Minhas APIs .

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

  12. Selecione opção Permissões delegadas .

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

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

  15. Neste momento, atribuiu as permissões corretamente. No entanto, uma vez que o inquilino é inquilino de um cliente, 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:

    1. Selecione Conceder consentimento ao administrador para <o seu nome> de inquilino e, em seguida, selecione Sim.

    2. Selecione Atualizar e, em seguida, verifique se a opção Concedido para <o seu nome> de inquilino é apresentada em Estado para ambos os âmbitos.

  16. Na lista Permissões configuradas , selecione as permissões ToDoList.Read e ToDoList.ReadWrite , uma de cada vez, e, em seguida, copie o URI completo da permissão para utilização posterior. O URI de permissão completo tem um aspeto semelhante a api://{clientId}/{ToDoList.Read} ou api://{clientId}/{ToDoList.ReadWrite}.

Criar um fluxo de utilizador

Siga estes passos para criar um fluxo de utilizador que um cliente pode utilizar para iniciar sessão ou inscrever-se numa aplicação.

  1. Inicie sessão no centro de administração do Microsoft Entra como, pelo menos, um Administrador de Fluxo de Utilizador de ID Externo.

  2. Se tiver acesso a vários inquilinos, utilize o filtro Diretórios + subscrições no menu superior para mudar para o inquilino do cliente.

  3. Navegue até Fluxos de utilizadorde Identidades Externas> de Identidades>Externas.

  4. Selecione + Novo fluxo de utilizador.

  5. Na página Criar :

    1. Introduza um Nome para o fluxo de utilizador, como SignInSignUpSample.

    2. Na lista Fornecedores de identidade, selecione Email Contas. Este fornecedor de identidade permite que os utilizadores iniciem sessão ou se inscrevam com o respetivo endereço de e-mail.

      Nota

      Os fornecedores de identidade adicionais só serão listados aqui depois de configurar a federação com os mesmos. Por exemplo, se configurar a federação com o Google ou o Facebook, poderá selecionar esses fornecedores de identidade adicionais aqui.

    3. Em Email contas, pode selecionar uma das duas opções. Para este tutorial, selecione Email com palavra-passe.

      • Email com palavra-passe: permite que os novos utilizadores se inscrevam e iniciem sessão com um endereço de e-mail como o nome de início de sessão e uma palavra-passe como credencial de primeiro fator.

      • Email código de acesso único: permite que os novos utilizadores se inscrevam e iniciem sessão com um endereço de e-mail como o nome de início de sessão e o código de acesso por e-mail único como a sua primeira credencial de fator.

        Nota

        Email código de acesso único tem de estar ativado ao nível do inquilino (Todos os Fornecedores> de Identidade Email código de acesso único) para que esta opção esteja disponível ao nível do fluxo de utilizador.

    4. Em Atributos de utilizador, selecione os atributos que pretende recolher do utilizador após a inscrição. Ao selecionar Mostrar mais, pode escolher atributos e afirmações para País/Região, Nome a Apresentar e Código Postal. Selecione OK. (Os utilizadores só são solicitados atributos quando se inscrevem pela primeira vez.)

  6. Selecione Criar. O novo fluxo de utilizador é apresentado na lista Fluxos de utilizador. Se necessário, atualize a página.

Para ativar a reposição personalizada de palavra-passe, utilize os passos no artigo Ativar a reposição personalizada de palavra-passe .

Associar a aplicação Web ao fluxo de utilizador

Embora muitas aplicações possam ser associadas ao fluxo de utilizador, uma única aplicação só pode ser associada a um fluxo de utilizador. Um fluxo de utilizador permite a configuração da experiência do utilizador para aplicações específicas. Por exemplo, pode configurar um fluxo de utilizador que requer que os utilizadores iniciem sessão ou se inscrevam com um número de telefone ou endereço de e-mail.

  1. No menu da barra lateral, selecione Identidade.

  2. Selecione Identidades Externas e, em seguida, Fluxos de utilizador.

  3. Na página Fluxos de utilizador, selecione o Nome do fluxo de utilizador que criou anteriormente, por exemplo SignInSignUpSample.

  4. Em Utilizar, selecione Aplicações.

  5. Selecione Adicionar aplicação.

  6. Selecione a aplicação na lista, como ciam-client-app ou utilize a caixa de pesquisa para localizar a aplicação e, em seguida, selecione-a.

  7. Escolha Selecionar.

Clonar ou transferir a aplicação Web de exemplo e a API Web

Para obter a aplicação Web e o código de exemplo da API Web, 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 .zip ficheiro, 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

  1. Abra uma janela da consola e altere para o diretório que contém a aplicação de exemplo Node.js/Express:

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

  2. Execute os seguintes comandos para instalar dependências de aplicações Web:

    npm install && npm update

Configurar a aplicação Web de exemplo e a API

Para utilizar o registo da aplicação no exemplo da aplicação Web cliente:

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

  2. Localize o marcador de posição:

    • Enter_the_Application_Id_Here e substitua-o pelo ID de Aplicação (cliente) da aplicação que registou anteriormente.

    • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio diretório (inquilino). Por exemplo, se o domínio primário do inquilino for contoso.onmicrosoft.com, utilize contoso. Se não tiver o seu nome de inquilino, saiba como ler os detalhes do inquilino.

    • Enter_the_Client_Secret_Here e substitua-o pelo valor do segredo da aplicação que copiou anteriormente.

    • Enter_the_Web_Api_Application_Id_Here e 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:

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

  2. Localize o marcador de posição:

    • Enter_the_Application_Id_Here e substitua-o pelo ID da Aplicação (cliente) da API Web que copiou.

    • Enter_the_Tenant_Id_Here e substitua-o pelo ID do Diretório (inquilino) que copiou anteriormente.

    • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio diretório (inquilino). Por exemplo, se o domínio primário do inquilino for contoso.onmicrosoft.com, utilize contoso. Se não tiver o seu nome de inquilino, saiba como ler os detalhes do inquilino.

Executar e testar a aplicação Web e a API de exemplo

  1. Abra uma janela da consola e, em seguida, execute a API Web com os seguintes comandos:

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

  2. Execute o cliente da aplicação Web com os seguintes comandos:

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

  3. Abra o browser e, em seguida, aceda a http://localhost:3000.

  4. Selecione o botão Iniciar Sessão . É-lhe pedido para iniciar sessão.

    Captura de ecrã a mostrar o início de sessão numa aplicação Web de nó.

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

  6. Se escolher a opção de inscrição, depois de preencher o seu e-mail, código de acesso único, nova palavra-passe e mais detalhes da conta, conclui todo o fluxo de inscrição. Verá uma página semelhante à seguinte captura de ecrã. Verá uma página semelhante se escolher a opção de início de sessão.

    Captura de ecrã a mostrar o início de sessão numa aplicação Web de nó e a chamar uma API.

Chamar a API

  1. Para chamar a API, selecione a ligação Ver a sua lista de tarefas . Verá uma página semelhante à seguinte captura de ecrã.

    Captura de ecrã a mostrar a lista de tarefas da API de manipulação.

  2. Manipular a lista de tarefas ao criar e remover itens.

Como funciona

Aciona uma chamada à API sempre que vê, adiciona ou remove uma tarefa. Sempre que aciona uma chamada à API, a aplicação Web cliente adquire um token de acesso com as permissões (âmbitos) necessárias para chamar um ponto final de API. Por exemplo, para ler uma tarefa, a aplicação Web cliente tem de adquirir um token de acesso com ToDoList.Read permissão/âmbito.

Do lado da API Web, o ponto final tem de validar que as permissões/âmbitos presentes no token de acesso, que a aplicação cliente apresenta, são válidos. Se o token de acesso for válido, o ponto final responde ao pedido HTTP, caso contrário, responde com um 401 Unauthorized erro HTTP.

Passos seguintes

Aprenda a: