Skip to content

8. Autenticação e autorização

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

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

Como o servidor é stateless (Capítulo 6), a prova de identidade deve acompanhar 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 devolve 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.

Com o [Spring], essas duas questões são tratadas pelo [Spring Security], um projeto da família [Spring] distinto do [Spring MVC]. O [Spring Security] é uma cadeia de filtros servlet (veja o Capítulo 7), posicionada antes do [DispatcherServlet]: toda requisição passa por ela antes de chegar ao [Spring MVC].

  • a autenticação é tratada por um filtro que procura um token na requisição, o verifica e deriva o usuário autenticado, um objeto [Authentication] armazenado no contexto de segurança da requisição. Para tokens JWT, esse filtro é fornecido pelo componente “resource server” ([resource server]) do [Spring Security], cujo nome deriva do protocolo [OAuth2]: um resource server é um servidor que aceita tokens gerados por outro servidor (neste caso, por ele mesmo);
  • a autorização é tratada por outro filtro, que aplica regras escritas em [Java] para cada URL (“este endereço é público”, “este exige um usuário autenticado”), e por anotações aplicadas aos controllers ([@PreAuthorize], Exemplo 26).

Os exemplos deste capítulo usam mais um starter: [spring-boot-starter-security-oauth2-resource-server]. Ele inclui o [Spring Security], seu componente “resource server” e a biblioteca [Nimbus JOSE + JWT], que gera e verifica tokens. O hashing de senhas ([bcrypt]) faz parte do [Spring Security]: não há outras bibliotecas a declarar. O [Maven] baixa essas bibliotecas durante a primeira compilação; portanto, é necessária uma conexão com a Internet.

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

25-jwt/
├── src/
│   └── main/
│       ├── java/
│       │   └── example25/
│       │       ├── auth/
│       │       │   ├── AuthService.java
│       │       │   ├── JwtProperties.java
│       │       │   └── UsersService.java
│       │       ├── config/
│       │       │   ├── SecurityConfig.java
│       │       │   └── WebConfig.java
│       │       ├── controllers/
│       │       │   ├── AuthController.java
│       │       │   └── ProfileController.java
│       │       └── Example25Application.java
│       └── resources/
│           ├── templates/
│           │   ├── auth/
│           │   │   └── login.html
│           │   ├── profile/
│           │   │   └── profile.html
│           │   └── layout.html
│           └── application.properties
└── pom.xml

O arquivo [pom.xml]:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>course.springmvc</groupId>
    <artifactId>examples</artifactId>
    <version>1.0</version>
  </parent>
  <artifactId>example25</artifactId>

  <dependencies>
    <!-- as views Thymeleaf -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <!-- Spring Security, com autenticação por token JWT (criação e verificação dos tokens) -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-security-oauth2-resource-server</artifactId>
    </dependency>
  </dependencies>
</project>
  • linhas 15–18: as views [Thymeleaf];
  • linhas 20–23: o [Spring Security] e a autenticação por token JWT. Assim que o [Spring Security] está presente no projeto, o [Spring Boot] protege todas as URLs da aplicação por padrão. É a classe de configuração [SecurityConfig], apresentada abaixo, que define nossas próprias regras.

O arquivo [application.properties]:

1
2
3
4
5
6
7
# a porta de escuta do servidor (8080 por padrão)
server.port=5000
# as respostas de erro do Spring Boot não contêm a pilha de chamadas
spring.web.error.include-stacktrace=never
# a chave que assina os tokens JWT (pelo menos 32 caracteres), e sua duração
jwt.secret=a-secret-key-of-at-least-32-characters-for-example-25
jwt.duration-minutes=60
  • linhas 6–7: duas propriedades específicas da aplicação: a chave que assina 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 do projeto, mas fornecida por uma variável de ambiente ([JWT_SECRET], que tem precedência sobre o arquivo) ou por um cofre de segredos. O algoritmo usado (HMAC-SHA256) exige uma chave de pelo menos 32 bytes (256 bits): o [Nimbus] se recusa a assinar com uma chave mais curta.

O arquivo [auth/JwtProperties.java]:

1
2
3
4
5
6
7
8
9
package example25.auth;

import org.springframework.boot.context.properties.ConfigurationProperties;

// as propriedades [jwt.*] de application.properties, armazenadas em um record:
// jwt.secret -> secret; jwt.duration-minutes -> durationMinutes
@ConfigurationProperties("jwt")
public record JwtProperties(String secret, int durationMinutes) {
}
  • linhas 7–8: a anotação [@ConfigurationProperties("jwt")] instrui o [Spring Boot] a preencher este record com as propriedades que começam por [jwt.]: [jwt.secret] vai para o componente [secret] e [jwt.duration-minutes] vai para o componente [durationMinutes] (hifens são ignorados, assim como letras maiúsculas: esse é o binding flexível do [Spring Boot]). O valor [60] é convertido em [int]; um valor que não seja um número faria a aplicação terminar imediatamente na inicialização, com uma mensagem de erro clara. O record se torna um bean, que é recebido por injeção como qualquer outro serviço. Ele é declarado pela anotação [@EnableConfigurationProperties] de [SecurityConfig] (abaixo).

Poderíamos ter lido cada propriedade com a anotação [@Value("${jwt.secret}")]; o record agrupa as propriedades de um mesmo assunto e atribui um tipo a cada uma.

O arquivo [auth/UsersService.java]:

package example25.auth;

import java.util.List;
import java.util.Optional;

import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.stereotype.Service;

// os usuários, em memória (o próximo capítulo os colocará em um banco de dados)
@Service
public class UsersService {

    public record User(String login, String name, String role, String passwordHash) {
    }

    private final List<User> users;

    // PasswordEncoder: o hash das senhas (bcrypt, veja SecurityConfig)
    public UsersService(PasswordEncoder hashing) {
        // uma senha NUNCA é guardada, somente seu hash
        users = List.of(
                new User("marie", "Marie Pélissier", "USER", hashing.encode("marie")),
                new User("admin", "Administrator", "ADMIN", hashing.encode("admin")));
    }

    public Optional<User> find(String login) {
        return users.stream().filter(u -> u.login().equals(login)).findFirst();
    }
}
  • linhas 13–14: um usuário, com seu papel, na forma de um record aninhado no serviço;
  • linhas 19–24: uma senha nunca é armazenada; apenas seu hash é guardado, um valor calculado por uma função de mão única. É possível verificar se uma senha corresponde a um hash, mas não recuperar a senha a partir do hash. O serviço recebe por injeção um [PasswordEncoder], a interface do [Spring Security] para o hashing de senhas, e o usa para gerar os hashes das duas contas de teste (linha 22);
  • linhas 26–28: a busca de um usuário pelo seu login retorna um [Optional<User>], um contêiner que contém um usuário ou está vazio. A lista é percorrida como um stream ([stream()]): [filter] mantém apenas os elementos que satisfazem a condição, e [findFirst] retorna o primeiro (em um [Optional]).

