Autenticação e autorização com JWT e Bearer

O que é autenticação JWT com Bearer

Um JWT (JSON Web Token) é um token compacto dividido em três partes: cabeçalho, payload e assinatura. O cabeçalho informa o algoritmo, o payload carrega as informações do usuário e a assinatura garante que ninguém alterou o conteúdo.

Por outro lado, o Bearer define como o token trafega entre cliente e servidor. Por isso ouvimos tanto falar em "JWT Bearer": o Bearer é o meio de transporte, enquanto o JWT é o formato do token.

Na prática, a autenticação JWT funciona assim: o servidor assina o token com uma chave privada, e só quem tem essa chave consegue validar a assinatura. Se o conteúdo mudar, a assinatura deixa de bater e o token se torna inválido.

Caso queira revisar os conceitos antes de seguir, o artigo o que é JWT explica a estrutura do token com mais detalhes. Além disso, a especificação oficial está na RFC 7519.

Criando a API no ASP.NET 7

O primeiro passo funciona com qualquer template do .NET que suporte ASP.NET, como MVC, Razor Pages ou Minimal APIs. Neste exemplo, escolhi as Minimal APIs porque são mais simples e deixam o foco no que realmente interessa.

Também não vamos cobrir acesso a dados aqui. Portanto, as informações do usuário ficam simuladas, já que o foco é a autenticação JWT.

O comando abaixo cria o projeto, entra na pasta e instala o único pacote necessário, o Microsoft.AspNetCore.Authentication.JwtBearer.

dotnet new web -o JwtAspNetBlazor
cd JwtAspNetBlazor
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

O ASP.NET já traz um middleware com suporte nativo à autenticação JWT. Assim, boa parte do trabalho pesado da autenticação JWT já vem pronta dentro do framework.

// Configuration.cs
namespace JwtAspNetBlazor;

public static class Configuration
{
    // Apenas para fins didáticos, nunca deixe a chave fixa no código
    public static string PrivateKey { get; set; } = "5+IV)E2glD3xCH2rNTElZ_at9(TbG1N(E=pH)29*";
}

// Models/User.cs
namespace JwtAspNetBlazor.Models;

public record User(int Id, string Email, string Password, string[] Roles);

Como gerar o token da autenticação JWT

A geração do token na autenticação JWT fica a cargo da classe JwtSecurityTokenHandler. O pacote cuida do cabeçalho e da assinatura, então sobra para nós apenas montar o payload.

Essa classe tem dois métodos principais. O CreateToken cria o token, enquanto o WriteToken serializa o resultado na string que a API devolve.

// Cria uma instância do JwtSecurityTokenHandler
var handler = new JwtSecurityTokenHandler();

// ... montagem do tokenDescriptor

// Gera o token e depois a sua representação em string
var token = handler.CreateToken(tokenDescriptor);
var tokenString = handler.WriteToken(token);

// Converte a chave (string) para um array de bytes
var key = Encoding.ASCII.GetBytes(Configuration.PrivateKey);

var credentials = new SigningCredentials(
    new SymmetricSecurityKey(key),
    SecurityAlgorithms.HmacSha256Signature);

var tokenDescriptor = new SecurityTokenDescriptor
{
    // Tempo de vida do token, sempre em UTC
    Expires = DateTime.UtcNow.AddHours(2),
    SigningCredentials = credentials,
};

// Chave personalizada: o ASP.NET não reconhece
new Claim("UserName", "André Baltieri");
// User.Identity.Name retorna null

// Chave padrão: o ASP.NET reconhece automaticamente
new Claim(ClaimTypes.Name, "André Baltieri");
new Claim(ClaimTypes.Role, "premium");
// User.Identity.Name retorna "André Baltieri"
// User.IsInRole("premium") retorna true

private static ClaimsIdentity GenerateClaims(User user)
{
    var identity = new ClaimsIdentity();
    identity.AddClaim(new Claim(ClaimTypes.Name, user.Email));

    // Um usuário pode ter vários perfis
    foreach (var role in user.Roles)
        identity.AddClaim(new Claim(ClaimTypes.Role, role));

    return identity;
}

Token service e injeção de dependência

Para fechar a geração, reunimos a lógica da autenticação JWT em um serviço que podemos chamar sempre que precisarmos de um token. A sugestão é criar o arquivo em Services/TokenService.cs.

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

namespace JwtAspNetBlazor.Services;

