Platforms, Microservices, DevOps and APIs · Hands-on 3

Hands-on 3 — Security

Log in once, get a signed JSON Web Token (JWT), and let the Gateway check it on every request

Who are you, and what can you do?

Requests to /accounts now arrive from the internet. Should every service check the user's password?

  • Authentication: verify who the user is → after login, issue a signed JWT valid for a limited time.
  • Authorization: verify what the user can access → the Gateway checks the JWT before routing.
  • One single entry point: services behind it never see an unauthenticated request.

Three modules

internet
→
gatewaythe only published port, :8080
→
authlogin, JWT, /auth/solve
→
accountpassword hash, db

gateway, auth and account: all inside the trusted layer (the Compose network).

Module Role
auth interface library: AuthController + DTOs LoginIn, RegisterIn, TokenOut
auth-service implementation: AuthResource, AuthService, JwtService; delegates accounts to account via Feign
gateway-service the single entry point of hands-on 2, now with AuthorizationFilter + RouterValidator

Same pattern as account / account-service: each one a git submodule under api/; the library is installed with mvn clean install.

JSON Web Token

Three Base64Url parts separated by dots: header . payload . signature — encoded, not encrypted

HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload),
            Base64.decode(JWT_SECRET_KEY) )   // 32 bytes = 256 bits
  • Header: the signing algorithm — JJWT writes only {"alg": "HS256"}.
  • Payload: the claims — statements about the user.
  • Signature: proves the token was issued by whoever holds the secret and was not altered.
  • Stateless: no server-side session, so it scales horizontally.

Anyone with the secret key can forge tokens: keep it in an environment variable, never hardcode it.

The claims this platform uses

Claim JJWT field Content
jti id the account's unique identifier
sub subject the account's name
iss issuer the issuing platform (Insper::PMA)
nbf notBefore valid from this timestamp
exp expiration expires at this timestamp

Plus a custom (private) claim: email. The payload is only encoded, not encrypted — anyone can read it.

The auth contract

@FeignClient(name="auth", url="http://auth:8080") · cookie name AUTH_COOKIE_TOKEN = "__store_jwt_token"

Method Path Does
POST /auth/register create: RegisterIn(name, email, password) → creates the account
POST /auth/login LoginIn(email, password) → sets the JWT cookie
GET /auth/logout clears the cookie
GET /auth/me header id-account → AccountOut
POST /auth/solve TokenOut(token) → { "idAccount": … } — internal, Gateway only
GET /auth/health-check 200 OK

Open vs. secured routes: RouterValidator

Register and login must be open — otherwise nobody could ever log in.

private List<String> openApiEndpoints = List.of(
    "POST /auth/register",
    "GET /auth/logout",
    "POST /auth/login");

public Predicate<ServerHttpRequest> isSecured = request ->
    openApiEndpoints.stream().noneMatch(/* method and path match, /** = prefix */);