O arquivo [auth/AuthService.java]:

package example25.auth;

import java.time.Duration;
import java.time.Instant;
import java.util.Optional;

import org.springframework.http.ResponseCookie;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.JwsHeader;
import org.springframework.security.oauth2.jwt.JwtClaimsSet;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
import org.springframework.stereotype.Service;

import example25.auth.UsersService.User;

@Service
public class AuthService {

    // o nome do cookie que carrega o token
    public static final String COOKIE = "token";

    private final UsersService users;
    private final PasswordEncoder hashing;
    private final JwtEncoder encoder;
    private final JwtProperties properties;

    public AuthService(UsersService users, PasswordEncoder hashing, JwtEncoder encoder,
            JwtProperties properties) {
        this.users = users;
        this.hashing = hashing;
        this.encoder = encoder;
        this.properties = properties;
    }

    // o usuário, ou "nada" se o login for desconhecido ou a senha estiver errada
    public Optional<User> validate(String login, String password) {
        if (login == null || password == null) {
            return Optional.empty();
        }
        return users.find(login).filter(u -> hashing.matches(password, u.passwordHash()));
    }

    // o token JWT do usuário, assinado com a chave secreta
    public String createToken(User user) {
        Instant now = Instant.now();
        // o conteúdo do token: os "claims" (declarações sobre o usuário)
        JwtClaimsSet claims = JwtClaimsSet.builder()
                .subject(user.login())
                .claim("name", user.name())
                .claim("role", user.role())
                .issuedAt(now)
                .expiresAt(now.plus(duration()))
                .build();
        // o cabeçalho: o algoritmo de assinatura (HMAC-SHA256)
        JwsHeader header = JwsHeader.with(MacAlgorithm.HS256).build();
        return encoder.encode(JwtEncoderParameters.from(header, claims)).getTokenValue();
    }

    // o cookie que carrega o token: o JavaScript da página não pode lê-lo
    public ResponseCookie cookie(String token) {
        return ResponseCookie.from(COOKIE, token).path("/").httpOnly(true).sameSite("Lax").maxAge(duration()).build();
    }

    private Duration duration() {
        return Duration.ofMinutes(properties.durationMinutes());
    }
}

Vamos comentar este código:

  • linha 22: o nome do cookie que transporta o token;
  • linhas 29–35: o serviço recebe pelo construtor o serviço de usuários, o codificador de senhas, o codificador de tokens [JwtEncoder], e as propriedades [jwt.*]. Esses três últimos beans são declarados em [SecurityConfig];
  • linhas 38–43: verificação do login e da senha. [Optional.filter] esvazia o contêiner se a condição for falsa: o resultado contém o usuário somente se o login existir e se [hashing.matches(password, hash)] reconhecer a senha;
  • linhas 49–55: o conteúdo do token, os claims (declarações sobre o usuário). [subject] (o claim [sub]) é o nome convencional do identificador do usuário. Incluímos aqui o que as páginas precisam (nome, papel), para não ter de consultar o banco de dados a cada requisição. [issuedAt] e [expiresAt] fornecem os claims [iat] (data de criação) e [exp] (data de expiração);
  • linha 57: o cabeçalho do token, que especifica o algoritmo de assinatura: HMAC-SHA256, denotado por [HS256];
  • linha 58: o codificador gera o token assinado; [getTokenValue()] o converte para a forma de texto;
  • linhas 62–64: o cookie que transporta o token, gerado pela classe [ResponseCookie] do [Spring]: [httpOnly(true)] impede que o [JavaScript] da página o leia, o que protege o token caso um script malicioso seja executado na página; [sameSite("Lax")] impede que o navegador o inclua em requisições POST enviadas de outro site (veja abaixo, a proteção [CSRF]); [maxAge] define o tempo de vida do cookie de acordo com o tempo de vida do token.

O arquivo [config/SecurityConfig.java] é o núcleo deste exemplo. Sua primeira parte declara os beans necessários para a segurança:

package example25.config;

import java.nio.charset.StandardCharsets;

import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseCookie;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
import org.springframework.security.oauth2.server.resource.web.BearerTokenResolver;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.web.util.WebUtils;

import example25.auth.AuthService;
import example25.auth.JwtProperties;
import jakarta.servlet.http.Cookie;

// a configuração do Spring Security
@Configuration
@EnableConfigurationProperties(JwtProperties.class)
public class SecurityConfig {

    // a chave que assina e verifica os tokens (algoritmo HMAC-SHA256 simétrico)
    @Bean
    public SecretKey jwtKey(JwtProperties properties) {
        return new SecretKeySpec(properties.secret().getBytes(StandardCharsets.UTF_8), "HmacSHA256");
    }

    // a construção dos tokens (biblioteca Nimbus, trazida pelo Spring Security)
    @Bean
    public JwtEncoder jwtEncoder(SecretKey key) {
        return NimbusJwtEncoder.withSecretKey(key).algorithm(MacAlgorithm.HS256).build();
    }

    // a verificação dos tokens: assinatura e data de expiração
    @Bean
    public JwtDecoder jwtDecoder(SecretKey key) {
        return NimbusJwtDecoder.withSecretKey(key).macAlgorithm(MacAlgorithm.HS256).build();
    }

    // o hash das senhas: bcrypt, com um custo de 10
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(10);
    }
  • linha 33: uma classe de configuração, cujos métodos [@Bean] criam beans (veja o Exemplo 06);
  • linha 34: registro do record [JwtProperties] como bean, preenchido a partir de [application.properties];
  • linhas 38–41: a chave de assinatura, gerada a partir do texto da propriedade [jwt.secret]. A mesma chave é usada para assinar e verificar os tokens: o algoritmo é simétrico. Um método [@Bean] pode aceitar outros beans como parâmetros: neste caso, as propriedades [jwt.*];
  • linhas 44–47: o codificador de tokens, que assina usando a chave. O [NimbusJwtEncoder] se apoia na biblioteca [Nimbus];
  • linhas 50–53: o decodificador, que verifica cada token recebido: primeiro a assinatura (usando a mesma chave) e depois a data de expiração (com tolerância de 60 segundos para relógios dessincronizados). O filtro de autenticação o utiliza em toda requisição que carrega um token;
  • linhas 56–59: hashing de senhas com o algoritmo [bcrypt], com um “custo” de 10: o [bcrypt] é intencionalmente lento (2¹⁰ ciclos de cálculo) para desencorajar quem tentasse milhões de senhas. Dois hashes da mesma senha são diferentes (um “salt” aleatório é adicionado): [matches] se encarrega de verificá-los.

