Minimal API com Autenticação e Autorização JWT e Bearer

O que é uma Minimal API

A Minimal API é uma abordagem do ASP.NET Core que simplifica bastante a criação de APIs. Em vez de controllers, atributos de rota e classes base, você declara cada endpoint com métodos como MapGet e MapPost.

O objetivo é reduzir a quantidade de código em comparação com o ASP.NET Core MVC. Por isso, a abordagem combina muito bem com microsserviços e APIs pequenas.

Se você ainda não conhece o modelo, o artigo ASP.NET Minimal APIs apresenta a estrutura básica antes de entrarmos na segurança.

O que é o esquema Bearer

Bearer é um esquema de autenticação baseado em token, descrito na RFC 6750. O cliente envia o token de acesso no cabeçalho Authorization de cada requisição HTTP.

A palavra "bearer" significa portador. Ou seja, qualquer pessoa que possua o token consegue usar o recurso protegido, por isso o token precisa trafegar sempre por HTTPS.

Quando o servidor recebe um token correto, ele concede ao cliente os privilégios associados àquele token. Assim, o acesso acontece de forma segura e sem sessão guardada no servidor.

O que é um JWT e como ele se divide

O JWT (JSON Web Token) é um formato de token definido na RFC 7519 e muito usado para autenticação e troca segura de informações. Ele transporta dados em objetos JSON assinados digitalmente, de forma compacta e autônoma.

Um token JWT tem três partes separadas por pontos: o cabeçalho (header), a carga útil (payload) e a assinatura (signature). Cada parte segue a codificação Base64Url, que deixa o token seguro para URLs e cabeçalhos.

O cabeçalho define o tipo do token, que no caso é sempre "JWT", e o algoritmo de assinatura. Já a carga útil contém as claims, como a identidade do usuário, o e-mail e as permissões.

A assinatura nasce da combinação do cabeçalho, da carga útil e de uma chave secreta que só o servidor emissor conhece. Com isso, o servidor verifica a integridade dos dados e garante que ninguém alterou o token depois da emissão.

Vale um alerta importante: a carga útil fica apenas codificada, e não criptografada. Portanto, nunca coloque senhas ou dados sensíveis dentro das claims.

O artigo O que é JWT aprofunda esse formato.

Instalando os pacotes via NuGet

O material original adiciona dois pacotes: Microsoft.AspNetCore.Authentication e Microsoft.AspNetCore.Authentication.JwtBearer. Eles reúnem os recursos de autenticação e o handler que entende tokens JWT.

dotnet add package Microsoft.AspNetCore.Authentication
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Na prática, a infraestrutura de autenticação já faz parte do framework compartilhado do ASP.NET Core desde a versão 3.0. Por isso, o pacote realmente indispensável é o Microsoft.AspNetCore.Authentication.JwtBearer, que a documentação oficial de Minimal APIs também cita.

Com o projeto criado e os pacotes instalados, a base está pronta. Então podemos organizar a configuração e as classes de apoio.

Chave de assinatura no appsettings.json

Primeiro, adicione uma seção Jwt ao arquivo appsettings.json com um valor de sua escolha. A aplicação usa essa chave para assinar o token na emissão e para conferir a assinatura a cada requisição.

"Jwt": {
  "Key": "f3894067-e4b1-47ba-bee1-8ce3364cc44a"
}

O algoritmo HMAC SHA256 exige uma chave com pelo menos 256 bits, conforme a RFC 7518. Como o valor acima tem 36 caracteres, ele passa desse limite com folga.

Em produção, porém, a chave não deve ficar no appsettings.json versionado. Prefira o Secret Manager no desenvolvimento e um cofre de segredos, como o Azure Key Vault, nos demais ambientes.

Classes User e JwtSettings

Agora crie duas classes: User, no arquivo User.cs, e JwtSettings, no arquivo JwtSettings.cs. A primeira representa quem faz login e a segunda espelha a seção Jwt da configuração.

public class User
{
    public string Email { get; set; } = string.Empty;
    public string Name { get; set; } = string.Empty;
    public string Password { get; set; } = string.Empty;
    // Perfil padrão do exemplo; altere para testar outros acessos
    public string Role { get; set; } = "Admin";
}

public class JwtSettings
{
    public string Key { get; set; } = string.Empty;
}

Repare que a propriedade Role começa com o valor Admin. Mais adiante, você pode trocar esse valor para ver a autorização bloquear o endpoint de administrador.

Serviço que gera o token JWT na Minimal API