Secured by default: everything not in the list — including all /accounts/** — needs a valid cookie.

auth-service

Class Responsibility
AuthApplication @EnableFeignClients(basePackages = "store.account")
AuthResource implements AuthController; writes the cookie on login/logout
AuthService registers via account (AuthParser → Register); on login, POST /accounts/login checks the credentials, then asks for a token
JwtService signs and parses JWTs with the JJWT library (HMAC key: 256-bit secret → HS256)
store:
  jwt:
    secretKey: ${JWT_SECRET_KEY:EBwrdOOcAIDRLON9hbJV0+O3PTdfTjgMCQIxwLH7ws8=}
    httpOnly: ${JWT_HTTP_ONLY:true}
    duration: ${JWT_DURATION:3600000} # 1 hour in milliseconds

Checking credentials in account

auth-service never checks a password: account gains POST /accounts/login (AccountController.login).

// account-service: AccountService (calcHash already exists)
public Account findByEmailAndPassword(String email, String password) {
    if (password == null || password.isEmpty())
        throw new ResponseStatusException(BAD_REQUEST, "Password is empty");
    final String hash = calcHash(password);
    return accountRepository.findByEmailAndHashPassword(email, hash)
        .map(AccountModel::to)
        .orElseThrow(() -> new ResponseStatusException(
            UNAUTHORIZED, "Invalid credentials"));
}
  • findByEmailAndHashPassword: a Spring Data derived query in AccountRepository. The endpoint answers 200 + AccountOut, or 401.
  • The hash never leaves account; AuthService.login turns FeignException.Unauthorized / BadRequest into 401.
  • AccountController changed: run mvn clean install in api/account again.

JwtService.generate

public String generate(AccountOut account, long duration) {
    Date now = new Date();
    return Jwts.builder()
        .id(account.id())
        .issuer("Insper::PMA")
        .claims(Map.of("email", account.email()))
        .signWith(getKey())  // Keys.hmacShaKeyFor(Base64-decoded secretKey)
        .subject(account.name())
        .notBefore(now)
        .expiration(new Date(now.getTime() + duration))
        .compact();
}

JwtService.getId

public String getId(String jwt) {
    try {
        JwtParser parser = Jwts.parser().verifyWith(getKey()).build();
        // checks the signature, nbf and exp: a JwtException otherwise
        Claims claims = parser.parseSignedClaims(jwt).getPayload();
        return claims.getId();
    } catch (JwtException e) {
        throw new ResponseStatusException(
            HttpStatus.UNAUTHORIZED, "Invalid token");
    }
}

This is what /auth/solve runs: a valid token becomes an idAccount; a bad or expired one, a 401 (not a 500).

  1. POST /auth/login → AuthService.login → POST /accounts/login (hash check, or 401) → JwtService.generate.
  2. AuthResource answers with Set-Cookie: __store_jwt_token=<jwt>.
  3. The browser stores it and sends it automatically on every later request.
Flag Value Why
HttpOnly true JavaScript cannot read it → mitigates XSS (unlike localStorage)
Secure true sent only over HTTPS
SameSite None sent on cross-site requests (SPA frontends)
Path / valid for all paths

Browsers reject SameSite=None without Secure: in production, frontend and API must use HTTPS.

The Gateway decides: AuthorizationFilter

A GlobalFilter: every request passes through it before routing.

request
→
isSecured?RouterValidator
yes →
cookie__store_jwt_token
→
POST /auth/solvesignature, nbf, exp
→
+ id-accountthe jti, then forward
open routeregister, login, logout: forward as is
no cookie401 Unauthorized
invalid or expired token401, kept by onStatus(4xx)

An id-account sent by the client is dropped first (RemoveRequestHeader): nobody can pose as another account.

AuthorizationFilter.filter

public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    ServerHttpRequest request = exchange.getRequest();
    if (!routerValidator.isSecured.test(request)) {
        return chain.filter(exchange);
    }
    HttpCookie cookie = request.getCookies().getFirst(AUTH_COOKIE_TOKEN);
    if (cookie == null || cookie.getValue().isBlank()) {
        return Mono.error(new ResponseStatusException(HttpStatus.UNAUTHORIZED));
    }
    return requestAuthTokenSolve(exchange, chain, cookie.getValue().trim());
}

Spring Cloud Gateway is reactive (WebFlux): the filter returns Mono<Void>, so a missing cookie is a Mono.error, not a throw; it calls auth with WebClient, not RestTemplate.

requestAuthTokenSolve: one WebClient, built once

// constructor: built once from the injected WebClient.Builder, reused by every request
this.authClient = builder.baseUrl("http://auth:8080").build();

return authClient.post().uri("/auth/solve").bodyValue(Map.of("token", jwt))
    .retrieve()
    .onStatus(HttpStatusCode::is4xxClientError,
        r -> Mono.error(new ResponseStatusException(HttpStatus.UNAUTHORIZED, "Invalid token")))
    .bodyToMono(new ParameterizedTypeReference<Map<String, String>>() {})
    .timeout(Duration.ofSeconds(3))
    .flatMap(map -> chain.filter(updateRequest(exchange, map.get("idAccount"))));
auth answers 200
auth answers 4xx
auth silent for 3 s
gateway
+ id-accountforward to the route
401onStatus, not a 500
timeoutfails, holds no request

The client is thread-safe: the injected builder adds metrics (http_client_requests) and tracing. spring-boot-starter-webclient in the pom: Spring Boot 4 moved it out of WebFlux.

Wiring: routes and Compose

default-filters:
  - RemoveRequestHeader=id-account
routes:
  - id: account-service
    uri: http://account:8080
    predicates:
      - Path=/accounts/**
  - id: auth-service
    uri: http://auth:8080
    predicates:
      - Path=/auth/**
  • New service: auth (after gateway, hands-on 2).
  • Only gateway publishes port 8080; auth stays inside.
  • auth runs on defaults: JWT_SECRET_KEY, JWT_HTTP_ONLY, JWT_DURATION.
  • gateway: CORS_ALLOWED_ORIGINS has a default too.

The default key is public (it is in the repo): outside dev, set JWT_SECRET_KEY to your own — openssl rand -base64 32.

Test it

docker compose up -d --build

curl -X POST http://localhost:8080/auth/register -H "Content-Type: application/json" \
  -d '{"name": "Antonio do Estudo", "email": "acme@insper.edu.br", "password": "123@321"}'

curl -c cookies.txt -X POST http://localhost:8080/auth/login -H "Content-Type: application/json" \
  -d '{"email": "acme@insper.edu.br", "password": "123@321"}'

curl -b cookies.txt http://localhost:8080/accounts   # 200 — cookie sent
curl http://localhost:8080/accounts                  # 401 — no cookie

Common pitfalls

  • Wrong credentials → 500: a bare .orElseThrow() throws NoSuchElementException; throw a 401.
  • Expired cookie → 500: getId must catch JwtException; the filter's onStatus keeps the 401.
  • Build fails after login: reinstall the account library before account-service and auth-service.
  • Cookie ignored: SameSite=None without Secure is rejected by the browser.
  • Leaky health check: /health-check is not a route, the filter does not run there — return only the hostname.

The default JWT_SECRET_KEY is in the repository: anyone could forge tokens for a deployment that keeps it.

Without Docker: the simulator

Authorization 5 (test)200, 200, 200, 401 · the JWT page's token, byte for byte
bad tokenswrong password, forged id-account, edited payload
forged with the default key200 as another user, until JWT_SECRET_KEY is yours
  • Each button is a curl of the lab through the Gateway; the boxes light up along the path.
  • The tokens are real HS256 JWTs signed with the key of application.yaml: paste one into jwt.io.
  • Past the cookie's Max-Age, curl stops sending it; sent by hand, the token meets ExpiredJwtException.

Takeaways

  1. Authentication issues a signed JWT; authorization checks it on every request.
  2. A JWT is header.payload.signature; the secret key is what makes it trustworthy.
  3. account checks the password hash (POST /accounts/login); JwtService signs jti, sub, iss, nbf, exp, email.
  4. The token travels in an HttpOnly, Secure cookie: __store_jwt_token.
  5. RouterValidator: only register, login and logout are open — secured by default.
  6. AuthorizationFilter resolves the token via /auth/solve and forwards id-account.
  7. Downstream services never parse JWTs; bad credentials or tokens are a 401, never a 500.

Outline: (1) authentication × authorization; (2) JWT and its claims; (3) the auth interface and the open routes; (4) auth-service and the credential check in account; (5) the cookie; (6) AuthorizationFilter at the gateway; (7) compose, testing and pitfalls.

Let the class answer first: checking credentials in every service multiplies the attack surface and the code.

Plain SHA-256 keeps the course simple; production uses a slow, salted algorithm (bcrypt, Argon2, Spring Security's PasswordEncoder).

Stress: downstream services never parse JWTs; they just read the id-account header.

A WebClient.builder()...build() inside filter() also works, but repeats the setup on every secured request. It is waste, not a memory leak: we measured 4 rounds, about 510 thousand requests, and the live heap after a full GC stayed flat. What grows in docker stats is the heap the JVM reserves (up to 25% of the host without a limit), not a leak.

The simulator sits on the overview (bad tokens) and in section 5 of Authorization (the page's four commands).