Skip to content

8. Autenticação e autorização

Duas questões distintas surgem a cada requisição:

  • Quem é o usuário? É a autenticação: o usuário se identificou com um nome de usuário e uma senha, e cada requisição seguinte precisa provar que vem dele;
  • O usuário tem permissão para acessar esta página? É a autorização: no estudo de caso, apenas um usuário com o papel ADMIN gerencia médicos e clientes.

Como o servidor não mantém estado (Capítulo 6), a prova de identidade deve ser incluída em cada requisição. Usa-se um token JWT ([JSON Web Token]): após o login, o servidor gera um token contendo a identidade do usuário e o assina com uma chave secreta. O token é armazenado em um cookie; o navegador o reenvia a cada requisição; o servidor verifica a assinatura. O usuário pode ler seu token, mas não pode modificá-lo: qualquer modificação invalida a assinatura.

[ASP.NET Core] distingue claramente as duas questões:

  • a autenticação é tratada por um middleware ([UseAuthentication]) e por um esquema de autenticação: neste caso, o esquema [JwtBearer], fornecido pelo pacote [NuGet] [Microsoft.AspNetCore.Authentication.JwtBearer] . A cada requisição, ele procura um token, o verifica e dele deriva o usuário, [HttpContext.User];
  • a autorização é tratada pelo atributo [[Authorize]], verificado pelo middleware [UseAuthorization]: ele compara as exigências da action com o que se sabe sobre o usuário.

Os exemplos deste capítulo usam dois pacotes [NuGet]: [Microsoft.AspNetCore.Authentication.JwtBearer] e [BCrypt.Net-Next] (hash de senhas). Eles são declarados no arquivo de projeto; o comando [dotnet build] (ou [dotnet run]) os baixa de nuget.org durante a primeira compilação: é necessária, portanto, uma conexão com a Internet.

8.1. Exemplo 25: login, token, página protegida

25-jwt/
├── Auth/
│   ├── AuthService.cs
│   └── UsersService.cs
├── Controllers/
│   ├── AuthController.cs
│   └── ProfileController.cs
├── Views/
│   ├── Auth/
│   │   └── Login.cshtml
│   ├── Profile/
│   │   └── Profile.cshtml
│   ├── Shared/
│   │   └── _Layout.cshtml
│   ├── _ViewImports.cshtml
│   └── _ViewStart.cshtml
├── appsettings.json
├── Example25.csproj
└── Program.cs

O arquivo [Example25.csproj]:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <!-- autenticação por token JWT (verificação do token) -->
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
    <!-- hash de senhas (bcrypt) -->
    <PackageReference Include="BCrypt.Net-Next" Version="4.0.3" />
  </ItemGroup>

</Project>
  • Linhas 5–7: os pacotes [NuGet] usados e suas versões. Os elementos comuns a todos os exemplos (versão do [.NET]...) ficam no arquivo [Directory.Build.props] da pasta [examples].

O arquivo [appsettings.json]:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Jwt": {
    "Secret": "a-secret-key-of-at-least-32-characters-for-example-25",
    "DurationMinutes": 60
  }
}
  • Linhas 9–11: uma seção de configuração específica da aplicação: a chave usada para assinar os tokens e seu tempo de vida. Quem conhece a chave pode gerar tokens válidos: em produção, ela não é armazenada em um arquivo de projeto; em vez disso, é fornecida por uma variável de ambiente ([Jwt__Secret]) ou por um cofre de segredos. O algoritmo utilizado (HMAC-SHA256) exige uma chave de pelo menos 32 bytes.

O arquivo [Auth/UsersService.cs]:

namespace Example25.Auth;

public record User(string Login, string Name, string Role, string PasswordHash);

// os usuários, em memória (o próximo capítulo os colocará em um banco de dados)
public class UsersService
{
    private readonly List<User> users =
    [
        // uma senha NUNCA é guardada, apenas seu hash
        Create("marie", "Marie Pélissier", "USER", "marie"),
        Create("admin", "Administrator", "ADMIN", "admin"),
    ];

