Partilhar via

Início rápido - Fazer login de utilizadores e chamar uma API Web em aplicação Web de exemplo Node.js

Aplica-se a: círculo verde com um símbolo de marca de seleção branco que indica que o conteúdo a seguir se aplica a locatários externos. Inquilinos externos (saiba mais)

Neste Guia de Início Rápido, irá aprender a autenticar utilizadores e chamar uma API web de uma aplicação web Node.js no seu tenant externo. O aplicativo de exemplo chama uma API .NET. O aplicativo Web de exemplo usa Microsoft Authentication Library (MSAL) para Node para manipular a autenticação.

Pré-requisitos

Configurar escopos e funções da API

Ao registrar a API da Web, você deve configurar os escopos da API para definir as permissões que um aplicativo cliente pode solicitar para acessar a API da Web. Além disso, você precisa configurar funções de aplicativo para especificar as funções disponíveis para usuários ou aplicativos e conceder as permissões de API necessárias ao aplicativo Web para permitir que ele chame a API Web.

Configurar escopos de API

Uma API precisa publicar pelo menos um escopo, também chamado de Permissão Delegada, para que os aplicativos cliente obtenham com êxito um token de acesso para um utilizador. Para publicar um escopo, siga estas etapas:

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

  2. Em Gerenciar, selecione Expor uma API.

  3. Na parte superior da página, ao lado de URI de ID do Aplicativo, selecione o link Adicionar para gerar um URI exclusivo para esta aplicação.

  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:

    Propriedade Valor
    Nome do escopo ToDoList.Ler
    Quem pode consentir Apenas administradores
    Nome de exibição do consentimento do administrador Leia a lista de ToDo dos usuários usando o 'TodoListApi'
    Descrição do consentimento do administrador Permitir que a aplicação leia a lista de ToDo do utilizador usando a '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 âmbito para salvar suas alterações.

    Propriedade Valor
    Nome do escopo ListaDeTarefas.LerEscrever
    Quem pode consentir Apenas administradores
    Nome de exibição do consentimento do administrador Ler e escrever a lista de tarefas dos utilizadores utilizando a 'ToDoListApi'
    Descrição do consentimento do administrador Permitir que a aplicação leia e escreva a lista de tarefas do utilizador usando a 'ToDoListApi'
    Estado ativado

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

Configurar funções do 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 obtenham 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 como si mesmos com sucesso e não precisem que os usuários façam login. Para publicar uma permissão de aplicativo, execute estas etapas:

  1. Na página Registos de aplicações , selecione a aplicação que criou (como ciam-ToDoList-api) para abrir a sua página de Visão geral .

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

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

    Propriedade Valor
    Nome de exibição ToDoList.Read.All
    Tipos de membros permitidos Aplicações
    Valor ToDoList.Read.All
    Descrição Permita que o aplicativo leia a lista de ToDo de cada usuário usando o 'TodoListApi'
    Deseja ativar esta função da aplicação? Mantenha-o verificado

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

    Propriedade Valor
    Nome de exibição ToDoList.ReadWrite.All
    Tipos de membros permitidos Aplicações
    Valor ToDoList.ReadWrite.All
    Descrição Permita que o aplicativo leia e escreva a lista de ToDo de cada usuário usando o 'ToDoListApi'
    Deseja ativar esta função da aplicação? Mantenha-o verificado

Configurar declarações opcionais

Você pode adicionar a declaração opcional idtyp para ajudar a API da 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 papéis para a mesma finalidade, usar a declaração idtyp é a maneira mais fácil de diferenciar um token de aplicativo de um token de aplicativo + usuário. Por exemplo, o valor dessa declaração é app quando o token é um token exclusivo de aplicativo.

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

  • Para o tipo Token selecione Access.
  • Na lista de reivindicaçõ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 do 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 utiliza .

  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 utilizadores finais 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 Atualizare, em seguida, verifique se Concedido para <o nome do inquilino> aparece sob o Status para ambos os escopos.

  9. Na lista de permissões configuradas, selecione as permissões ToDoList.Read e ToDoList.ReadWrite, uma de cada vez, e copie os URIs completos das permissões 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

  • Baixe o arquivo .zip. Extraia-o para um caminho de arquivo onde o comprimento do nome é inferior a 260 caracteres.

Instale as 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 arquivo App\authConfig.js.

  2. Encontre o espaço reservado:

    • Enter_the_Application_Id_Here e substitua-o pelo ID do aplicativo (cliente) do aplicativo cliente que você registrou anteriormente. A aplicação cliente é aquela que registaste nos pré-requisitos.
    • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, utilize contoso. Se 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 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 como parte dos pré-requisitos.

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

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

  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. A aplicação de API da Web é aquela que tu registaste anteriormente como uma parte dos pré-requisitos.
    • 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 Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, utilize contoso. Se não tiver o nome do locatário, saiba como ler os detalhes do locatário.

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 install
npm start

  3. Abra o navegador e vá para http://localhost:3000.

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

    Captura de ecrã do início de sessão numa aplicação web com node.

  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.

    Captura de ecrã de iniciar sessão numa aplicação web Node.js e chamar uma API.

Chamar API

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

    Captura de ecrã da lista de tarefas da API.

  2. Manipule a lista de to-do criando e removendo itens.

Como funciona

Você aciona uma chamada de API sempre que visualiza, adiciona ou remove uma tarefa. Sempre que acionas uma chamada de API, a aplicação web cliente adquire um token de acesso com as permissões (âmbitos) necessárias para chamar um ponto de extremidade de API. Por exemplo, para ler uma tarefa, a aplicação web cliente deve adquirir um token de acesso com a permissão/escopo ToDoList.Read.

O endpoint da API web precisa verificar se as permissões ou âmbitos no token de acesso, fornecido pela aplicação cliente, são válidos. Se o token de acesso for válido, o endpoint responderá à solicitação HTTP, caso contrário, ele responderá com um erro HTTP 401 Unauthorized.

Conteúdo relacionado

  • Last updated on