Início Rápido: Chamar uma API Web protegida pela plataforma de identidade da Microsoft

Aplica-se a: Locatários da força de trabalho Locatários externos (saiba mais)

Neste início rápido, você usará um aplicativo Web de exemplo para mostrar como proteger uma API Web ASP.NET usando a plataforma de identidade da Microsoft. O exemplo usa a MSAL (Biblioteca de Autenticação da Microsoft) para lidar com autenticação e autorização.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• Registre um novo aplicativo no Centro de administração do Microsoft Entra e registre seus identificadores na página Visão geral do aplicativo. Para obter mais informações, consulte Register an application (Registrar um aplicativo).
  • Nome: NewWebAPI1
  • Tipos de conta com suporte: Somente contas deste diretório organizacional (Locatário único)

ASP.NET

• Visual Studio 2022. Baixe o Visual Studio gratuitamente.

ASP.NET Core

• Código do Visual Studio

Expor a API

Depois que a API for registrada, você poderá configurar sua permissão definindo os escopos que a API expõe aos aplicativos cliente. Os aplicativos cliente solicitam permissão para executar operações passando um token de acesso junto com suas solicitações para a API Web protegida. A API Web executará a operação solicitada somente se o token de acesso recebido contiver os escopos necessários.

ASP.NET

1. Em Gerenciar, selecione Expor uma API>Adicionar um escopo. Aceite o URI da ID do Aplicativo proposto (api://{clientId}) selecionando Salvar e continuar e insira as seguintes informações:

   1. Para Nome do escopo, insira access_as_user.
   2. Para Quem pode consentir, verifique se a opção Administradores e usuários está selecionada.
   3. Na caixa Nome de exibição do consentimento do administrador, insira Access TodoListService as a user.
   4. Na caixa Descrição do consentimento do administrador, insira Accesses the TodoListService web API as a user.
   5. Na caixa Nome de exibição do consentimento do usuário, insira Access TodoListService as a user.
   6. Na caixa Descrição do consentimento do usuário, insira Accesses the TodoListService web API as a user.
   7. Para Estado, mantenha Habilitado.

2. Selecione Adicionar escopo.

ASP.NET Core

Expor as permissões delegadas (escopos)

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	Lista de tarefas.Ler
   Quem pode consentir	Somente administradores
   Nome de exibição do 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	Habilitado

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 do consentimento do administrador	Leia e escreva a lista de tarefas dos usuários usando "ToDoListApi"
   Descrição do consentimento do administrador	Permita que o aplicativo leia e grave na lista ToDo do usuário usando “ToDoListApi”
   Estado	Habilitado

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

Adicionar permissões de aplicativo (funções de aplicativo)

Uma API precisa publicar no mínimo uma função de aplicativo, também chamada permissão de aplicativo, para que os aplicativos clientes 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 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"
   Quer habilitar esta função de aplicativo?	Mantenha-o marcado

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 de tarefas de cada usuário usando a 'ToDoListApi'
   Quer habilitar esta função de aplicativo?	Mantenha-o marcado

Clonar ou baixar o aplicativo de exemplo

Para obter o aplicativo de exemplo, você pode cloná-lo do GitHub ou baixá-lo como um arquivo .zip.

ASP.NET

git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

• Baixe-o como um arquivo ZIP.

Dica

Para evitar erros causados por limitações de comprimento de caminho no Windows, recomendamos extrair o arquivo ou clonar o repositório em um diretório na raiz da unidade.

ASP.NET Core

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

• Baixe o arquivo .zip. Extraia-o para um caminho de arquivo em que o comprimento do nome tenha menos de 260 caracteres.

Configurar o aplicativo de exemplo

Configure o exemplo de código para corresponder à API Web registrada.

ASP.NET

1. Abra a solução no Visual Studio e abra o arquivo appsettings.json na raiz do projeto TodoListService.

2. Substitua o valor do parâmetro Enter_the_Application_Id_here pelo valor da ID do Cliente (ID do Aplicativo) do aplicativo recém-registrado no portal Registros de aplicativo nas propriedades ClientID e Audience.

Adicionar o novo escopo ao arquivo app.config

Para adicionar o novo escopo ao arquivo app.config do TodoListClient, siga estas etapas:

1. Na pasta raiz do projeto TodoListClient, abra o arquivo app.config.

2. Cole a ID do Aplicativo registrada para o projeto TodoListService no parâmetro TodoListServiceScope, substituindo a cadeia de caracteres {Enter the Application ID of your TodoListService from the app registration portal}.

Observação

Verifique se a ID do Aplicativo usa o seguinte formato: api://{TodoListService-Application-ID}/access_as_user (em que {TodoListService-Application-ID} é o GUID que representa a ID do Aplicativo para o aplicativo do TodoListService).

Registrar o aplicativo Web (TodoListClient)

Registre seu aplicativo TodoListClient em registros de aplicativo no Centro de administração do Microsoft Entra e configure o código no projeto TodoListClient. Se o cliente e o servidor forem considerados o mesmo aplicativo, você poderá reutilizar o aplicativo registrado na etapa 2. Use o mesmo aplicativo se desejar que os usuários entrem com uma conta pessoal Microsoft.

Registre o aplicativo

Para registrar o aplicativo TodoListClient, siga estas etapas:

1. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativos de Nuvem.

2. Navegue atéregistros do aplicativo> e selecione Novo registro.

3. Selecione Novo registro.

4. Quando a página Registrar um aplicativo for exibida, insira as informações de registro do aplicativo:

   1. Na seção Nome, insira um nome de aplicativo relevante que será exibido aos usuários do aplicativo (por exemplo, NativeClient-DotNet-TodoListClient).
   2. Em Tipos de conta compatíveis, selecione Contas em qualquer diretório da organização.
   3. Selecione Registrar para criar o aplicativo.

   Observação

   No arquivo app.config do projeto TodoListClient, o valor padrão de ida:Tenant é definido como common. Os valores possíveis são:

   • common: você pode se conectar usando uma conta corporativa ou de estudante ou uma conta pessoal Microsoft (porque você selecionou Contas em qualquer diretório organizacional em uma etapa anterior).
   • organizations: você pode entrar usando uma conta corporativa ou de estudante.
   • consumers: você pode entrar somente usando uma conta pessoal Microsoft.

5. Na página Visão geral do aplicativo, selecione Autenticação e conclua estas etapas para adicionar uma plataforma:

   1. Em Configurações da plataforma, selecione o botão Adicionar uma plataforma.
   2. Para Aplicativos móveis e da área de trabalho, selecione Aplicativos móveis e da área de trabalho.
   3. Em URIs de Redirecionamento, marque a caixa de seleção https://login.microsoftonline.com/common/oauth2/nativeclient.
   4. Selecione Configurar.

6. Selecione Permissões de API e conclua estas etapas para adicionar permissões:

   1. Selecione o botão Adicionar uma permissão.
   2. Selecione a guia Minhas APIs.
   3. Na lista de APIs, selecione a API AppModelv2-NativeClient-DotNet-TodoListService ou o nome que você inseriu para a API Web.
   4. Marque a caixa de seleção de permissão access_as_user caso ela ainda não esteja marcada. Use a caixa de Pesquisa, se necessário.
   5. Selecione o botão Adicionar permissões.

Configurar seu projeto

Configure seu projeto TodoListClient adicionando a ID do Aplicativo ao arquivo app.config.

1. No portal de Registros de aplicativo, na página Visão Geral, copie o valor da ID do Aplicativo (Cliente) .

2. Da pasta raiz do projeto TodoListClient, abra o arquivo app.config e cole o valor da ID do Aplicativo no parâmetro ida:ClientId.

ASP.NET Core

1. Em seu IDE, abra a pasta do projeto, ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI, que contém o exemplo.

2. Abra o arquivo appsettings.json, que contém o seguinte trecho de código:

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   Encontre os seguintes valores:

   • ClientId - O identificador do aplicativo, também conhecido como o cliente. Substitua o texto value entre aspas pela ID do aplicativo (cliente) que foi registrada anteriormente na página Visão geral do aplicativo registrado.
   • TenantId - O identificador do locatário em que o aplicativo está registrado. Substitua o texto value entre aspas pelo valor da ID do Diretório (locatário) que foi registrado anteriormente na página Visão geral do aplicativo registrado.
   • Instance - Especifica o diretório do qual a MSAL (Biblioteca de Autenticação da Microsoft) pode solicitar tokens. Substitua Enter_the_Authority_URL_Here por qualquer um dos seguintes valores, dependendo do cenário:
     • Para locatários da força de trabalho, use https://login.microsoftonline.com/ como a instância.
     • Para locatários externos, adicione uma URL de autoridade na forma de https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/

Executar o aplicativo de exemplo

ASP.NET

Inicie ambos os projetos. Para usuários do Visual Studio;

1. Clique com o botão direito na solução do Visual Studio e selecione Propriedades

2. Nas Propriedades Comuns, selecione Projeto de Inicialização e, em seguida, Vários projetos de inicialização.

3. Para ambos os projetos, escolha Iniciar como a ação

4. Verifique se o serviço TodoListService é iniciado primeiro movendo-o para a primeira posição na lista, usando a seta para cima.

Conecte-se para executar o projeto TodoListClient.

1. Pressione F5 para iniciar o projeto. A página de serviço será aberta, bem como o aplicativo da área de trabalho.

2. Em TodoListClient, no canto superior direito, selecione Entrar e conecte-se com as mesmas credenciais usadas para registrar o aplicativo ou entre como um usuário no mesmo diretório.

   Se você está se conectando pela primeira vez, talvez precise fornecer seu consentimento para a API Web TodoListService.

   Para ajudar você a acessar a API Web do TodoListService e manipular a lista de tarefas pendentes, o login também solicita um token de acesso para o escopo access_as_user.

Pré-autorize seu aplicativo cliente

Você pode permitir que os usuários de outros diretórios acessem a API Web pré-autorizando o aplicativo cliente a acessá-la. Faça isso adicionando a ID do aplicativo cliente à lista de aplicativos pré-autenticados para sua API Web. Ao adicionar um cliente pré-autenticado, você está permitindo que os usuários acessem sua API Web sem precisar fornecer consentimento.

1. No portal Registros de aplicativo, abra as propriedades do aplicativo do TodoListService.
2. Na seção Expor uma API, em Aplicativos cliente autorizados, selecione Adicionar um aplicativo cliente.
3. No campo ID do Cliente, cole a ID do Aplicativo do TodoListClient.
4. Na seção Escopos autorizados, selecione o escopo da API Web api://<Application ID>/access_as_user.
5. Selecione Adicionar aplicativo.

Execute seu projeto

1. Pressione F5 para executar o projeto. O aplicativo TodoListClient será aberto.
2. No canto superior direito, selecione Entrar e conecte-se usando uma conta pessoal Microsoft, como live.com ou hotmail.com, ou uma conta corporativa ou de estudante.

Opcional: limitar o acesso de entrada a determinados usuários

Por padrão, todas as contas pessoais, como outlook.com ou live.com, ou as contas corporativas ou de estudante de organizações integradas ao Microsoft Entra ID podem solicitar tokens e acessar a API Web.

Para especificar quem pode entrar em seu aplicativo, alterando a propriedade TenantId no arquivo appsettings.json .

ASP.NET Core

1. Execute o seguinte comando na raiz do diretório do projeto da API Web para iniciar o aplicativo:

   dotnet run
   

2. Se tudo funcionar corretamente, o terminal exibirá uma saída semelhante à seguinte:

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   Registre o número da porta no URL https://localhost:{port}.

3. Para verificar se o ponto de extremidade está protegido, atualize o URL base no seguinte comando cURL para corresponder ao que você recebeu na etapa anterior e execute o comando:

   curl -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   A resposta esperada é 401 Não autorizada.

Próximas etapas

Saiba como proteger uma API Web do ASP.NET Core com a plataforma de identidade da Microsoft.

Tutorial: Criar e proteger uma API Web do ASP.NET Core com a plataforma de identidade da Microsoft