A segunda parte descreve a cadeia de filtros de segurança:

    // a cadeia de filtros de segurança: quem pode acessar o quê, e como
    // o usuário é reconhecido
    @Bean
    public SecurityFilterChain securityFilters(HttpSecurity http) throws Exception {
        http
                // 1. as regras de acesso, examinadas em ordem
                .authorizeHttpRequests(access -> access
                        .requestMatchers("/", "/login", "/error", "/bootstrap/**").permitAll()
                        .anyRequest().authenticated())
                // 2. autenticação por token JWT (OAuth2 "resource server")
                .oauth2ResourceServer(jwt -> jwt
                        .bearerTokenResolver(tokenFromCookie())
                        .authenticationEntryPoint(toLogin())
                        .jwt(config -> config.jwtAuthenticationConverter(converter())))
                // 3. página protegida solicitada sem token: direto para a página de login
                .exceptionHandling(errors -> errors.authenticationEntryPoint(toLogin()))
                // 4. logout (POST /logout): apagar o cookie e depois ir para /login
                .logout(logout -> logout.logoutUrl("/logout").deleteCookies(AuthService.COOKIE)
                        .logoutSuccessUrl("/login"))
                // 5. o servidor é stateless: sem sessão HTTP
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                // 6. sem token anti-CSRF: o cookie SameSite=Lax já protege
                // as requisições POST vindas de outros sites
                .csrf(csrf -> csrf.disable());
        return http.build();
    }

    // o token é lido do cookie (e não do cabeçalho Authorization)
    private static BearerTokenResolver tokenFromCookie() {
        return request -> {
            Cookie cookie = WebUtils.getCookie(request, AuthService.COOKIE);
            return cookie == null ? null : cookie.getValue();
        };
    }

    // nenhum usuário autenticado (sem token, token inválido ou expirado):
    // apagamos o eventual cookie e redirecionamos para a página de login
    private static AuthenticationEntryPoint toLogin() {
        return (request, response, exception) -> {
            if (WebUtils.getCookie(request, AuthService.COOKIE) != null) {
                response.addHeader("Set-Cookie", ResponseCookie.from(AuthService.COOKIE, "").path("/").maxAge(0).build().toString());
            }
            response.sendRedirect("/login");
        };
    }

    // do token ao usuário autenticado: o claim [name] é o nome dele, o
    // claim [role] o seu papel; o Spring Security escreve os papéis com o prefixo ROLE_
    private static JwtAuthenticationConverter converter() {
        JwtGrantedAuthoritiesConverter roles = new JwtGrantedAuthoritiesConverter();
        roles.setAuthoritiesClaimName("role");
        roles.setAuthorityPrefix("ROLE_");
        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(roles);
        converter.setPrincipalClaimName("name");
        return converter;
    }
}

Vamos analisar este código:

  • linhas 4–5: um bean do tipo [SecurityFilterChain]: a cadeia de filtros de segurança. O [Spring Boot] fornece um objeto [HttpSecurity], que configuramos, método por método, antes de construir a cadeia (linha 26). Cada método recebe uma lambda que configura uma parte das definições;
  • linhas 8–10: as regras de acesso às URLs, examinadas na ordem a seguir: [/], [/login], [/error] (a página de erro do [Spring Boot]) e os arquivos do [Bootstrap] são públicos ([permitAll()]); qualquer outra URL ([anyRequest()]) exige um usuário autenticado. A página [/profile] está, portanto, protegida, sem que seja necessário escrever nada em seu controller;
  • Linhas 12–15: autenticação baseada em token JWT. Por padrão, o resource server procura o token no cabeçalho [Authorization: Bearer ...] da requisição: é assim que funcionam um cliente [JavaScript] ou um aplicativo mobile. Um navegador não adiciona esse cabeçalho por conta própria: instruímos o resource server a obter o token do cookie (linha 13). A linha 15 altera a forma como o token é mapeado para um usuário (veja as linhas 50–58);
  • linhas 14 e 17: o ponto de entrada de autenticação ([authentication entry point]) é chamado quando uma página protegida é solicitada sem um usuário autenticado. 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. Isso é declarado duas vezes: o filtro do resource server chama diretamente seu próprio ponto de entrada quando a requisição contém um token que ele rejeita (linha 14); a linha 17 cobre o caso de uma página protegida solicitada sem token;
  • linhas 19–20: o logout é tratado pelo próprio [Spring Security] , por meio de um filtro ([LogoutFilter]) que intercepta [POST /logout]: ele exclui o cookie do token ([deleteCookies]) e redireciona para [/login]. Nenhuma action de controller é necessária;
  • linha 22: [STATELESS]: o [Spring Security] não cria uma sessão (HTTP; veja o Capítulo 6) e não a usa para reter o usuário. O usuário é reconhecido a cada requisição unicamente pelo token;
  • linha 25: a proteção [CSRF] ([Cross-Site Request Forgery], falsificação de requisição entre sites) está desativada. Um ataque [CSRF] consiste em um site malicioso induzir o navegador da vítima a enviar um formulário POST ao nosso site: o navegador incluiria o cookie, e a requisição seria autenticada. Por padrão, o [Spring Security] exige um token anti-CSRF em todo formulário POST, um campo oculto que o site malicioso não tem como conhecer. Aqui, o cookie [SameSite=Lax] é suficiente: o navegador não o inclui em uma requisição POST originada de outro site, de modo que essa requisição chega sem usuário autenticado. No entanto, nenhuma requisição GET com o cookie deve modificar dados (veja o Exemplo 21): um cookie [Lax] acompanha os links vindos de outros sites;
  • linhas 30–35: o resolver de token ([BearerTokenResolver]): uma interface de um único método, escrita aqui como lambda, que retorna o token da requisição ou [null]. [WebUtils.getCookie] procura um cookie pelo nome;
  • linhas 39–46: o ponto de entrada: um redirecionamento para [/login] (linha 44). Se a requisição continha um cookie [token], significa que o token é inválido (assinatura inválida) ou expirou: o cookie é limpo ao redefini-lo com um valor vazio e tempo de vida zero (linhas 41–43). Sem essa etapa, o navegador reenviaria o token rejeitado junto com a requisição [GET /login], que o filtro rejeitaria por sua vez, resultando em um loop de redirecionamento;
  • linhas 50–58: do token ao usuário autenticado. Para o [Spring Security], as permissões de um usuário são authorities ([authorities]): simples strings de caracteres. Por padrão, o resource server as lê do claim [scope] do token, com o prefixo [SCOPE_]. Aqui elas são lidas do claim [role] (linha 52), com o prefixo [ROLE_] (linha 53), que o [Spring Security] espera para um papel: o papel [USER] do token se torna a authority [ROLE_USER]. A linha 56 indica que o nome do usuário ([Authentication.getName()]) é o claim [name], e não [sub].