    public User? Find(string login) =>
        users.Find(u => u.Login == login);

    // bcrypt, com custo 10: 2^10 rodadas de cálculo, deliberadamente lento
    private static User Create(string login, string name, string role, string password) =>
        new(login, name, role, BCrypt.Net.BCrypt.HashPassword(password, 10));
}
  • linha 3: um usuário, com seu papel;
  • linhas 10–12: uma senha nunca é armazenada; apenas seu hash é mantido — uma impressão digital calculada por uma função unidirecional. É possível verificar se uma senha corresponde a uma impressão digital, mas não recuperar a senha a partir da impressão digital;
  • linhas 19–20: [BCrypt.Net.BCrypt.HashPassword(password, 10)] calcula o hash usando o algoritmo [bcrypt]. O 10 representa o “custo”: o [bcrypt] é intencionalmente lento (2¹⁰ ciclos de cálculo) para desencorajar quem tente milhões de senhas. Dois hashes da mesma senha são diferentes (um “salt” aleatório é adicionado): [BCrypt.Verify] é responsável por verificá-los.

O arquivo [Auth/AuthService.cs]:

using System.Text;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;

namespace Example25.Auth;

public class AuthService(UsersService users, IConfiguration configuration)
{
    // o nome do cookie que carrega o token
    public const string Cookie = "token";

    // a chave que assina os tokens, lida de appsettings.json (seção Jwt)
    public static SymmetricSecurityKey Key(IConfiguration configuration) =>
        new(Encoding.UTF8.GetBytes(configuration["Jwt:Secret"]!));

    // null se o login for desconhecido ou a senha estiver errada
    public User? Validate(string? login, string? password)
    {
        var user = users.Find(login ?? "");
        if (user is null || password is null)
        {
            return null;
        }
        return BCrypt.Net.BCrypt.Verify(password, user.PasswordHash) ? user : null;
    }

    // o token JWT do usuário, assinado com a chave secreta
    public string CreateToken(User user)
    {
        var descriptor = new SecurityTokenDescriptor
        {
            // o conteúdo do token: as "claims" (declarações sobre o usuário)
            Claims = new Dictionary<string, object>
            {
                ["sub"] = user.Login,
                ["name"] = user.Name,
                ["role"] = user.Role,
            },
            Expires = DateTime.UtcNow.AddMinutes(configuration.GetValue<int>("Jwt:DurationMinutes")),
            SigningCredentials = new SigningCredentials(Key(configuration), SecurityAlgorithms.HmacSha256),
        };
        return new JsonWebTokenHandler().CreateToken(descriptor);
    }
}

Vamos detalhar este código:

  • linha 10: o nome do cookie que transporta o token;
  • Linhas 13–14: a chave de assinatura, gerada a partir do texto de [appsettings.json]. [IConfiguration] dá acesso à configuração; ["Jwt:Secret"] designa a propriedade [Secret] da seção [Jwt]. A mesma chave é usada para assinar e verificar os tokens (algoritmo simétrico);
  • linhas 17–24: verificação do nome de usuário e da senha;
  • linhas 33–37: o conteúdo do token, as claims (declarações sobre o usuário). [sub] ([subject]) é o nome convencional do identificador do usuário. Incluímos o que as páginas precisam (nome, papel) para não ter de consultar o banco de dados a cada requisição;
  • linha 39: a data de expiração do token;
  • linha 40: a chave e o algoritmo de assinatura;
  • linha 42: a classe [JsonWebTokenHandler] (pacote [Microsoft.IdentityModel.JsonWebTokens], fornecido pelo [JwtBearer]) gera o token assinado.

O arquivo [Program.cs]:

using System.Text.Encodings.Web;
using System.Text.Unicode;
using Example25.Auth;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Extensions.FileProviders;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));
builder.Services.AddSingleton<UsersService>();
builder.Services.AddSingleton<AuthService>();

