Início rápido: chamar um ASP.NET Web API protegido pela plataforma de identidade da Microsoft

  • Artigo

O início rápido a seguir usa 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 solicitar um token de acesso para acessar uma API Web.

Pré-requisitos

Clonar ou baixar o exemplo

O exemplo de código pode ser obtido 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)

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

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

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

  2. Se você tiver acesso a vários locatários, use o ícone de Configurações no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.

  3. Navegue até Identidade>Aplicativos>Registros de aplicativos e 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\appsettings.json ).

  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 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 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. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.

  2. Navegue até Identidade>Aplicativos>Registros de aplicativos 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.

Obter seus projetos

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. 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 em seu aplicativo, alterando a propriedade TenantId no arquivo appsettings.json .

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 do ASP.NET Core protegida na seguinte série de tutoriais:

Tutorial de API Web protegida