Além das classes de modelo, o exemplo usa duas classes estáticas: AppSettingsService, no arquivo AppSettingsService.cs, e JwtBearerService, no arquivo JwtBearerService.cs. A primeira lê a configuração e a segunda gera o token da minimal api JWT.

using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using Microsoft.IdentityModel.Tokens;

public static class AppSettingsService
{
    public static JwtSettings JwtSettings { get; }

    static AppSettingsService()
    {
        // Lê o appsettings.json uma única vez, no primeiro acesso
        IConfigurationRoot configuration = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json")
            .Build();

        JwtSettings = configuration.GetSection("Jwt").Get<JwtSettings>() ?? new JwtSettings();
    }
}

public static class JwtBearerService
{
    public static string GenerateToken(User user)
    {
        var tokenHandler = new JwtSecurityTokenHandler();
        var key = Encoding.UTF8.GetBytes(AppSettingsService.JwtSettings.Key);

        var tokenDescriptor = new SecurityTokenDescriptor
        {
            // Claims que vão para o payload do token
            Subject = new ClaimsIdentity(
            [
                new Claim(ClaimTypes.Name, user.Name),
                new Claim(ClaimTypes.Email, user.Email),
                new Claim(ClaimTypes.Role, user.Role)
            ]),
            Expires = DateTime.UtcNow.AddHours(2),
            SigningCredentials = new SigningCredentials(
                new SymmetricSecurityKey(key),
                SecurityAlgorithms.HmacSha256Signature)
        };

        var token = tokenHandler.CreateToken(tokenDescriptor);
        return tokenHandler.WriteToken(token);
    }
}

O método GenerateToken monta uma ClaimsIdentity com nome, e-mail e role do usuário. Depois, ele define a expiração em duas horas e assina o conteúdo com HMAC SHA256.

O original convertia a chave com Encoding.ASCII na geração e com Encoding.UTF8 na validação. Como a chave tem apenas caracteres ASCII, o resultado coincide, mas usar UTF8 nos dois lados evita surpresas se a chave mudar.

Também vale saber que, a partir do .NET 8, o handler de JwtBearer valida tokens com o JsonWebTokenHandler por padrão. Mesmo assim, tokens emitidos pelo JwtSecurityTokenHandler continuam compatíveis, porque ambos seguem o mesmo padrão JWT.

Registrando o middleware

Em seguida, ative os middlewares de autenticação e autorização no mesmo Program.cs, logo depois do builder.Build(). A ordem importa: primeiro a aplicação identifica o usuário e só depois decide o que ele pode acessar.

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

Segundo a documentação da Microsoft, o WebApplication registra esses middlewares automaticamente quando você chama AddAuthentication ou AddAuthorization. Ainda assim, a chamada explícita deixa a ordem visível e se torna necessária quando outros middlewares, como o CORS, precisam rodar antes.

Endpoint de autenticação

O primeiro endpoint recebe o usuário, confere as credenciais e devolve o token. Por isso, ele precisa aceitar chamadas anônimas.

app.MapPost("/v1/authenticate/", [AllowAnonymous] (User user) =>
{
    // Validação fixa apenas para fins didáticos
    if (user.Email == "user@domain.com" && user.Password == "StrongPassword")
        return Results.Ok(JwtBearerService.GenerateToken(user));

    return Results.Unauthorized();
});

A comparação com valores fixos serve só para o exemplo. Em um sistema real, você consultaria o banco de dados e compararia o hash da senha, nunca a senha em texto puro.

Endpoints anônimo, autenticado e de administrador

O segundo endpoint não exige autenticação nem autorização. Para isso, basta marcar o handler com o atributo AllowAnonymous.

app.MapGet("/v1/anonymous/", [AllowAnonymous] () => "Anonymous");

O terceiro endpoint exige apenas um token válido. Nesse caso, chamamos o método RequireAuthorization sem parâmetros.

app.MapGet("/v1/user/", () => "User").RequireAuthorization();

Por fim, o quarto endpoint exige autenticação e o perfil Admin. Para isso, combinamos o atributo Authorize com a propriedade Roles e mantemos o RequireAuthorization.

app.MapGet("/v1/admin/", [Authorize(Roles = "Admin")] () => "Administrator")
    .RequireAuthorization();

Quando o token está ausente, expirado ou com assinatura inválida, a API responde 401 Unauthorized. Já quando o token é válido, mas o usuário não tem a role exigida, a resposta passa a ser 403 Forbidden.