Os filtros que o [Spring Security] colocou na cadeia são escritos no console na inicialização, se o nível de log [DEBUG] for solicitado para a classe [DefaultSecurityFilterChain]:

../mvnw spring-boot:run -Dspring-boot.run.arguments=--logging.level.org.springframework.security.web.DefaultSecurityFilterChain=debug
... DEBUG ... o.s.s.web.DefaultSecurityFilterChain : Will secure any request with filters: DisableEncodeUrlFilter, WebAsyncManagerIntegrationFilter, SecurityContextHolderFilter, HeaderWriterFilter, LogoutFilter, OAuth2ProtectedResourceMetadataFilter, BearerTokenAuthenticationFilter, RequestCacheAwareFilter, SecurityContextHolderAwareRequestFilter, AnonymousAuthenticationFilter, SessionManagementFilter, ExceptionTranslationFilter, AuthorizationFilter

Podem-se identificar, em particular:

  • [HeaderWriterFilter], que adiciona cabeçalhos de segurança ([X-Content-Type-Options: nosniff], [X-Frame-Options: DENY], [Cache-Control: no-cache, no-store...]) a cada resposta: eles não aparecem nas respostas deste capítulo;
  • [LogoutFilter], que processa [/logout];
  • [BearerTokenAuthenticationFilter], o filtro do resource server: ele lê o token (usando nosso resolver), o verifica (usando o decodificador) e coloca o usuário autenticado no contexto de segurança;
  • [AnonymousAuthenticationFilter]: sem token, o usuário é “anônimo”;
  • [ExceptionTranslationFilter], que transforma negações de acesso em respostas HTTP: ponto de entrada para um usuário anônimo, erro 403 para um usuário autenticado (exemplo 26);
  • [AuthorizationFilter], o último, que aplica as regras de [authorizeHttpRequests].

O arquivo [controllers/AuthController.java]:

package example25.controllers;

import java.util.Optional;

import org.springframework.http.HttpHeaders;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;

import example25.auth.AuthService;
import example25.auth.UsersService.User;
import jakarta.servlet.http.HttpServletResponse;

@Controller
public class AuthController {

    private final AuthService auth;

    public AuthController(AuthService auth) {
        this.auth = auth;
    }

    @GetMapping("/")
    public String home() {
        return "redirect:/profile";
    }

    @GetMapping("/login")
    public String form() {
        return "auth/login";
    }

    @PostMapping("/login")
    public String login(@RequestParam(required = false) String login,
            @RequestParam(required = false) String password, HttpServletResponse response, Model model) {
        Optional<User> user = auth.validate(login, password);
        if (user.isEmpty()) {
            // uma mensagem deliberadamente vaga: não dizemos se é o login ou a senha
            model.addAttribute("error", "Incorrect login or password.");
            model.addAttribute("login", login);
            return "auth/login";
        }
        // o token, em um cookie
        response.addHeader(HttpHeaders.SET_COOKIE, auth.cookie(auth.createToken(user.get())).toString());
        return "redirect:/profile";
    }
}

Vamos analisar este código:

  • linhas 35–44: o login. Os parâmetros são opcionais ([required = false]): um parâmetro ausente assume o valor [null], e [AuthService.validate] o rejeita. 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;
  • linha 46: em caso de sucesso, o cookie é adicionado à resposta como um cabeçalho [Set-Cookie], antes do redirecionamento para o perfil;
  • Não há nenhuma action [/logout]: o logout é tratado pelo filtro [LogoutFilter], antes mesmo de a requisição chegar ao [Spring MVC].

O arquivo [controllers/ProfileController.java]:

package example25.controllers;

import org.springframework.security.core.Authentication;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

// reservado aos usuários autenticados: veja SecurityConfig (anyRequest().authenticated())
@Controller
public class ProfileController {

    // Authentication: o usuário autenticado pelo token;
    // @AuthenticationPrincipal Jwt: o próprio token, já verificado
    @GetMapping("/profile")
    public String profile(Authentication user, @AuthenticationPrincipal Jwt token, Model model) {
        model.addAttribute("name", user.getName());
        model.addAttribute("admin", user.getAuthorities().stream()
                .anyMatch(a -> a.getAuthority().equals("ROLE_ADMIN")));
        model.addAttribute("claims", token.getClaims());
        return "profile/profile";
    }
}
  • Linha 10: nenhuma anotação de segurança no controller: a regra [anyRequest().authenticated()] de [SecurityConfig] já protege [/profile];
  • Linha 17: uma action pode receber o usuário autenticado como parâmetro, do tipo [Authentication], armazenado no contexto de segurança pelo filtro do resource server. A anotação [@AuthenticationPrincipal] dá acesso ao principal desse usuário: para a autenticação via JWT, é o próprio token (tipo [Jwt]), que já foi verificado;
  • linha 18: o nome do usuário, o claim [name] (veja [setPrincipalClaimName]);
  • Linhas 19–20: o usuário é um administrador? Verificamos a presença da authority [ROLE_ADMIN] entre as authorities do usuário;
  • linha 21: os claims do token, em forma de dicionário ([Map<String, Object>]).

