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

O início rápido a seguir usa um exemplo de código da API Web ASP.NET Core para demonstrar como restringir o acesso de recursos a contas autorizadas. O exemplo dá suporte à autorização de contas e contas Microsoft pessoais em qualquer organização do Microsoft Entra.

Pré-requisitos

• Conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• Locatário do Microsoft Entra
• Um requisito mínimo do SDK 6.0 do .NET
• Visual Studio 2022 ou Visual Studio Code

Etapa 1: Registrar o aplicativo

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

1. Entre no Centro de administração do Microsoft Entra pelo menos como um Administrador de Aplicativo.
2. Navegue para Entra ID>registros do aplicativo.
3. Selecione Novo registro.
4. Em Nome, insira um nome para o aplicativo. Por exemplo, insira AspNetCoreWebApi-Quickstart. Os usuários do aplicativo verão esse nome e poderão ser alterados posteriormente.
5. Selecione Registrar.
6. 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: Habilitado

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

O exemplo de código atualmente tem como destino o ASP.NET Core 3.1. O exemplo pode ser atualizado para usar o .NET Core 6.0 e é abordado nas seguintes etapas: Atualizar o código de exemplo para ASP.NET Core 6.0. Este início rápido será preterido em um futuro próximo e será atualizado para usar o .NET 6.0.

Etapa 3: Configurar o projeto do ASP.NET Core

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

1. Extraia o arquivo .zip para uma pasta local próxima à raiz do disco para evitar erros causados por limitações de comprimento de caminho no Windows. Por exemplo, extraia em C:\Azure-Samples.

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

3. Em appsettings.json, substitua os valores de ClientId e TenantId.

   "ClientId": "Enter_the_Application_Id_here",
   "TenantId": "Enter_the_Tenant_Info_Here"
   

   • Enter_the_Application_Id_Here é a ID de cliente do aplicativo que você registrou.
   • 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). A ID de diretório (locatário) pode ser encontrada na página Visão geral do aplicativo.
     • Se o aplicativo der suporte a 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.

Etapa 4: atualizar o código de exemplo para ASP.NET Core 6.0

Para atualizar o exemplo de código para ASP.NET Core 6.0, siga estas etapas:

1. Abra webapi.csproj
2. Remova a seguinte linha:

<TargetFramework>netcoreapp3.1</TargetFramework>

1. Adicione a seguinte linha em seu lugar:

<TargetFramework>netcoreapp6.0</TargetFramework>

Esta etapa garantirá que o exemplo esteja voltado para a estrutura do .NET Core 6.0.

Etapa 5: executar o exemplo

1. Abra um terminal e altere o diretório para a pasta do projeto.

   cd webapi
   

2. Execute o seguinte comando para criar a solução:

dotnet run

Se o build tiver sido bem-sucedido, a seguinte saída será exibida:

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: https://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

Como o exemplo funciona

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:

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

Um controlador ou métodos do controlador podem ser protegidos pelo uso do 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 a seguir contém as instruções de exemplo de código da API Web do ASP.NET Core e mais exemplos que mostram como obter o seguinte:

• Adicionar a autenticação a uma nova API Web ASP.NET Core.
• Chame a API da Web a partir de um aplicativo de desktop.
• Chamar APIs downstream como o Microsoft Graph e outras APIs da Microsoft.