Guia de início rápido: chame uma API da 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ê usa 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 Microsoft Authentication Library (MSAL) para manipular 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 Registrar um aplicativo.
  • Nome: NewWebAPI1
  • Tipos de conta suportados: Contas apenas neste diretório organizacional (Inquilino único)

ASP.NET

• Visual Studio 2022. Baixe o Visual Studio gratuitamente.

ASP.NET Núcleo

• Código do Visual Studio

Tornar a API acessível

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 da Web protegida. Em seguida, a API da Web executa a operação solicitada somente se o token de acesso que recebe contiver os escopos necessários.

ASP.NET

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

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

2. Selecione Adicionar escopo.

ASP.NET Núcleo

Adicionar permissões delegadas (escopos)

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 os seguintes passos:

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:

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

   Propriedade	Valor
   Nome do escopo	ListaDeTarefas.LerEscrever
   Quem pode consentir	Apenas administradores
   Nome de exibição 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

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

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

Uma API precisa publicar pelo menos uma função de aplicação para aplicativos, também chamada de permissão de aplicativo, para que as aplicações cliente obtenham um token de acesso em seu próprio nome. 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 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:

   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 e, em seguida, 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

Copie ou descarregue a aplicação 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

• Faça o download como um arquivo ZIP.

Sugestão

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 perto da raiz da unidade.

ASP.NET Núcleo

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

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

Configurar o aplicativo de exemplo

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

ASP.NET

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

2. Substitua o valor de Enter_the_Application_Id_here pelo ID do Cliente (ID da Aplicação) da aplicação que registou no portal de registos de aplicações, tanto nas propriedades ClientID como nas Audience.

Adicionar o novo escopo ao arquivo app.config

Para adicionar o novo âmbito ao ficheiro TodoListClient app.config, siga estes passos:

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

2. Cole a ID do aplicativo que você registrou para seu 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

Certifique-se de que a ID do aplicativo usa o seguinte formato: api://{TodoListService-Application-ID}/access_as_user (onde {TodoListService-Application-ID} é o GUID que representa a ID do aplicativo para seu aplicativo TodoListService).

Registrar o aplicativo Web (TodoListClient)

Registe a sua aplicação TodoListClient em Registos de aplicações no centro de administração do Microsoft Entra e, em seguida, 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. Utilize a mesma aplicação se pretender que os utilizadores iniciem sessão com uma conta Microsoft pessoal.

Registar a aplicação

Para registar a aplicação TodoListClient, siga estes passos:

1. Entre no centro de administração do Microsoft Entra como pelo menos um administrador de aplicativos na nuvem.

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

3. Selecione Novo registo.

4. Quando a página Registar uma candidatura abrir, 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, NativeClient-DotNet-TodoListClient).
   2. Em Tipos de conta suportados, selecione Contas em qualquer diretório organizacional.
   3. Selecione Registrar para criar o aplicativo.

   Observação

   No arquivo app.config do projeto Os valores possíveis são:

   • common: Você pode entrar usando uma conta corporativa ou de estudante ou uma conta pessoal da 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: Só pode iniciar sessão utilizando uma conta pessoal da 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 Aplicações móveis e de ambiente de trabalho, selecione Aplicações móveis e de ambiente de trabalho.
   3. Para Redirecionar URIs, selecione a caixa de https://login.microsoftonline.com/common/oauth2/nativeclient seleção.
   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 AppModelv2-NativeClient-DotNet-TodoListService API ou o nome que você inseriu para a API da Web.
   4. Marque a caixa de seleção access_as_user se a permissão ainda não estiver selecionada. Use a caixa Pesquisar, se necessário.
   5. Selecione o botão Adicionar permissões .

Configure seu projeto

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

1. No portal de registros de aplicativos , na página Visão geral , copie o valor da ID do aplicativo (cliente).

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

ASP.NET Núcleo

1. No 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 appsettings.json arquivo, 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 cliente. Substitua o texto value entre aspas pelo ID de Aplicação (cliente) que foi registrado anteriormente na página de Visão Geral do aplicativo registrado.
   • TenantId - O identificador do locatário onde o aplicativo está registrado. Substitua o value texto entre aspas pelo valor de 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 Biblioteca de Autenticação da Microsoft (MSAL) pode solicitar tokens. Substitua Enter_the_Authority_URL_Here por um dos seguintes valores, dependendo do cenário:
     • Para locatários de força de trabalho, use https://login.microsoftonline.com/ como exemplo.
     • Para locatários externos, adicione uma URL de autoridade na forma de https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/

Execute o aplicativo de exemplo

ASP.NET

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

1. Clique com o botão direito do mouse na solução 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 da lista, usando a seta para cima.

Entre para executar seu projeto TodoListClient.

1. Pressione F5 para iniciar os projetos. A página de serviço é aberta, assim como a aplicação de desktop.

2. No TodoListClient, no canto superior direito, selecione Entrar e entre com as mesmas credenciais que você usou para registrar seu aplicativo ou entre como um usuário no mesmo diretório.

   Se estiveres a entrar pela primeira vez, poderás ser solicitado a dar consentimento à API web TodoListService.

   Para ajudá-lo a acessar a API da Web TodoListService e manipular a lista de tarefas pendentes , o logon também solicita um token de acesso ao escopo access_as_user .

Pré-autorize a sua aplicação cliente

Você pode permitir que usuários de outros diretórios acessem sua API da Web pré-autorizando o aplicativo cliente a acessar sua API da Web. Para fazer isso, adicione a ID do aplicativo cliente à lista de aplicativos pré-autorizados para sua API da Web. Ao adicionar um cliente pré-autorizado, você está permitindo que os usuários acessem sua API da Web sem precisar fornecer consentimento.

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

Execute o seu projeto

1. Pressione F5 para executar seu projeto. A sua aplicação TodoListClient abre-se.
2. No canto superior direito, selecione Entrar e entre usando uma conta pessoal da Microsoft, como uma conta live.com ou hotmail.com ou uma conta corporativa ou de estudante.

Opcional: Limitar o acesso de iniciar sessão a determinados utilizadores

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

Para especificar quem pode iniciar sessão na sua aplicação, altere a TenantId propriedade no ficheiro appsettings.json.

ASP.NET Núcleo

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

   dotnet run
   

2. Se tudo funcionou corretamente, seu 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
   ...
   

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

3. Para verificar se o ponto de extremidade está protegido, atualize a 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óximos passos

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

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