Início Rápido: chamar uma ASP.NET Web API protegida pela plataforma de identidade da Microsoft

Seja bem-vindo! Essa provavelmente não é a página que você esperava. Enquanto trabalhamos em uma correção, este link direcionará você para o artigo certo:

Guia de Início Rápido: Chamar uma API Web ASP.NET protegida

Pedimos desculpas pela inconveniência e agradecemos sua paciência enquanto trabalhamos para resolver isso.

Neste guia de início rápido, você baixará e executará um exemplo de código que demonstra como proteger uma ASP.NET Web API restringindo o acesso aos recursos dela somente às contas autorizadas. O exemplo dá suporte à autorização de contas Microsoft pessoais e contas em qualquer organização do Microsoft Entra.

O artigo também usa um aplicativo do WPF (Windows Presentation Foundation) para demonstrar como você pode solicitar um token de acesso para acessar uma API Web.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• Visual Studio 2017 ou 2019. Baixe o Visual Studio gratuitamente.

Clonar ou baixar o exemplo

Você pode obter o exemplo de duas maneiras:

• Clone-o no Shell ou na linha de comando:

  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 do caminho no Windows, é recomendável extrair os arquivos em um diretório próximo à raiz da unidade.

Registrar a API Web (TodoListService)

Registre sua API Web em Registros de aplicativo no portal do Azure.

1. Entre no centro de administração do Microsoft Entra como, no mínimo, um Administrador de aAplicativos.

2. Navegue até Identidade>Aplicativos>Registros do aplicativo.

3. Selecione Novo registro.

4. Insira um Nome para seu aplicativo, por exemplo, AppModelv2-NativeClient-DotNet-TodoListService. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.

5. Em Tipos de conta compatíveis, selecione Contas em qualquer diretório da organização.

6. Selecione Registrar para criar o aplicativo.

7. Na página Visão Geral do aplicativo, localize o valor da ID do aplicativo (cliente) e registre-o para uso posterior. Você precisará dele para definir o arquivo de configuração do Visual Studio para este projeto (ou seja, ClientId no arquivo TodoListService\Web.config).

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

9. Selecione Adicionar escopo.

Configurar o projeto de serviço

Configure o projeto de serviço para que ele corresponda à API Web registrada.

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

2. Substitua o valor do parâmetro ida:ClientId pelo valor da ID do Cliente (ID do Aplicativo) do aplicativo recém-registrado no portal Registros de aplicativo.

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 recém-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 o aplicativo TodoListClient em Registros de aplicativo no portal do Azure 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. Vá para o portal Registros de aplicativo da plataforma de identidade da Microsoft para desenvolvedores.

2. Selecione Novo registro.

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

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

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

Obter seus projetos

Inicie ambos os projetos. Se você estiver usando o Visual Studio:

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

2. Em Propriedades Comuns, selecione Projeto de inicialização, e em 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 serviço é 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ê estiver entrando pela primeira vez, talvez seja solicitado a consentir com a API Web do TodoListService.

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

Pré-autorizar 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. Você faz isso adicionando a ID do Aplicativo Cliente à lista de aplicativos previamente autorizados para sua API Web. Ao adicionar um cliente previamente autorizado, você está permitindo que usuários acessem a API Web sem a necessidade de 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. Escolha Adicionar aplicativo.

Execute seu projeto

1. Pressione F5 para executar o projeto. Seu 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 no aplicativo, use uma das seguintes opções:

Opção 1: limitar o acesso a uma organização (locatário único)

Você pode limitar o acesso de entrada ao seu aplicativo para contas de usuário que estão em um único locatário do Microsoft Entra, incluindo contas de convidado desse locatário. Esse cenário é comum para aplicativos de linha de negócios.

1. Abra o arquivo App_Start\Startup.Auth e altere o valor do ponto de extremidade de metadados que é passado em OpenIdConnectSecurityTokenProvider para https://login.microsoftonline.com/{Tenant ID}/v2.0/.well-known/openid-configuration. Você também pode usar o nome do locatário, como contoso.onmicrosoft.com.
2. No mesmo arquivo, defina a propriedade ValidIssuer em TokenValidationParameters como https://sts.windows.net/{Tenant ID}/ e o argumento ValidateIssuer como true.

Opção 2: Usar um método personalizado para validar emissores

É possível implementar um método personalizado para validar emissores usando o parâmetro IssuerValidator. Para obter mais informações sobre como usar esse parâmetro, confira a classe TokenValidationParameters.

Ajuda e suporte

Se precisar de ajuda, quiser relatar um problema ou desejar saber mais sobre as opções de suporte, confira Ajuda e suporte para desenvolvedores.

Próximas etapas

Saiba mais criando uma API web protegida do ASP.NET Core na série de tutoriais a seguir:

Tutorial de API web protegida