public class TokenService
{
    public string Generate(User user)
    {
        var handler = new JwtSecurityTokenHandler();
        var key = Encoding.ASCII.GetBytes(Configuration.PrivateKey);
        var credentials = new SigningCredentials(
            new SymmetricSecurityKey(key),
            SecurityAlgorithms.HmacSha256Signature);

        var tokenDescriptor = new SecurityTokenDescriptor
        {
            Subject = GenerateClaims(user),
            Expires = DateTime.UtcNow.AddHours(2),
            SigningCredentials = credentials,
        };

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

    private static ClaimsIdentity GenerateClaims(User user)
    {
        var identity = new ClaimsIdentity();
        identity.AddClaim(new Claim(ClaimTypes.Name, user.Email));
        foreach (var role in user.Roles)
            identity.AddClaim(new Claim(ClaimTypes.Role, role));

        return identity;
    }
}

O método Generate recebe um User e devolve o token como string. Em seguida, registramos o serviço no container de injeção de dependência com o tempo de vida transiente, pois ele não guarda estado.

// Program.cs
using JwtAspNetBlazor.Models;
using JwtAspNetBlazor.Services;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddTransient<TokenService>();

var app = builder.Build();

// Endpoint de login simplificado, sem validação de senha
app.MapPost("/login", (User user, TokenService tokenService)
    => tokenService.Generate(user));

app.Run();

Se quiser entender melhor os tempos de vida dos serviços, o artigo sobre injeção de dependência no ASP.NET Core aprofunda o tema. Lembre também que este endpoint é só um exemplo, sem tratamento de erros nem padronização de retorno.

Testando a geração do token

Antes de proteger qualquer rota, vale confirmar que o token da autenticação JWT sai corretamente. Execute a aplicação com dotnet run e faça uma requisição POST para /login, de preferência pelo Postman.

A porta da URL vai variar na sua máquina. No corpo da requisição, selecione Raw e o formato JSON, com o conteúdo abaixo.

{
    "email": "test@balta.io",
    "roles": ["admin", "premium"]
}

Como resposta, a API devolve uma string longa no formato xxxxx.yyyyy.zzzzz. Cada bloco separado por ponto corresponde a uma das três partes do token.

Inspecionando o token no jwt.io

Com o token em mãos, cole o valor no jwt.io para ver o conteúdo decodificado.

Se tudo deu certo, você verá algo parecido com o conteúdo abaixo. Repare que o ClaimTypes.Name virou unique_name e os perfis aparecem em role.

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "unique_name": "test@balta.io",
  "role": ["admin", "premium"],
  "nbf": 1684503947,
  "exp": 1684511147,
  "iat": 1684503947
}

Configurando a autenticação JWT no pipeline

Na autenticação JWT, gerar tokens e proteger rotas são tarefas ligadas, mas distintas. Inclusive, seria possível ter uma API dedicada apenas a emitir tokens.

Agora vamos restringir o acesso usando os serviços AddAuthentication e AddAuthorization. O primeiro descobre quem o usuário é, e o segundo decide o que ele pode fazer.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication();
builder.Services.AddAuthorization();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

curl --location 'http://localhost:5049/hello' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

builder.Services
    .AddAuthentication(options =>
    {
        options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    })
    .AddJwtBearer(options =>
    {
        // Permite HTTP sem TLS (use true em produção)
        options.RequireHttpsMetadata = false;
        // Salva o token nas AuthenticationProperties
        options.SaveToken = true;
        options.TokenValidationParameters = new TokenValidationParameters
        {
            // Mesma chave usada para assinar o token
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.ASCII.GetBytes(Configuration.PrivateKey)),
            // Validações de emissor e público desligadas neste exemplo
            ValidateIssuer = false,
            ValidateAudience = false
        };
    });
builder.Services.AddAuthorization();

Restringindo rotas e obtendo o usuário logado

Com a autenticação JWT configurada, restringimos as rotas com RequireAuthorization nas Minimal APIs ou com o atributo [Authorize] em MVC e Razor Pages.

// Minimal APIs
app.MapGet("/hello", () => "Hello World")
    .RequireAuthorization();

// MVC
[Authorize]
public IActionResult Get() => Ok();

Embora o nome remeta à autorização, sem perfil, claim ou policy o recurso serve apenas como autenticação. Na prática, um acesso sem token retorna 401 Unauthorized, enquanto um token sem o requisito exigido retorna 403 Forbidden.

Imagine agora uma rota em que o usuário altera os próprios dados. Se o Id vier na URL, ele pode trocar o valor e tentar editar outra conta.

A forma mais segura é usar as informações do token da autenticação JWT, porque ninguém consegue alterá-las sem invalidar a assinatura. Como usamos ClaimTypes.Name, o HttpContext já traz o nome em User.Identity.Name.

// MVC: o controller expõe a propriedade User
[Authorize]
public IActionResult Get()
{
    var userName = User.Identity?.Name ?? string.Empty;
    return Ok(userName);
}

// Minimal APIs: injete o HttpContext ou o ClaimsPrincipal
app.MapGet("/me", (HttpContext context)
        => Results.Ok(context.User.Identity?.Name ?? string.Empty))
    .RequireAuthorization();

O usuário e o Name podem ser nulos, por isso usamos a coalescência nula. Além disso, só faz sentido ler esses dados em rotas protegidas.

Autorização com roles, claims e policies

A autenticação JWT diz quem é o usuário, mas isso não basta, já que muitas vezes precisamos classificá-lo. Por exemplo, batman@balta.io pode ser administrador, robin@balta.io apenas visualiza dados e alfred@balta.io também acessa o financeiro.