// autenticação: um token JWT, verificado a cada requisição
builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.MapInboundClaims = false; // mantém os nomes das claims como estão ("sub", "role"...)
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = AuthService.Key(builder.Configuration), // a assinatura deve ser a nossa
            ValidateLifetime = true,                                   // o token não deve estar expirado
            ValidateIssuer = false,
            ValidateAudience = false,
            NameClaimType = "name", // User.Identity.Name
            RoleClaimType = "role", // [Authorize(Roles = ...)], User.IsInRole(...)
        };
        options.Events = new JwtBearerEvents
        {
            // 1. o token é lido do cookie (e não do cabeçalho Authorization)
            OnMessageReceived = context =>
            {
                context.Token = context.Request.Cookies[AuthService.Cookie];
                return Task.CompletedTask;
            },
            // 2. página protegida sem token válido: direto para a página de login
            OnChallenge = context =>
            {
                context.HandleResponse(); // construímos a resposta nós mesmos (sem 401)
                context.Response.Redirect("/login");
                return Task.CompletedTask;
            },
        };
    });
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(Path.GetFullPath(Path.Combine(builder.Environment.ContentRootPath, "..", "common", "bootstrap"))),
    RequestPath = "/bootstrap",
});
app.UseAuthentication(); // quem é? -> HttpContext.User
app.UseAuthorization();  // é permitido? -> [Authorize]

app.MapControllers();
app.Run();

