Guia de início rápido: Proteger uma API Web com a plataforma de identidade da Microsoft

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 Azure AD (Azure Active Directory).

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

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 portal do Azure.

  2. Se você tem acesso a vários locatários, use o filtro Diretório + assinatura no menu superior para selecionar o locatário no qual você deseja registrar um aplicativo.

  3. Encontre e selecione Azure Active Directory.

  4. Em Gerenciar, selecione Registros de aplicativo>Novo registro.

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

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

  7. Selecione Registrar para criar o aplicativo.

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

  9. 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.
  10. 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 Azure AD 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 restringir o acesso de entrada ao aplicativo às contas de usuário que estejam em um locatário do Azure AD, incluindo as contas de convidado daquele 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 sobre o cenário de API Web protegida compatível com a plataforma de identidade da Microsoft.

Neste guia de início rápido, você baixará um exemplo de código da API Web ASP.NET Core e examinará como ele restringe o acesso aos recursos somente às contas autorizadas. O exemplo dá suporte à autorização de contas Microsoft pessoais e contas em qualquer organização do Azure AD (Azure Active Directory).

Pré-requisitos

Etapa 1: Registrar o aplicativo

Primeiro, registre a API Web no seu locatário do Azure AD e adicione um escopo seguindo estas etapas:

  1. Entre no portal do Azure.
  2. Se você tem acesso a vários locatários, use o filtro Diretórios + assinaturas no menu superior para mudar para o locatário no qual você deseja registrar o aplicativo.
  3. Pesquise Azure Active Directory e selecione-o.
  4. Em Gerenciar, selecione Registros de aplicativo>Novo registro.
  5. Em Nome, insira um nome para o seu aplicativo. Por exemplo, insira AspNetCoreWebApi-Quickstart. Os usuários do seu aplicativo verão esse nome e você pode alterá-lo mais tarde.
  6. Selecione Registrar.
  7. Em Gerenciar, selecione Expor uma API>Adicionar um escopo. Em URI da ID do Aplicativo, aceite o padrão selecionando Salvar e continuar e insira os seguintes detalhes:
    • Nome do escopo: access_as_user
    • Quem pode consentir? : Administradores e usuários
    • Nome de exibição de consentimento do administrador: Access AspNetCoreWebApi-Quickstart
    • Descrição do consentimento do administrador:Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
    • Nome de exibição do consentimento do usuário: Access AspNetCoreWebApi-Quickstart
    • Descrição do consentimento do usuário: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
    • Estado: Enabled
  8. Selecione Adicionar escopo para concluir a adição do escopo.

Etapa 2: Baixar o projeto do ASP.NET Core

Baixe a solução do ASP.NET Core no GitHub.

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.

Etapa 3: Configurar o projeto do ASP.NET Core

Nesta etapa, configure o código de exemplo para trabalhar com o registro do aplicativo criado anteriormente.

  1. Extraia o arquivo .zip para uma pasta próxima à raiz da unidade. Por exemplo, extraia no C:\Azure-Samples.

    É recomendável extrair os arquivos em um diretório próximo à raiz da unidade para evitar erros causados por limitações de comprimento do caminho no Windows.

  2. Abra a solução na pasta webapi no editor de códigos.

  3. Abra o arquivo appsettings.json e modifique o seguinte código:

    "ClientId": "Enter_the_Application_Id_here",
    "TenantId": "Enter_the_Tenant_Info_Here"
    
    • Substitua Enter_the_Application_Id_here pela ID do aplicativo (cliente) referente ao aplicativo que você registrou no portal do Azure. Encontre a ID do aplicativo (cliente) na página Visão geral do aplicativo.
    • Substitua Enter_the_Tenant_Info_Here por um dos seguintes:
      • Se o aplicativo dá suporte às Contas somente neste diretório organizacional, substitua esse valor pela ID de diretório (locatário) (um GUID) ou pelo nome do locatário (por exemplo, contoso.onmicrosoft.com). Encontre a ID de diretório (locatário) na página Visão geral do aplicativo.
      • Se o aplicativo der suporte para Contas em qualquer diretório organizacional, substitua esse valor por organizations.
      • Se o aplicativo der suporte a Todos os usuários de contas Microsoft, defina esse valor como common.

Para este guia de início rápido, não altere nenhum outro valor no arquivo appsettings.json.

Como o exemplo funciona

A API Web recebe um token de um aplicativo cliente, e o código na API Web valida o token. Esse cenário é explicado mais detalhadamente em Cenário: API Web protegida.

Classe de inicialização

O middleware Microsoft.AspNetCore.Authentication usa a classe Startup que é executada quando o processo de hospedagem é iniciado. No método ConfigureServices, o método de extensão AddMicrosoftIdentityWebApi fornecido pelo Microsoft.Identity.Web é chamado.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

O método AddAuthentication() configura o serviço para adicionar a autenticação baseada em JwtBearer.

A linha que contém .AddMicrosoftIdentityWebApi adiciona a autorização da plataforma de identidade da Microsoft à API Web. Em seguida, ela é configurada para validar os tokens de acesso emitidos pela plataforma de identidade da Microsoft com base nas informações na seção AzureAD do arquivo de configuração appsettings.json:

chave appsettings.json Descrição
ClientId ID do aplicativo (cliente) referente ao aplicativo registrado no portal do Azure.
Instance Ponto de extremidade do STS (serviço de token de segurança) para o usuário se autenticar. Esse valor geralmente é https://login.microsoftonline.com/, indicando a nuvem pública do Azure.
TenantId Nome do seu locatário ou sua ID de locatário (um GUID) ou common para conectar usuários que tenham contas corporativas ou de estudante ou contas pessoais Microsoft.

O método Configure() contém dois métodos importantes, app.UseAuthentication() e app.UseAuthorization(), que habilitam a funcionalidade nomeada:

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

Como proteger um controlador, um método do controlador ou uma página Razor

Você pode proteger um controlador ou métodos do controlador usando o atributo [Authorize]. Esse atributo restringe o acesso ao controlador ou aos métodos permitindo apenas usuários autenticados. Um desafio de autenticação poderá ser iniciado para acessar o controlador se um usuário não estiver autenticado.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

Validação do escopo no controlador

O código na API verifica se os escopos necessários estão no token usando HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);:

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

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

O repositório GitHub que contém este exemplo de código ASP.NET Core da API Web inclui instruções e mais exemplos de código que mostram como:

  • Adicionar a autenticação a uma nova API Web ASP.NET Core.
  • Chamar a API Web em um aplicativo da área de trabalho.
  • Chamar APIs downstream como o Microsoft Graph e outras APIs da Microsoft.