O arquivo [templates/profile/profile.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h1 class="h3" th:text="|Hello ${name}|">Hello</h1>
  <p>Your role: <b th:text="${admin} ? 'administrator' : 'user'">user</b>.</p>
  <p>The content of your token:</p>
  <table class="table table-sm w-auto">
    <!--/* um laço sobre um dicionário: cada elemento tem uma chave e um valor */-->
    <tr th:each="claim : ${claims}"><td><code th:text="${claim.key}">sub</code></td><td th:text="${claim.value}">marie</td></tr>
  </table>
  <!--/* logout: 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>
</main>
</body>
</html>
  • linha 10: [th:each] também itera sobre um dicionário: cada elemento tem uma chave ([claim.key]) e um valor ([claim.value]);
  • Linhas 13–15: o logout, por meio de um formulário POST reduzido ao seu botão.

O arquivo [templates/auth/login.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <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" th:value="${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>
  <div class="alert alert-danger mt-3" th:if="${error != null}" th:text="${error}">error</div>
  <p class="text-muted small mt-3">Test accounts (password = login): marie (USER), admin (ADMIN).</p>
</main>
</body>
</html>
  • linha 9: o nome de usuário digitado é exibido novamente após um login malsucedido; a senha nunca é exibida novamente;
  • linha 17: a mensagem de erro, se houver.

O template [templates/layout.html] e a classe [config/WebConfig.java], que servem os arquivos do [Bootstrap] na URL [/bootstrap/...], são os mesmos dos exemplos anteriores (veja o Exemplo 15 e o Capítulo 1).

8.1.1. Execução

Sem 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
Location: http://localhost:5000/login
Content-Length: 0

(O [Tomcat] não inclui o texto [Found], que costuma acompanhar o código 302: ele é opcional.)

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
Set-Cookie: token=eyJraWQiOiJLQzBjVllOZXdUWWFTY1FWM21EV1ZEbFQ0bDZWYmFfUTNSNjB6cmNtWmQ0IiwiYWxnIjoiSFMyNTYifQ.eyJuYW1lIjoiTWFyaWUgUMOpbGlzc2llciIsInN1YiI6Im1hcmllIiwicm9sZSI6IlVTRVIiLCJleHAiOjE3OTAzNTgzNTYsImlhdCI6MTc5MDM1NDc1Nn0.ZsCOrkYPuZFYu2xPtIx3JGpKBQCOJP9dqF8fzkwpLmo; Path=/; Max-Age=3600; Expires=Fri, 25 Sep 2026 17:45:56 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:5000/profile
Content-Length: 0

O token é composto de 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:

{"kid":"KC0cVYNewTYaScQV3mDWVDlT4l6Vba_Q3R60zrcmZd4","alg":"HS256"}

Ele contém o algoritmo de assinatura ([alg]) e um identificador de chave ([kid], [key id]): quando um servidor usa várias chaves, o [kid] indica qual chave assinou o token. O [NimbusJwtEncoder] o calcula por conta própria a partir da chave (é a impressão digital SHA-256 da chave, segundo o padrão [JWK Thumbprint]): ele não revela nada sobre a chave. O conteúdo decodificado:

1
2
3
4
5
6
7
{
  "name": "Marie Pélissier",
  "sub": "marie",
  "role": "USER",
  "exp": 1790358356,
  "iat": 1790354756
}

Encontramos os claims gerados por [createToken]. As datas [exp] e [iat] são escritas em segundos desde 1º de janeiro de 1970. O token não é criptografado: nada secreto é incluído nele. No navegador, na URL http://localhost:5000/profile:

Image

Na página, as datas [exp] e [iat] são exibidas no formato ISO 8601: o decodificador as converteu em objetos [Instant] (um instante em tempo universal, daí o [Z] final). Vemos que o token é válido por uma hora.

Agora vamos tentar modificar o token para atribuir a nós mesmos o papel ADMIN: decodificamos o conteúdo, substituímos [USER] por [ADMIN] e o codificamos novamente... mas não podemos recalcular a assinatura sem a chave secreta:

curl -i -b "token=eyJraWQiOi...(modified content)...(old signature)" http://localhost:5000/profile
1
2
3
4
HTTP/1.1 302
Set-Cookie: token=; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Location: http://localhost:5000/login
Content-Length: 0

A assinatura não corresponde mais ao conteúdo: o decodificador rejeita o token, o filtro chama o ponto de entrada, que limpa o cookie e redireciona para a página de login. O logout:

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

O filtro [LogoutFilter] limpa o cookie redefinindo-o, vazio, com uma data de expiração já vencida. Observe que, como a proteção [CSRF] está desativada, o [Spring Security] também aceita o logout por meio de um GET ([curl -i http://localhost:5000/logout] retorna a mesma resposta): isso é inofensivo aqui (no máximo, um link malicioso desconecta o usuário), mas nossas páginas sempre desconectam os usuários por meio de um POST.

8.2. Exemplo 26: papéis

O Exemplo 26 se baseia no Exemplo 25 e adiciona uma página reservada ao papel ADMIN. O papel já é uma authority do usuário autenticado ([ROLE_ADMIN]): basta exigi-lo. O arquivo [controllers/AdminController.java]:

package example26.controllers;

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.Authentication;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

// o controller inteiro é reservado ao papel ADMIN: é preciso estar autenticado E
// ter o papel ADMIN (o claim "role" do token, veja SecurityConfig)
@Controller
@PreAuthorize("hasRole('ADMIN')")
public class AdminController {

    @GetMapping("/admin")
    public String admin(Authentication user, Model model) {
        model.addAttribute("name", user.getName());
        return "admin/admin";
    }
}
  • linha 12: a anotação [@PreAuthorize] define uma condição, que é verificada antes de cada action do controller ser chamada. A condição é uma expressão na linguagem [SpEL] ([Spring Expression Language]): [hasRole('ADMIN')] é verdadeira se o usuário tiver a authority [ROLE_ADMIN] (o prefixo [ROLE_] é adicionado por [hasRole]). Um usuário anônimo é primeiro redirecionado para a página de login (ponto de entrada); um usuário autenticado sem esse papel recebe uma resposta 403, “Access Denied”. [hasAnyRole('ADMIN', 'DOCTOR')] aceitaria qualquer um desses papéis.

Para que [@PreAuthorize] seja levado em conta, a classe [SecurityConfig] tem uma anotação adicional:

1
2
3
4
5
6
// a configuração do Spring Security.
// @EnableMethodSecurity: habilita as anotações @PreAuthorize dos controllers
@Configuration
@EnableMethodSecurity
@EnableConfigurationProperties(JwtProperties.class)
public class SecurityConfig {
  • Linha 4: [@EnableMethodSecurity] ativa a segurança de métodos. O [Spring] passa então a envolver cada bean cujo método carrega [@PreAuthorize] em um proxy: um objeto intermediário que recebe as chamadas em nome do bean, verifica a condição e depois chama o método real ou lança uma exceção [AccessDeniedException]. Voltaremos a esse mecanismo de proxy no contexto das transações no próximo capítulo.

A cadeia de filtros mudou em dois pontos:

1
2
3
4
5
6
7
8
9
                .oauth2ResourceServer(jwt -> jwt
                        .bearerTokenResolver(tokenFromCookie())
                        .authenticationEntryPoint(toLogin())
                        .accessDeniedHandler(accessDenied())
                        .jwt(config -> config.jwtAuthenticationConverter(converter())))
                // 3. página protegida solicitada sem token: direto para a página de login;
                // papel insuficiente: uma resposta 403, transformada em página por ErrorPageController
                .exceptionHandling(errors -> errors.authenticationEntryPoint(toLogin())
                        .accessDeniedHandler(accessDenied()))
  • linhas 4 e 9: o tratador de acesso negado ([access denied handler]). A exceção lançada por [@PreAuthorize] é propagada, via [Spring MVC], até o filtro [ExceptionTranslationFilter], que a repassa a esse tratador. O tratador do resource server retornaria uma resposta 403 sem conteúdo, incluindo um cabeçalho [WWW-Authenticate] destinado a um cliente [JavaScript]. Assim como o ponto de entrada, ele é substituído em dois lugares.

O próprio tratador, no final do arquivo:

1
2
3
4
    // papel insuficiente: uma resposta de erro 403, que o servidor encaminha para /error
    private static AccessDeniedHandler accessDenied() {
        return (request, response, exception) -> response.sendError(HttpServletResponse.SC_FORBIDDEN);
    }
  • linhas 2–4: nosso tratador simplesmente usa [sendError(403)]. O servidor [Tomcat] encaminha então a requisição para a URL [/error] (veja o Exemplo 24), isto é, para o tratador de erros. É por isso que [/error] aparece entre as URLs públicas: a requisição encaminhada também passa pela cadeia de filtros.

O arquivo [controllers/ErrorPageController.java]:

package example26.controllers;

import org.springframework.boot.webmvc.error.ErrorController;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;

import jakarta.servlet.RequestDispatcher;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

// a página das respostas de erro (403, 404...): veja o exemplo 24
@Controller
public class ErrorPageController implements ErrorController {

    @RequestMapping("/error")
    public String error(HttpServletRequest request, HttpServletResponse response, Model model) {
        Object code = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
        int status = code instanceof Integer c ? c : 500;
        response.setStatus(status);
        model.addAttribute("code", status);
        return "error";
    }
}
  • linhas 14–16: o controller da página de erro, como no Exemplo 24: ele implementa a interface [ErrorController] do [Spring Boot], substituindo assim a página de erro padrão;
  • Linhas 18–21: o código de status da resposta de erro (403, 404 etc.) é um atributo da requisição; ele é copiado para a resposta e para o template da view.

A view [templates/error.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <div class="alert alert-danger">
    <h1 class="h4" th:text="|Error ${code}|">Error 403</h1>
    <p class="mb-0" th:text="${code == 403} ? 'Access denied: this page is reserved for administrators.' : 'An error occurred.'">message</p>
  </div>
  <p><a href="/profile">Back to the profile</a></p>
</main>
</body>
</html>
  • linha 7: uma mensagem específica para o erro 403 e uma mensagem genérica para os demais.

Por fim, a página de perfil tem mais um link, para [/admin]. O usuário [marie] (papel USER) tenta abrir a página de administração a partir do seu perfil:

Image

Image

A mesma tentativa 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
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">
    <main>
  <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>
</main>
  </div>
</body>
</html>

O estudo de caso tem três papéis (ADMIN, DOCTOR, USER) e usa exatamente esses mecanismos: a regra [anyRequest().authenticated()] protege todas as páginas, exceto as de login e de criação de conta; [@PreAuthorize("hasRole('ADMIN')")] restringe ao administrador o acesso ao gerenciamento de médicos e clientes; [@PreAuthorize("hasRole('USER')")] restringe aos pacientes o acesso à área do paciente. A página 403 é exibida ali.

8.3. Exemplo 27: CAPTCHA e limites de tentativas

Uma página de login atrai bots: programas que tentam milhares de combinações diferentes de nome de usuário e senha. Duas salvaguardas complementares:

  • um CAPTCHA: uma imagem de caracteres distorcidos que um humano lê com facilidade, 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 salvaguardas ao Exemplo 25. O arquivo [auth/CaptchaService.java]:

package example27.auth;

import java.time.Duration;
import java.time.Instant;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;

import org.springframework.stereotype.Service;

// singleton: os captchas pendentes são mantidos em memória pelo servidor
@Service
public class CaptchaService {

    // um captcha: seu identificador e sua imagem (SVG)
    public record Captcha(String id, String svg) {
    }

    // a resposta esperada e sua data de expiração
    private record Expected(String text, Instant expires) {
    }

    private static final Duration LIFETIME = Duration.ofMinutes(10);

    // identificador -> resposta esperada.
    // ConcurrentHashMap: um dicionário utilizável por várias requisições simultâneas
    private final Map<String, Expected> pending = new ConcurrentHashMap<>();

    public Captcha generate() {
        String text = CaptchaDrawing.randomText(5);
        String id = UUID.randomUUID().toString(); // um identificador aleatório, impossível de adivinhar
        pending.put(id, new Expected(text, Instant.now().plus(LIFETIME)));
        return new Captcha(id, CaptchaDrawing.svg(text));
    }

    // o captcha é CONSUMIDO em todos os casos: uma imagem é usada uma única vez
    public boolean check(String id, String input) {
        Expected expected = id == null ? null : pending.remove(id);
        return expected != null && input != null
                && expected.expires().isAfter(Instant.now())
                && expected.text().equalsIgnoreCase(input.trim());
    }
}

Vamos comentar este código:

  • linhas 11–13: um serviço é um bean singleton (veja o Exemplo 06): uma única instância, compartilhada por todas as requisições. Os CAPTCHAs pendentes são, portanto, mantidos na memória do servidor;
  • linhas 16–21: dois records: o CAPTCHA enviado à página (ID e imagem) e a resposta esperada, armazenada pelo servidor;
  • linha 27: as respostas esperadas são armazenadas 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 é usado por requisições concorrentes, executadas por threads diferentes: [ConcurrentHashMap] é um dicionário projetado para essa finalidade;
  • linhas 29–34: um texto de cinco caracteres gerado aleatoriamente, armazenado por dez minutos e renderizado como imagem. [UUID.randomUUID()] gera um identificador aleatório de 128 bits impossível de adivinhar;
  • linhas 37–42: a verificação consome o CAPTCHA ([remove] o remove do dicionário e retorna o valor removido): uma imagem é usada uma única vez; um bot não pode reutilizar uma solução que já encontrou. Um CAPTCHA expirado é rejeitado; letras maiúsculas ou minúsculas não importam ([equalsIgnoreCase]).

A imagem é tratada pela classe [auth/CaptchaDrawing.java], extraída do estudo de caso. Nenhuma biblioteca é necessária: a imagem está no formato [SVG] ([Scalable Vector Graphics]), um formato de imagem vetorial composto de texto (XML), que o navegador consegue exibir. O início do arquivo:

// o desenho de um captcha: uma imagem SVG (texto XML) construída à mão
final class CaptchaDrawing {

    private static final int WIDTH = 150;
    private static final int HEIGHT = 50;

    // SecureRandom: um gerador de números aleatórios "criptográfico",
    // imprevisível (ao contrário de Random, cuja sequência poderia ser adivinhada)
    private static final SecureRandom RANDOM = new SecureRandom();

    // A "fonte": cada caractere é uma lista de traços, cada traço uma
    // sequência de pontos (x, y) em uma grade de 4 x 6 (y apontando para baixo).
    // Caracteres fáceis demais de confundir entre si: excluídos (0 O, 1 I L).
    private static final Map<Character, double[][]> FONT = new LinkedHashMap<>();

    static {
  • linha 2: uma classe [final] (da qual não se pode herdar), sem a palavra-chave [public]: ela é visível apenas para as classes de seu pacote, [example27.auth];
  • linha 9: o número aleatório é gerado por [SecureRandom], um gerador criptográfico: a sequência de suas saídas é imprevisível, mesmo para quem conhece as saídas anteriores. Não é o caso de [Random], cuja sequência pode ser reconstruída com apenas alguns sorteios: um bot poderia então prever os CAPTCHAs seguintes;
  • linhas 11–14: cada caractere é descrito por uma lista de traços em uma pequena grade. Os caracteres facilmente confundidos (0 e O, 1, I e L) são excluídos. O restante do arquivo (não reproduzido aqui) preenche esse dicionário em um bloco [static { ... }] que é executado uma vez quando a classe é carregada.

O desenho da imagem:

    static String svg(String text) {
        StringBuilder svg = new StringBuilder();
        svg.append("<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"%d\" height=\"%d\" viewBox=\"0 0 %d %d\">"
                .formatted(WIDTH, HEIGHT, WIDTH, HEIGHT));
        svg.append("<rect width=\"100%\" height=\"100%\" fill=\"#f5f7fa\"/>");

        // os caracteres: cada um ampliado, inclinado, deslocado, e cada ponto
        // ligeiramente movido ao acaso
        double step = (WIDTH - 20) / (double) text.length();
        for (int i = 0; i < text.length(); i++) {
            double scale = random(4.6, 5.6); // tamanho de uma unidade da grade, em pixels
            double angle = random(-0.35, 0.35); // rotação, em radianos (cerca de ±20°)
            double cx = 10 + step * (i + 0.5) + random(-3, 3); // centro do caractere
            double cy = HEIGHT / 2.0 + random(-4, 4);
            StringBuilder d = new StringBuilder();
            for (double[] stroke : FONT.get(text.charAt(i))) {
                for (int k = 0; k < stroke.length; k += 2) {
                    // ponto da grade, centralizado em (2, 3), distorcido, girado, posicionado
                    double x = (stroke[k] - 2 + random(-0.2, 0.2)) * scale;
                    double y = (stroke[k + 1] - 3 + random(-0.2, 0.2)) * scale;
                    double px = cx + x * Math.cos(angle) - y * Math.sin(angle);
                    double py = cy + x * Math.sin(angle) + y * Math.cos(angle);
                    d.append(k == 0 ? 'M' : 'L').append(number(px)).append(' ').append(number(py)).append(' ');
                }
            }
            svg.append("<path d=\"%s\" fill=\"none\" stroke=\"%s\" stroke-width=\"%s\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>"
                    .formatted(d.toString().trim(), color(), number(random(2.2, 3))));
        }

        // 3 traços de ruído: curvas que cruzam a imagem
        for (int n = 0; n < 3; n++) {
            svg.append("<path d=\"M%s %s C%s %s %s %s %s %s\" fill=\"none\" stroke=\"%s\" stroke-width=\"1.3\"/>"
                    .formatted(number(random(0, 20)), number(random(5, 45)),
                            number(random(30, 60)), number(random(0, 50)), number(random(90, 120)), number(random(0, 50)),
                            number(random(130, 150)), number(random(5, 45)), color()));
        }
        svg.append("</svg>");
        return svg.toString();
    }

    // um número com ponto decimal, qualquer que seja o idioma do servidor
    // (em francês, "%.1f" escreveria "12,5" - ilegível para o SVG)
    private static String number(double value) {
        return String.format(Locale.ROOT, "%.1f", value);
    }
  • Linhas 3–5: a imagem SVG é um elemento [<svg>] de 150 x 50 pixels, sobre um fundo claro (um retângulo [<rect>]). ["...".formatted(...)] substitui os [%d] e [%s] do texto pelos valores fornecidos, como [String.format];
  • Linhas 9–28: cada caractere se torna um caminho [<path>]: uma sequência de pontos ligados por segmentos ([M]: ir até o ponto; [L]: traçar um segmento até o ponto). Cada caractere é ampliado, inclinado e deslocado aleatoriamente, e cada um de seus pontos é ligeiramente movido: nunca há duas imagens idênticas do mesmo texto;
  • linhas 31–36: três curvas de embaralhamento ([C]: uma curva de Bézier) cruzam a imagem para confundir um programa de reconhecimento de caracteres;
  • linhas 43–45: os números são escritos com ponto decimal, independentemente do idioma do servidor ([Locale.ROOT]): em francês, [%.1f] escreveria uma vírgula, que o SVG não reconhece.

O arquivo [auth/LimiterService.java]:

package example27.auth;

import java.time.Duration;
import java.time.Instant;
import java.util.HashMap;
import java.util.Map;

import org.springframework.stereotype.Service;

// singleton: conta as falhas de login de cada endereço IP
@Service
public class LimiterService {

    private static final int MAX_FAILURES = 3;
    private static final Duration BLOCK_DURATION = Duration.ofMinutes(1);

    private static class Counter {
        int failures;
        Instant blockedUntil = Instant.MIN;
    }

    private final Map<String, Counter> counters = new HashMap<>();

    // synchronized: várias requisições simultâneas, um único acesso por vez

    // o número de segundos de bloqueio restantes (0: não bloqueado)
    public synchronized long blockedSeconds(String ip) {
        Counter c = counters.get(ip);
        if (c == null) {
            return 0;
        }
        Duration remaining = Duration.between(Instant.now(), c.blockedUntil);
        return remaining.isNegative() || remaining.isZero() ? 0 : (remaining.toMillis() + 999) / 1000;
    }

    public synchronized void failure(String ip) {
        Counter c = counters.computeIfAbsent(ip, key -> new Counter());
        c.failures++;
        if (c.failures >= MAX_FAILURES) {
            c.blockedUntil = Instant.now().plus(BLOCK_DURATION);
            c.failures = 0; // após o bloqueio, recomeçamos do zero
        }
    }

    public synchronized void success(String ip) {
        counters.remove(ip);
    }
}
  • linhas 14–15: três falhas bloqueiam o endereço IP por um minuto;
  • linhas 17–20: o contador de um endereço: número de falhas e data de fim do bloqueio ([Instant.MIN], um tempo muito remoto, inicialmente);
  • linha 22: o dicionário de contadores é compartilhado por todas as requisições. É um simples [HashMap], que não suporta acesso concorrente: cada método é, portanto, [synchronized]. A palavra-chave garante que apenas uma thread por vez execute um dos métodos [synchronized] do objeto: duas falhas simultâneas não podem ocorrer (veja [AtomicInteger], Capítulo 6);
  • linhas 27–34: o tempo de bloqueio restante, arredondado para cima até o próximo segundo;
  • linhas 36–43: uma falha é contabilizada; na terceira falha, o endereço é bloqueado. [computeIfAbsent] retorna o contador do endereço após criá-lo, se ainda não existia;
  • linhas 45–47: um sucesso zera o contador.

O arquivo [controllers/AuthController.java]:

package example27.controllers;

import java.util.Optional;

import org.springframework.http.HttpHeaders;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;

import example27.auth.AuthService;
import example27.auth.CaptchaService;
import example27.auth.LimiterService;
import example27.auth.UsersService.User;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@Controller
public class AuthController {

    private final AuthService auth;
    private final CaptchaService captchas;
    private final LimiterService limiter;

    public AuthController(AuthService auth, CaptchaService captchas, LimiterService limiter) {
        this.auth = auth;
        this.captchas = captchas;
        this.limiter = limiter;
    }

    @GetMapping("/")
    public String home() {
        return "redirect:/profile";
    }

    @GetMapping("/login")
    public String form(Model model) {
        return loginPage(model, null, null);
    }

    @PostMapping("/login")
    public String login(@RequestParam(required = false) String login,
            @RequestParam(required = false) String password, @RequestParam(required = false) String captchaId,
            @RequestParam(required = false) String captcha, HttpServletRequest request,
            HttpServletResponse response, Model model) {
        // o endereço IP do cliente
        String ip = request.getRemoteAddr();

        // 1. um endereço bloqueado nem sequer é ouvido
        long seconds = limiter.blockedSeconds(ip);
        if (seconds > 0) {
            return loginPage(model, 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(model, login, "The image code is incorrect.");
        }
        Optional<User> user = auth.validate(login, password);
        if (user.isEmpty()) {
            limiter.failure(ip);
            return loginPage(model, login, "Incorrect login or password.");
        }
        limiter.success(ip);
        response.addHeader(HttpHeaders.SET_COOKIE, auth.cookie(auth.createToken(user.get())).toString());
        return "redirect:/profile";
    }

    // cada exibição do formulário constrói um NOVO captcha
    private String loginPage(Model model, String login, String error) {
        model.addAttribute("login", login);
        model.addAttribute("error", error);
        model.addAttribute("captcha", captchas.generate());
        return "auth/login";
    }
}

Vamos comentar este código:

  • linha 48: o endereço IP do cliente, fornecido pela conexão de rede;
  • linhas 51–54: um endereço bloqueado nem sequer é ouvido;
  • linhas 56–59: o CAPTCHA é verificado primeiro e, só se estiver correto, a senha (uma operação [bcrypt] computacionalmente cara). Um CAPTCHA incorreto conta como uma falha;
  • linhas 71–76: a cada exibição do formulário, um novo CAPTCHA é gerado e colocado no template da view. Isso vale também para a primeira exibição (linhas 37–40).

O arquivo [templates/auth/login.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <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" th:value="${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" th:utext="${captcha.svg}">image</div>
      <!--/* o identificador do captcha viaja em um campo oculto; a resposta fica no servidor */-->
      <input type="hidden" name="captchaId" th:value="${captcha.id}">
      <input class="form-control" id="captcha" name="captcha" autocomplete="off" required>
    </div>
    <button class="btn btn-primary" type="submit">Log in</button>
  </form>
  <div class="alert alert-danger mt-3" th:if="${error != null}" th:text="${error}">error</div>
  <p class="text-muted small mt-3">Test accounts (password = login): marie (USER), admin (ADMIN).</p>
</main>
</body>
</html>
  • linha 18: a imagem SVG é texto (XML): ela é inserida na página tal como está. [th:utext] ([unescaped text]) insere o texto sem escape: os caracteres [<] e [>] continuam sendo tags (com [th:text], eles se tornariam [&lt;] e [&gt;], e a página exibiria o código da imagem). [th:utext] é válido aqui: trata-se de HTML gerado pelo servidor, não de entrada do usuário;
  • linha 20: o ID do CAPTCHA é passado em um campo oculto; a resposta, porém, permanece no servidor;
  • linha 21: [autocomplete="off"]: o navegador não sugere entradas anteriores, que são irrelevantes para um CAPTCHA.

O arquivo [config/SecurityConfig.java] é exatamente igual ao do Exemplo 25 (e não ao do Exemplo 26: aqui não há [@EnableMethodSecurity] nem tratador de acesso negado, já que nenhuma página é reservada a um papel específico). Em particular, a regra de acesso [/login] permanece inalterada: a página de login continua pública, e o CAPTCHA é verificado pelo controller, não pelo [Spring Security].

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

Image

Um CAPTCHA digitado incorretamente:

Image

Um novo CAPTCHA foi gerado. Reenviar um CAPTCHA já utilizado, mesmo digitado corretamente, resulta na mesma mensagem: a resposta foi removida do dicionário durante a primeira verificação. Após três tentativas malsucedidas, até a senha correta, junto com o CAPTCHA correto, é rejeitada durante 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 [application.properties] (propriedades [rdvmedecins.protection.*]).