Vamos comentar este código:

  • linhas 16–17: declaramos o esquema de autenticação [JwtBearer] e o definimos como esquema padrão;
  • linha 19: por padrão, o [JwtBearer] renomeia certas claims usando nomes longos herdados de tecnologias da Microsoft ([role] se tornaria [http://schemas.microsoft.com/ws/2008/06/identity/claims/role]). Mantemos os nomes do token;
  • Linhas 20–26: as verificações feitas em cada token: a assinatura (com a nossa chave) e a data de expiração. Nossos tokens não especificam nem o emissor ([issuer]) nem o destinatário ([audience]), portanto não os verificamos;
  • linhas 27–28: qual claim contém o nome do usuário ([User.Identity.Name]) e qual contém seu papel ([[Authorize(Roles = ...)]], [User.IsInRole(...)]);
  • linhas 33–36: os eventos de [JwtBearer] permitem personalizar seu comportamento. Por padrão, ele procura o token no cabeçalho [Authorization: Bearer ...] da requisição: é assim que funciona um cliente [JavaScript] ou um aplicativo móvel. Um navegador não adiciona esse cabeçalho por conta própria: o token é recuperado do cookie;
  • linhas 39–42: o desafio (challenge) ocorre quando uma página protegida é solicitada sem um token válido. Por padrão, a resposta é um erro 401 sem conteúdo: útil para um cliente [JavaScript], mas confuso para um usuário. O usuário é redirecionado para a página de login. [HandleResponse()] informa a [JwtBearer] que a resposta está sendo tratada;
  • linhas 56–57: os dois componentes de middleware, nesta ordem: primeiro determinar quem é o usuário, depois verificar suas permissões.

O arquivo [Controllers/AuthController.cs]:

using Example25.Auth;
using Microsoft.AspNetCore.Mvc;

namespace Example25.Controllers;

public class AuthController(AuthService auth, IConfiguration configuration) : Controller
{
    [HttpGet("/")]
    public IActionResult Home() => Redirect("/profile");

    [HttpGet("login")]
    public IActionResult Form() => View("Login");

    [HttpPost("login")]
    public IActionResult Login(string? login, string? password)
    {
        var user = auth.Validate(login, password);
        if (user is null)
        {
            // uma mensagem deliberadamente vaga: não dizemos se é o login ou a senha
            ViewData["Error"] = "Incorrect login or password.";
            ViewData["Login"] = login;
            return View("Login");
        }
        // o token, em um cookie que o JavaScript da página não consegue ler
        Response.Cookies.Append(AuthService.Cookie, auth.CreateToken(user), new CookieOptions
        {
            HttpOnly = true,
            SameSite = SameSiteMode.Lax,
            MaxAge = TimeSpan.FromMinutes(configuration.GetValue<int>("Jwt:DurationMinutes")),
        });
        return Redirect("/profile");
    }

    // sair altera o estado do usuário: é um POST
    [HttpPost("logout")]
    public IActionResult Logout()
    {
        Response.Cookies.Delete(AuthService.Cookie);
        return Redirect("/login");
    }
}

Vamos comentar este código:

  • linhas 14–23: o login. Se o login falhar, o formulário é exibido novamente com uma mensagem deliberadamente vaga: dizer “este login não existe” ajudaria um atacante a encontrar logins válidos;
  • linhas 26–32: em caso de sucesso, o token é armazenado em um cookie [HttpOnly]; o [JavaScript] da página não consegue lê-lo, o que protege o token caso um script malicioso seja executado na página. [SameSite = Lax]: o cookie não é incluído em requisições POST enviadas de outro site, o que protege contra a falsificação de requisições ([CSRF]). A duração do cookie corresponde à do token;
  • Linhas 36–40: o logout exclui o cookie ([Cookies.Delete]). Trata-se de um POST: ele altera o estado do usuário (veja o Exemplo 21).

O arquivo [Controllers/ProfileController.cs]:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace Example25.Controllers;

// [Authorize]: reservado a usuários autenticados
[Authorize]
public class ProfileController : Controller
{
    [HttpGet("profile")]
    public IActionResult Profile()
    {
        // User: o usuário autenticado pelo token (HttpContext.User)
        return View(User.Claims.Select(c => (c.Type, c.Value)).ToList());
    }
}
  • Linha 7: o atributo [[Authorize]], aplicado ao controller, restringe todas as suas ações a usuários autenticados. Trata-se de um filtro de autorização (veja o Capítulo 7). Sem um token válido, ele dispara o desafio, resultando em um redirecionamento para [/login];
  • Linha 14: [User] (o [HttpContext.User] da requisição) é o usuário estabelecido por [JwtBearer] a partir do token. [User.Claims] é a lista de suas claims; ela é convertida em uma lista de pares (tipo, valor) para a view.

O arquivo [Views/Profile/Profile.cshtml]:

@model List<(string Type, string Value)>
<h1 class="h3">Hello @User.Identity!.Name</h1>
<p>Your role: <b>@(User.IsInRole("ADMIN") ? "administrator" : "user")</b>.</p>
<p>The content of your token:</p>
<table class="table table-sm w-auto">
  @foreach (var (type, value) in Model)
  {
    <tr><td><code>@type</code></td><td>@value</td></tr>
  }
</table>
@* sair: um formulário POST reduzido ao seu botão *@
<form method="post" action="/logout">
  <button class="btn btn-outline-secondary" type="submit">Log out</button>
</form>
  • linha 2: a propriedade [User] também é acessível em uma view. O nome é a claim [name] (veja [NameClaimType]);
  • linha 3: [IsInRole] testa a claim [role] (veja [RoleClaimType]);
  • linha 6: o laço decompõe cada par em duas variáveis;
  • linha 12: logout por meio de um formulário POST.

O arquivo [Views/Auth/Login.cshtml]:

<h1 class="h3">Login</h1>
<form method="post" action="/login">
  <div class="mb-2">
    <label class="form-label" for="login">Login</label>
    <input class="form-control" id="login" name="login" value="@ViewData["Login"]" required>
  </div>
  <div class="mb-3">
    <label class="form-label" for="password">Password</label>
    <input class="form-control" type="password" id="password" name="password" required>
  </div>
  <button class="btn btn-primary" type="submit">Log in</button>
</form>
@if (ViewData["Error"] is string error)
{
  <div class="alert alert-danger mt-3">@error</div>
}
<p class="text-muted small mt-3">Test accounts (password = login): marie (USER), admin (ADMIN).</p>

8.1.1. Execução

Sem um cookie, a página protegida redireciona para a página de login:

curl -i http://localhost:5000/profile
1
2
3
HTTP/1.1 302 Found
Content-Length: 0
Location: /login

Image

Uma senha incorreta:

Image

Login bem-sucedido, visto pelo [curl]:

curl -i -c cookies.txt -d "login=marie&password=marie" http://localhost:5000/login
1
2
3
4
HTTP/1.1 302 Found
Content-Length: 0
Location: /profile
Set-Cookie: token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3OTAzMzU1MzgsInN1YiI6Im1hcmllIiwibmFtZSI6Ik1hcmllIFDDqWxpc3NpZXIiLCJyb2xlIjoiVVNFUiIsImlhdCI6MTc5MDMzMTkzOCwibmJmIjoxNzkwMzMxOTM4fQ.uAKi5OB-jReuSrQR12_AWdiLR1l6ZLORBYSfHwg99xk; max-age=3600; path=/; samesite=lax; httponly

O token é composto por três partes separadas por pontos: um cabeçalho, o conteúdo e a assinatura. As duas primeiras são simplesmente codificadas em [base64url]. O cabeçalho decodificado:

{"alg":"HS256","typ":"JWT"}

(o algoritmo de assinatura e o tipo do token). O conteúdo decodificado:

1
2
3
4
5
6
7
8
{
  "exp": 1790335538,
  "sub": "marie",
  "name": "Marie Pélissier",
  "role": "USER",
  "iat": 1790331938,
  "nbf": 1790331938
}

Encontramos as claims geradas por [CreateToken], mais três campos adicionados por [JsonWebTokenHandler]: [exp] (a data de expiração), [iat] ([issued at], a data de criação) e [nbf] ([not before], a data a partir da qual o token é válido), em segundos desde 1º de janeiro de 1970. O token não é criptografado: ele não contém nenhuma informação confidencial. No navegador, na URL http://localhost:5000/profile:

Image

Agora vamos tentar modificar o token para nos atribuir o papel ADMIN: decodificamos o conteúdo, substituímos [USER] por [ADMIN] e o recodificamos… mas não conseguimos recalcular a assinatura sem a chave secreta:

curl -i -b "token=eyJhbGciOi...(modified content)...(old signature)" http://localhost:5000/profile
1
2
3
HTTP/1.1 302 Found
Content-Length: 0
Location: /login

A assinatura não corresponde mais ao conteúdo: o token é rejeitado, o usuário não é autenticado e [[Authorize]] redireciona para a página de login. Logout:

curl -i -b cookies.txt -X POST http://localhost:5000/logout
1
2
3
4
HTTP/1.1 302 Found
Content-Length: 0
Location: /login
Set-Cookie: token=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/

O servidor exclui o cookie redefinindo-o, vazio, com uma data de expiração já vencida.

8.2. Exemplo 26: papéis

O Exemplo 26 baseia-se no Exemplo 25 e adiciona uma página reservada ao papel ADMIN. Com o [ASP.NET Core], quase não há nada a escrever: o papel é uma claim do token, e [[Authorize]] sabe verificá-la. O arquivo [Controllers/AdminController.cs]:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace Example26.Controllers;

// todo o controller é reservado ao papel ADMIN: é preciso estar autenticado
// E ter a claim "role" igual a "ADMIN" (veja RoleClaimType em Program.cs)
[Authorize(Roles = "ADMIN")]
public class AdminController : Controller
{
    [HttpGet("admin")]
    public IActionResult Admin() => View();
}
  • Linha 8: o controller inteiro é reservado ao papel ADMIN. O filtro verifica primeiro se o usuário está autenticado (se não estiver: desafio, ou seja, a página de login) e, em seguida, se ele possui o papel exigido (se não possuir: resposta 403, “acesso negado”). [Roles = "ADMIN,DOCTOR"] aceitaria qualquer um desses papéis.

O arquivo [Program.cs] tem apenas uma linha adicional:

var app = builder.Build();

// 403 (papel insuficiente), 404...: uma página de erro
app.UseStatusCodePagesWithReExecute("/error/{0}");
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(Path.GetFullPath(Path.Combine(builder.Environment.ContentRootPath, "..", "common", "bootstrap"))),
    RequestPath = "/bootstrap",
});
app.UseAuthentication(); // quem é? -> HttpContext.User
app.UseAuthorization();  // é permitido? -> [Authorize]

