API da Web protegida: configuração de código

  • Artigo

Para configurar o código para sua API da Web protegida, entenda:

  • O que define APIs como protegidas.
  • Como configurar um token de portador.
  • Como validar o token.

O que define ASP.NET e ASP.NET APIs principais como protegidas?

Como os aplicativos Web, as APIs Web ASP.NET e ASP.NET Core são protegidas porque suas ações do controlador são prefixadas com o atributo [Autorizar]. As ações do controlador só podem ser chamadas se a API for chamada com uma identidade autorizada.

Considere as perguntas seguintes:

  • Somente um aplicativo pode chamar uma API da Web. Como a API sabe a identidade do aplicativo que a chama?
  • Se o aplicativo chamar a API em nome de um usuário, qual é a identidade do usuário?

Token ao portador

O token de portador definido no cabeçalho quando o aplicativo é chamado contém informações sobre a identidade do aplicativo. Ele também contém informações sobre o usuário, a menos que o aplicativo Web aceite chamadas de serviço a serviço de um aplicativo daemon.

Aqui está um exemplo de código C# que mostra um cliente chamando a API depois que ele adquire um token com a Biblioteca de Autenticação da Microsoft para .NET (MSAL.NET):

var scopes = new[] {$"api://.../access_as_user"};
var result = await app.AcquireToken(scopes)
                      .ExecuteAsync();

httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);

// Call the web API.
HttpResponseMessage response = await _httpClient.GetAsync(apiUri);

Importante

Um aplicativo cliente solicita o token de portador para a plataforma de identidade da Microsoft para a API da Web. A API é o único aplicativo que deve verificar o token e exibir as declarações que ele contém. Os aplicativos cliente nunca devem tentar inspecionar as declarações em tokens.

No futuro, a API da Web pode exigir que o token seja criptografado. Esse requisito impediria o acesso de aplicativos cliente que podem exibir tokens de acesso.

Configuração do JwtBearer

Esta seção descreve como configurar um token de portador.

Arquivo de configuração

Você precisa especificar somente TenantId se quiser aceitar tokens de acesso de um único locatário (aplicativo de linha de negócios). Caso contrário, pode ser deixado como common. Os diferentes valores podem ser:

  • Um GUID (ID do Locatário = ID do Diretório)
  • common pode ser qualquer organização e contas pessoais
  • organizations pode ser qualquer organização
  • consumers são contas pessoais da Microsoft
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Usando um URI de ID de aplicativo personalizado para uma API da Web

Se você aceitou o URI de ID de Aplicativo padrão proposto pelo portal do Azure, não precisará especificar a audiência (consulte URI de ID de Aplicativo e escopos). Caso contrário, adicione uma Audience propriedade cujo valor seja o URI da ID do Aplicativo para sua API da Web. Isso normalmente começa com api://.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common",
    "Audience": "Enter_the_Application_ID_URI_here"
  },
}

Inicialização de código

Quando um aplicativo é chamado em uma ação de controlador que contém um atributo [Autorizar], ASP.NET e ASP.NET Core extraem o token de acesso do token de portador do cabeçalho de Autorização. O token de acesso é então encaminhado para o middleware JwtPorter, que chama Microsoft IdentityModel Extensions para .NET.

Microsoft.Identity.Web

A Microsoft recomenda que você use o pacote NuGet Microsoft.Identity.Web ao desenvolver uma API da Web com o ASP.NET Core.

Microsoft.Identity.Web fornece a cola entre ASP.NET Core, o middleware de autenticação e a Microsoft Authentication Library (MSAL) para .NET. Ele permite uma experiência de desenvolvedor mais clara e robusta e aproveita o poder da plataforma de identidade da Microsoft e do Azure AD B2C.

ASP.NET para .NET 6.0

Para criar um novo projeto de API da Web que usa Microsoft.Identity.Web, use um modelo de projeto na CLI do .NET 6.0 ou Visual Studio.

CLI do núcleo Dotnet

# Create new web API that uses Microsoft.Identity.Web
dotnet new webapi --auth SingleOrg

Visual Studio - Para criar um projeto de API da Web no Visual Studio, selecione Arquivo>Novo>Projeto>ASP.NET API Web Principal.

Os modelos de projeto .NET CLI e Visual Studio criam um arquivo de Program.cs semelhante a esse trecho de código. Aviso Microsoft.Identity.Web usando diretiva e as linhas que contêm autenticação e autorização.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

app.Run();