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

  • Artigo

Bem-vindo! Esta provavelmente não é a página que você estava esperando. Enquanto trabalhamos em uma correção, este link deve levá-lo ao artigo certo:

Guia de início rápido: chamar uma API da Web de ASP.NET protegida

Pedimos desculpas pelo inconveniente e agradecemos a sua paciência enquanto trabalhamos para resolver este problema.

Neste início rápido, você baixa e executa um exemplo de código que demonstra como proteger uma API da Web ASP.NET restringindo o acesso a seus recursos apenas a contas autorizadas. O exemplo oferece suporte à autorização de contas pessoais da Microsoft e contas em qualquer organização do Microsoft Entra.

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

Pré-requisitos

Clone ou faça o download do exemplo

Você pode obter a amostra de duas maneiras:

  • Clone a partir do seu shell ou linha de comando:

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

  • Faça o download como um arquivo ZIP.

Gorjeta

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.

Registrar a API da Web (TodoListService)

Registe a sua API Web em Registos de aplicações no portal do Azure.

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

  2. Navegue até Registros do aplicativo Identity>Applications>.

  3. Selecione Novo registo.

  4. Introduza um Nome para a sua aplicação, 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 suportados, selecione Contas em qualquer diretório organizacional.

  6. Selecione Registar para criar a aplicação.

  7. Na página Visão geral do aplicativo, procure o valor da ID do aplicativo (cliente) e registre-o para uso posterior. Você precisará dele para configurar 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 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.

  9. Selecione Adicionar escopo.

Configurar o projeto de serviço

Configure o projeto de serviço para corresponder à API da Web registrada.

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

  2. Substitua ida:ClientId o valor do parâmetro pelo valor da ID do Cliente (ID do Aplicativo) do aplicativo que você registrou no portal de registros do aplicativo.

Adicione o novo escopo ao arquivo app.config

Para adicionar o novo escopo ao arquivo app.config TodoListClient, siga 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 TodoListServiceScope parâmetro, substituindo a {Enter the Application ID of your TodoListService from the app registration portal} cadeia de caracteres.

Nota

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)

Registre seu 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. 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. Vá para a plataforma de identidade da Microsoft para desenvolvedores Portal de registros de aplicativos.

  2. Selecione Novo registo.

  3. 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 Registar para criar a aplicação.

    Nota

    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 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: Você pode entrar somente usando uma conta pessoal da 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 Aplicações móveis e de ambiente de trabalho, selecione Aplicações móveis e de ambiente de trabalho.
    3. Para Redirecionar URIs, marque a caixa de https://login.microsoftonline.com/common/oauth2/nativeclient seleção.
    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 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 permissão 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 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.

Execute seus projetos

Inicie ambos os projetos. Se você estiver usando o 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 o aplicativo da área de trabalho.

  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 você estiver entrando pela primeira vez, poderá ser solicitado a consentir com a API da 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 registros de aplicativos, abra as propriedades do seu aplicativo 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.

Executar o 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 início de 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, use uma das seguintes opções:

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

Pode limitar o acesso de início de sessão à sua aplicação a contas de utilizador que estejam num único inquilino do Microsoft Entra, incluindo contas de convidado desse inquilino. 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 para https://login.microsoftonline.com/{Tenant ID}/v2.0/.well-known/openid-configurationo OpenIdConnectSecurityTokenProvider . Você também pode usar o nome do locatário, como contoso.onmicrosoft.com.
  2. No mesmo arquivo, defina a ValidIssuerTokenValidationParameters propriedade no para https://sts.windows.net/{Tenant ID}/e defina o ValidateIssuer argumento como true.

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

Você pode implementar um método personalizado para validar emissores usando o IssuerValidator parâmetro. Para obter mais informações sobre esse parâmetro, consulte TokenValidationParameters classe.

Ajuda e suporte

Se precisar de ajuda, quiser comunicar um problema ou quiser saber mais sobre as suas opções de suporte, consulte Ajuda e suporte para programadores.

Próximos passos

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

Tutorial da API da Web protegida