app.MapControllers();
app.Run();
  • Linha 4: a resposta 403 não tem conteúdo; ela é renderizada como uma página pelo controller [ErrorController] (veja o Exemplo 24).

O usuário [marie] (papel USER) tenta abrir a página de administração a partir de seu perfil:

Image

Image

A mesma tentativa feita por [admin]:

Image

Com o [curl], vemos um erro 403:

curl -i -c cookies.txt -d "login=marie&password=marie" http://localhost:5000/login
curl -i -b cookies.txt http://localhost:5000/admin
HTTP/1.1 403 Forbidden
Content-Type: text/html; charset=utf-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Authentication</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
</head>
<body>
  <div class="container py-3" style="max-width: 34rem">
    <div class="alert alert-danger">
  <h1 class="h4">Error 403</h1>
  <p class="mb-0">Access denied: this page is reserved for administrators.</p>
</div>
<p><a href="/profile">Back to the profile</a></p>

  </div>
</body>
</html>

O estudo de caso tem três papéis (ADMIN, DOCTOR, USER) e usa exatamente estes atributos: [[Authorize]] em todos os controllers de páginas, [[Authorize(Roles = "ADMIN")]] para o gerenciamento de médicos e clientes, e [[Authorize(Roles = "USER")]] para a área do paciente. A página 403 é traduzida ali.

