Partilhar via

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

  • Artigo

O guia de início rápido a seguir usa 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 de contas em qualquer organização Microsoft Entra.

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

Pré-requisitos

Clone ou faça o download do exemplo

O exemplo de código pode ser obtido de duas maneiras:

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.

Registrar a API da Web (TodoListService)

Registe a sua API Web em Registos de Aplicação no portal do Azure.

  1. Entre no centro de administração do Microsoft Entra com pelo menos as credenciais de um Administrador de Aplicações na Cloud.

  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é Identity>Applications>Registos de aplicações e 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. Para Tipos de conta suportados, selecione Contas em qualquer diretório organizacional.

  6. Selecione Registrar para criar o aplicativo.

  7. Na página Visão Geral da aplicação, procure o valor ID de Aplicação (cliente) e registe-o para uso posterior. Você precisará dele para configurar o arquivo de configuração do Visual Studio para este projeto (ou seja, ClientId no\appsettings.jsTodoListService em arquivo).

  8. 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 utilizadores 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 de 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 State, 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 de appsettings.json na raiz do projeto TodoListService.

  2. Substitua o valor do Enter_the_Application_Id_here pelo valor do ID de Cliente (ID da Aplicação) da aplicação que registou no portal de Registos de Aplicações , tanto nas propriedades ClientID como em 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 a sua aplicação TodoListClient nos Registos de Aplicações no portal 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. Inicie sessão no centro de administração do Microsoft Entra como pelo menos um Administrador de Aplicações na Cloud.

  2. Navegue até Identity>Aplicações>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 Registo para criar a aplicação.

    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 de 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 desktop, selecione Aplicações móveis e de desktop.
    3. Para Redirecionar URIs, marque a caixa de seleção https://login.microsoftonline.com/common/oauth2/nativeclient.
    4. Selecionar Configurar.

  6. Selecione permissões de APIe 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 de API AppModelv2-NativeClient-DotNet-TodoListService ou o nome que você inseriu para a API da Web.
    4. Marque a caixa de seleção da permissão access_as_user caso ainda não esteja 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.

Execute seus projetos

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 Arranque e depois Vários Projetos de Arranque.

  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 Entrare, em seguida, entre com as mesmas credenciais que utilizou para registar a sua aplicação ou entre como um utilizador no mesmo diretório.

    Se estiveres a entrar pela primeira vez, poder-te-á ser pedido para consentires 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 Registos das aplicações, abra as propriedades da aplicação TodoListService.
  2. Na secçã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 da Aplicação do app TodoListClient.
  4. Na secção Escopos autorizados, selecione o escopo da API da web api://<Application ID>/access_as_user.
  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 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, alterando a propriedade TenantId no arquivo appsettings.json.

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