Guia de início rápido: chame uma API da Web protegida pela plataforma de identidade da Microsoft

Aplica-se a: Os inquilinos da força de trabalho Inquilinos externos (saber 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 da Biblioteca de Autenticação da Microsoft (MSAL) para manipular a autenticação.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• Visual Studio 2022. Baixe Visual Studio gratuitamente.

Registrar aplicativo de API da Web

Para concluir o registro, forneça um nome ao aplicativo e especifique os tipos de conta suportados. Uma vez registrado, a página Visão geral do aplicativo exibe os identificadores necessários no código-fonte do aplicativo.

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 no qual pretende registar a aplicação a partir do menu Diretórios + subscrições.

3. Navegue até Identidade>Aplicativos>Registros de aplicativos.

4. Selecione Novo registo.

5. Insira um Nome para a aplicação, como NewWebAPI1.

6. Para Tipos de conta suportados, selecione Contas somente neste diretório organizacional. Para obter informações sobre diferentes tipos de conta, selecione Ajude-me a escolher opção.

7. Selecione Registo.

   

8. O painel Visão geral do do aplicativo é exibido quando o registro é concluído. Registre o de ID do Diretório (locatário) e o ID do Aplicativo (cliente) a serem usados no código-fonte do aplicativo.

   

Observação

Os Tipos de conta suportados podem ser alterados consultando Modificar as contas suportadas por um aplicativo.

Expor uma 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 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 continuare, em seguida, insira as seguintes informações:

   1. Para 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 de exibição do consentimento do administrador, digite Access TodoListService as a user.
   4. Na caixa de 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 de descrição do consentimento do utilizador , introduza Accesses the TodoListService web API as a user.
   7. Para o Estado, mantenha Ativado.

2. Selecione Adicionar escopo.

ASP.NET CORE

1. Em Gerenciar, selecione Expor uma API > Adicionar um escopo. Aceite o URI de ID de Aplicação proposto (api://{clientId}) selecionando Guardar e continuar. O {clientId} é o valor registado na página Visão Geral. Em seguida, insira as seguintes informações:

   1. Para o nome de escopo , digite Forecast.Read.
   2. Para Quem pode consentir, verifique se a opção Administradores e utilizadores está selecionada.
   3. Na caixa Nome de exibição do consentimento do administrador, digite Read forecast data.
   4. Na caixa Descrição do consentimento do administrador, digite Allows the application to read weather forecast data.
   5. Na caixa Nome de exibição do consentimento do usuário, digite Read forecast data.
   6. Na caixa Descrição do consentimento do utilizador, introduza Allows the application to read weather forecast data.
   7. Verifique se o Estado está definido como Habilitado.

2. Selecione Adicionar escopo. Se o escopo tiver sido inserido corretamente, ele será listado no painel Expor uma API.

   

Clone ou baixe 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

• Faça o download 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 perto da raiz da unidade.

ASP.NET CORE

git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

• Baixe o arquivo .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 de appsettings.json na raiz do projeto TodoListService.

2. Substitua o valor do Enter_the_Application_Id_here pelo valor ID do Cliente (ID do Aplicativo) do aplicativo registrado no portal registros do Aplicativo nas propriedades ClientID e Audience.

Adicionar o novo escopo ao arquivo app.config

Para adicionar o novo escopo ao arquivo de app.config TodoListClient, execute estas etapas:

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 o seu aplicativo TodoListClient em Registros de Aplicativos no portal do Azure 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 Aplicações na Nuvem .

2. Navegue até Identity>Applications>Registos de aplicações e selecione Novo registo.

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. Para Tipos de conta suportados, selecione Contas em qualquer diretório organizacional.
   3. Selecione Registrar para criar o aplicativo.

   Observação

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

   • common: Pode iniciar sessão utilizando uma conta escolar ou profissional ou uma conta Microsoft pessoal (porque selecionou Contas em qualquer diretório organizacional num passo 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çãoe conclua estas etapas para adicionar uma plataforma:

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

6. Selecione permissões de APIe conclua os passos seguintes para adicionar permissões:

   1. Selecione o botão Adicionar uma permissão.
   2. Selecione o separador Minhas APIs.
   3. Na lista de APIs, selecione de API AppModelv2-NativeClient-DotNet-TodoListService ou o nome que você inseriu para a API da Web.
   4. Marque a caixa de seleção de permissão access_as_user se ainda não estiver marcada. 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 Registros de aplicativos portal, na página Visão geral do, copie o valor do ID do aplicativo (cliente).

2. Na 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. No IDE, abra a pasta do projeto ms-identity-docs-code-dotnet/web-api, que contém o exemplo.

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

   {
     "AzureAd": {
       "Instance": "https://login.microsoftonline.com/", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter the tenant ID obtained from the Microsoft Entra admin center",
       "ClientId": "Enter the client ID obtained from the Microsoft Entra admin center",
       "Scopes": "Forecast.Read"
     },
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*"
   }
   

   Encontre os seguintes key:

   • 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 texto value entre aspas por valor ID do diretório (locatário) que foi registrado anteriormente na página Visão Geral do do aplicativo registrado.

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. No Propriedades Comuns, selecione Projeto de Inicialização e 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 o aplicativo da área de trabalho.

2. No TodoListClient, no canto superior direito, selecione Entrar, depois inicie a sessão com as mesmas credenciais que você/vocês usou/usaram para registar a sua aplicação, ou inicie a sessão como um utilizador 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 login também solicita um token de acesso ao escopo access_as_user.

Pré-autorizar seu aplicativo 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 Aplicações cliente autorizadas, selecione Adicionar uma aplicação cliente.
3. Na caixa de ID do Cliente, cole a ID do Aplicativo do aplicativo TodoListClient.
4. Na seção Escopos autorizados, selecione o escopo para a api://<Application ID>/access_as_user API web.
5. Selecione Adicionar aplicativo.

Execute o seu projeto

1. Pressione F5 para executar seu projeto. Seu aplicativo TodoListClient é aberto.
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 entrar no seu aplicativo, alterando a propriedade TenantId no arquivo appsettings.json.

ASP.NET CORE

1. Execute o seguinte comando para iniciar o aplicativo:

   dotnet run
   

2. Um resultado como o seguinte exemplo é exibido:

   ...
   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: http://localhost:{port}
   ...
   

   Registre o número da porta no URL http://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 -X GET https://localhost:5001/weatherforecast -ki
   

   A resposta esperada é 401 não autorizado com resultado semelhante a:

   user@host:~$ curl -X GET https://localhost:5001/weatherforecast -ki
   HTTP/2 401
   date: Fri, 23 Sep 2023 23:34:24 GMT
   server: Kestrel
   www-authenticate: Bearer
   content-length: 0
   

Próximos passos

ASP.NET

Saiba mais criando uma API Web protegida do ASP.NET Core na seguinte série de tutoriais:

Tutorial de API web protegida

ASP.NET CORE

Prossiga para o próximo artigo para saber como chamar a API da Web protegida usando cURL.

Passo-a-passo: Chamar uma API Web ASP.NET Core com cURL