8.3. Exemplo 27: CAPTCHA e limite de tentativas

Uma página de login atrai bots: programas que testam milhares de combinações de login/senha. Duas proteções complementares:

  • um CAPTCHA: uma imagem de caracteres distorcidos que um humano lê facilmente, mas que um bot simples não consegue decifrar;
  • um limite de tentativas: após algumas tentativas malsucedidas, o endereço IP é bloqueado por um tempo;

O Exemplo 27 adiciona essas duas proteções ao Exemplo 25. O arquivo [Auth/CaptchaService.cs]:

using System.Collections.Concurrent;

namespace Example27.Auth;

// um captcha: seu identificador e sua imagem (SVG)
public record Captcha(string Id, string Svg);

// singleton: os captchas pendentes são mantidos em memória pelo servidor
public class CaptchaService
{
    private static readonly TimeSpan Lifetime = TimeSpan.FromMinutes(10);

    // identificador -> (resposta esperada, data de expiração).
    // ConcurrentDictionary: um dicionário utilizável por várias requisições simultâneas
    private readonly ConcurrentDictionary<string, (string Text, DateTime Expires)> pending = new();

    public Captcha Generate()
    {
        var text = CaptchaDrawing.RandomText(5);
        var id = Guid.NewGuid().ToString(); // um identificador aleatório, impossível de adivinhar
        pending[id] = (text, DateTime.UtcNow + Lifetime);
        return new Captcha(id, CaptchaDrawing.Svg(text));
    }

    // o captcha é CONSUMIDO em todos os casos: uma imagem é usada uma só vez
    public bool Check(string? id, string? input)
    {
        if (id is null || input is null || !pending.TryRemove(id, out var expected))
        {
            return false;
        }
        return expected.Expires > DateTime.UtcNow
            && string.Equals(expected.Text, input.Trim(), StringComparison.OrdinalIgnoreCase);
    }
}

