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

  • Artigo

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

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

O que define as APIs ASP.NET e ASP.NET Core como protegidas?

Assim como os aplicativos Web, as APIs Web do ASP.NET e ASP.NET Core são protegidas porque suas ações de controlador são prefixadas com o atributo [Authorize]. As ações do controlador poderão ser chamadas somente se a API for chamada com uma identidade autorizada.

Considere as seguintes perguntas:

  • 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 de 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 em C# que mostra um cliente que chama a API depois de adquirir 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 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 Web pode exigir que o token seja criptografado. Esse requisito impediria o acesso para 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 o TenantId único se quiser aceitar tokens de acesso de um único locatário (aplicativo de linha de negócios). Caso contrário, ele poderá ser deixado como common. Os valores diferentes podem ser:

  • Uma GUID (ID do locatário = ID do diretório)
  • common pode ser qualquer organização e contas pessoais
  • organizations pode ser qualquer organização
  • consumerssã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 do Aplicativo personalizado para uma API Web

Se você aceitou o URI da ID do aplicativo padrão proposto pelo portal do Azure, não é necessário especificar o público. Confira Escopos e URI da ID do aplicativo. Caso contrário, adicione uma propriedade Audience cujo valor seja o URI da ID do aplicativo para a sua API Web. Normalmente, isso 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 do código

Quando um aplicativo é chamado em uma ação do controlador que contém um atributo [Authorize] , 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 é encaminhado para o middleware JwtBearer, que chama as extensões Microsoft IdentityModel para .NET.

Microsoft.Identity.Web

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

O Microsoft.Identity.Web fornece a cola entre ASP.NET Core, o middleware de autenticação e a MSAL (biblioteca de autenticação da Microsoft) 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 projeto da API Web que usa o Microsoft.Identity.Web, use um modelo de projeto na CLI do .NET 6.0 ou no Visual Studio.

CLI do Dotnet core

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

Visual Studio – Para criar um projeto de API Web no Visual Studio, selecione Arquivo>Novo>Projeto>ASP.NET Core Web API.

Os modelos de projeto da CLI do .NET e do Visual Studio criam um arquivo Program.cs semelhante para este snippet de código. Observe a diretiva usando Microsoft.Identity.Web 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();