Um role é um perfil, uma string simples que qualifica o usuário. Já um claim é uma afirmação, como dizer que o usuário X possui o perfil Y.

As policies são o recurso mais poderoso, pois são trechos de código que podem exigir perfis ou até consultar dados. Contudo, elas rodam em toda chamada a uma rota protegida, então evite acessos caros ao banco ou a serviços externos.

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("Admin", policy => policy.RequireRole("manager"));
    options.AddPolicy("Employee", policy => policy.RequireRole("employee"));
});

app.MapGet("/employee", (ClaimsPrincipal user) =>
    Results.Ok(new { message = $"Authenticated as {user.Identity?.Name}" }))
    .RequireAuthorization("Employee");

app.MapGet("/manager", (ClaimsPrincipal user) =>
    Results.Ok(new { message = $"Authenticated as {user.Identity?.Name}" }))
    .RequireAuthorization("Admin");

Testando a autenticação JWT no Postman

Para facilitar os testes da autenticação JWT, o repositório do projeto no GitHub traz uma coleção do Postman com os endpoints prontos. Rode a API com dotnet run e importe o arquivo endpoints.postman_collection em File, Import.

Com isso, a coleção aparece no menu lateral. Se a sua API subir em outra porta, ajuste a URL de cada requisição.

Comece pelo login, que neste exemplo não valida senha. Guarde o token retornado, pois ele será usado nas próximas chamadas.

Erro 401 Unauthorized

Ao chamar o endpoint de funcionários sem token, recebemos 401 Unauthorized. Apesar da mensagem, esse erro indica que não estamos autenticados.

Para enviar o token, abra a aba Authorization, selecione o tipo Bearer Token e cole o valor no campo indicado.

Erro 403 Forbidden

Com o token informado, a autenticação JWT funciona e o retorno muda para 403 Forbidden. Agora estamos autenticados, mas o token não tem o perfil employee exigido pela policy.

Então geramos um novo token, desta vez com o perfil employee no corpo do login.

Por fim, atualizamos o cabeçalho da requisição com o novo token. A API responde 200 OK, já que o token agora atende à policy do endpoint.

Novidades do ASP.NET 7 para autenticação JWT

O ASP.NET Core 7 trouxe mudanças que reduzem o código de configuração. Primeiro, quando a aplicação registra um único esquema, ele passa a ser o padrão, conforme a nota de mudança da Microsoft.

Na prática, AddAuthentication().AddJwtBearer() já basta quando o JWT é o único esquema. Mesmo assim, informar o esquema de forma explícita, como fizemos, deixa a intenção clara e evita surpresas ao adicionar outros esquemas.

Além disso, o WebApplication registra os middlewares de autenticação e autorização automaticamente quando os serviços existem. Você ainda pode chamá-los de forma explícita para controlar a ordem, por exemplo depois do CORS.

Outra novidade é a ferramenta dotnet user-jwts, que cria tokens para testes locais. Ela também adiciona ao appsettings.json as opções que validam esses tokens, o que facilita testar a autenticação JWT sem um endpoint de login.

# Cria um token de desenvolvimento com o perfil admin
dotnet user-jwts create --role "admin"

Para um panorama mais amplo de proteção de APIs, veja também as boas práticas de segurança em APIs ASP.NET Core.

Conclusão sobre autenticação JWT

Neste guia, implementamos um fluxo completo de autenticação JWT no ASP.NET 7. Geramos tokens assinados, configuramos o esquema Bearer, protegemos rotas e aplicamos autorização com roles e policies.

O ponto central é separar bem as responsabilidades: autenticação diz quem é o usuário, enquanto autorização diz o que ele pode fazer. Com isso em mente, fica fácil evoluir a API para cenários mais exigentes.

Antes de ir para produção, tire a chave do código e ative a validação de emissor e público. Todo o código está no repositório do balta.io no GitHub.

FAQ

Qual a diferença entre JWT e Bearer?

No JWT temos o formato do token, com cabeçalho, payload e assinatura. Já o Bearer é o esquema que define como o token trafega, no cabeçalho Authorization.

Quando a API retorna 401 e quando retorna 403?

Um 401 indica que o usuário não está autenticado, geralmente por falta de token ou token inválido. O 403 indica que ele está autenticado, mas não atende ao perfil ou à policy da rota.

Preciso chamar UseAuthentication e UseAuthorization no .NET 7?

Não necessariamente, pois o WebApplication registra esses middlewares automaticamente quando os serviços existem. Chame de forma explícita quando precisar controlar a ordem no pipeline.

Onde devo guardar a chave privada do token?

Nunca no código ou no repositório. Use configurações por ambiente, variáveis de ambiente ou um cofre de segredos, com uma chave exclusiva para produção.

Posso ter vários perfis no mesmo token?

Sim, basta adicionar vários claims do tipo ClaimTypes.Role. O ASP.NET avalia todos eles no IsInRole e nas policies.