Vamos detalhar este código:

  • linha 15: as respostas esperadas são armazenadas pelo servidor sob um identificador aleatório. A página contém apenas a imagem e o identificador: a resposta nunca sai do servidor. O serviço é um singleton, usado por requisições concorrentes: [ConcurrentDictionary] é um dicionário projetado para essa finalidade;
  • linhas 17–22: uma cadeia de cinco caracteres é sorteada aleatoriamente, armazenada e desenhada como imagem. O desenho é feito pela classe [CaptchaDrawing] (arquivo [Auth/CaptchaDrawing.cs], extraída do estudo de caso e comentada linha por linha): cada caractere é um conjunto de linhas que é ampliado, inclinado e distorcido aleatoriamente, e a imagem é borrada por três curvas. Caracteres facilmente confundidos (0 e O, 1, I e L) são excluídos;
  • linhas 26–33: o processo de verificação consome o CAPTCHA ([TryRemove] o remove do dicionário): uma imagem é usada uma única vez; um bot não pode reutilizar uma solução que já encontrou. Letras maiúsculas não contam.

O arquivo [Auth/LimiterService.cs]:

namespace Example27.Auth;

// singleton: conta as falhas de login de cada endereço IP
public class LimiterService
{
    private const int MaxFailures = 3;
    private static readonly TimeSpan BlockDuration = TimeSpan.FromMinutes(1);

    private class Counter
    {
        public int Failures;
        public DateTime BlockedUntil;
    }

    private readonly Dictionary<string, Counter> counters = [];
    private readonly Lock padlock = new(); // várias requisições simultâneas: um acesso por vez

    // o número de segundos de bloqueio restantes (0: não bloqueado)
    public int BlockedSeconds(string ip)
    {
        lock (padlock)
        {
            if (!counters.TryGetValue(ip, out var c)) return 0;
            var remaining = c.BlockedUntil - DateTime.UtcNow;
            return remaining > TimeSpan.Zero ? (int)Math.Ceiling(remaining.TotalSeconds) : 0;
        }
    }

    public void Failure(string ip)
    {
        lock (padlock)
        {
            if (!counters.TryGetValue(ip, out var c))
            {
                c = new Counter();
                counters[ip] = c;
            }
            c.Failures++;
            if (c.Failures >= MaxFailures)
            {
                c.BlockedUntil = DateTime.UtcNow + BlockDuration;
                c.Failures = 0; // após o bloqueio, recomeçamos do zero
            }
        }
    }

    public void Success(string ip)
    {
        lock (padlock)
        {
            counters.Remove(ip);
        }
    }
}
  • linhas 6–7: três tentativas malsucedidas bloqueiam o endereço IP por um minuto;
  • linha 16: o dicionário de contadores é compartilhado por todas as requisições. A instrução [lock (padlock) { ... }] garante que apenas uma requisição por vez execute o bloco: duas falhas simultâneas não podem se perder (veja [Interlocked], Capítulo 6). [Lock] é o tipo de lock para o [.NET] 9 e versões posteriores;
  • linhas 19–25: o tempo de bloqueio restante;
  • linhas 29–42: uma falha é contabilizada; na terceira falha, o endereço é bloqueado;
  • linhas 47–51: um sucesso zera o contador.

O arquivo [Controllers/AuthController.cs]:

using Example27.Auth;
using Microsoft.AspNetCore.Mvc;

namespace Example27.Controllers;

public class AuthController(AuthService auth, CaptchaService captchas, LimiterService limiter,
    IConfiguration configuration) : Controller
{
    [HttpGet("/")]
    public IActionResult Home() => Redirect("/profile");

    [HttpGet("login")]
    public IActionResult Form() => LoginPage(null, null);

    [HttpPost("login")]
    public IActionResult Login(string? login, string? password, string? captchaId, string? captcha)
    {
        // o endereço IP do cliente
        var ip = HttpContext.Connection.RemoteIpAddress?.ToString() ?? "?";

        // 1. um endereço bloqueado nem sequer é atendido
        var seconds = limiter.BlockedSeconds(ip);
        if (seconds > 0)
        {
            return LoginPage(login, $"Too many attempts: try again in {seconds} s.");
        }
        // 2. primeiro o captcha (barato), depois a senha (bcrypt, caro)
        if (!captchas.Check(captchaId, captcha))
        {
            limiter.Failure(ip);
            return LoginPage(login, "The image code is incorrect.");
        }
        var user = auth.Validate(login, password);
        if (user is null)
        {
            limiter.Failure(ip);
            return LoginPage(login, "Incorrect login or password.");
        }
        limiter.Success(ip);
        Response.Cookies.Append(AuthService.Cookie, auth.CreateToken(user), new CookieOptions
        {
            HttpOnly = true,
            SameSite = SameSiteMode.Lax,
            MaxAge = TimeSpan.FromMinutes(configuration.GetValue<int>("Jwt:DurationMinutes")),
        });
        return Redirect("/profile");
    }

    [HttpPost("logout")]
    public IActionResult Logout()
    {
        Response.Cookies.Delete(AuthService.Cookie);
        return Redirect("/login");
    }

    // cada exibição do formulário constrói um NOVO captcha
    private ViewResult LoginPage(string? login, string? error)
    {
        ViewData["Login"] = login;
        ViewData["Error"] = error;
        return View("Login", captchas.Generate());
    }
}

Vamos comentar este código:

  • linha 19: o endereço do cliente, IP, fornecido pela conexão de rede;
  • linhas 22–25: um endereço bloqueado nem sequer é atendido;
  • linhas 28–31: o CAPTCHA é verificado primeiro e, em seguida, a senha (uma operação [bcrypt] computacionalmente cara) somente se o CAPTCHA estiver correto. Um CAPTCHA incorreto conta como uma falha;
  • linhas 57–61: a cada exibição do formulário, um novo CAPTCHA é gerado, que se torna o modelo da view.

O arquivo [Views/Auth/Login.cshtml]:

@model Captcha
<h1 class="h3">Login</h1>
<form method="post" action="/login">
  <div class="mb-2">
    <label class="form-label" for="login">Login</label>
    <input class="form-control" id="login" name="login" value="@ViewData["Login"]" required>
  </div>
  <div class="mb-2">
    <label class="form-label" for="password">Password</label>
    <input class="form-control" type="password" id="password" name="password" required>
  </div>
  <div class="mb-3">
    <label class="form-label" for="captcha">Copy the code of the image</label>
    @* a imagem SVG, construída pelo servidor: inserida sem escape *@
    <div class="mb-1">@Html.Raw(Model.Svg)</div>
    @* o identificador do captcha viaja em um campo oculto; a resposta fica no servidor *@
    <input type="hidden" name="captchaId" value="@Model.Id">
    <input class="form-control" id="captcha" name="captcha" autocomplete="off" required>
  </div>
  <button class="btn btn-primary" type="submit">Log in</button>
</form>
@if (ViewData["Error"] is string error)
{
  <div class="alert alert-danger mt-3">@error</div>
}
<p class="text-muted small mt-3">Test accounts (password = login): marie (USER), admin (ADMIN).</p>
  • linha 15: a imagem SVG é texto (XML): ela é inserida na página como está. [Html.Raw] é legítimo aqui: trata-se de HTML gerado pelo servidor, não de uma entrada do usuário;
  • Linha 17: o ID do CAPTCHA é passado em um campo oculto; a resposta, no entanto, permanece no servidor.

A página de login, na URL http://localhost:5000/login:

Image

Um CAPTCHA digitado incorretamente:

Image

Após três tentativas malsucedidas, até a senha correta é rejeitada por um minuto:

Image

O estudo de caso aplica essas duas medidas de segurança à sua página de login e ao processo de criação de conta, com limites ajustáveis no arquivo [appsettings.json] (seção [Protection]).