CicloUrbana already knows who each citizen of Ribalta is, but it asks in a way that does not stand up to real use. With HTTP Basic, the mobile application has to store Marta's password and send it on every request: when opening the map, when looking up a station, when starting a rental. The user's most valuable credential travels the network dozens of times a day, the server computes a ninety-millisecond BCrypt on every one of them, and there is no way to expire access without forcing a password change.

This lesson solves it with the standard pattern of modern APIs: the password is sent just once, and in exchange the server issues a signed, expirable token that the client then presents in the Authorization: Bearer header. We will look at exactly what a JWT is field by field, we will implement it with JJWT and a filter of our own, we will add refresh tokens with rotation and database revocation, and we will face honestly the two uncomfortable questions of the stateless model: where the client stores the token and what signing out really means.

Warning. Every secret, key and token in this lesson is fictional and truncated; none of them should be reused. The signing secret is never written into the repository: it is injected through an environment variable or a secrets manager. And a home-grown JWT implementation, even one using a solid library, must be reviewed by a security professional before being exposed to the internet; section 15 explains the alternative that avoids writing this code at all.

1. Why a mobile app needs stateless authentication
2. Cookie session versus token: the honest comparison
3. Anatomy of a JWT
4. The claims: standard ones and CicloUrbana's own
5. Signing algorithms: HS256 versus RS256
6. Signed is not encrypted
7. JJWT and JwtProperties
8. JwtService: generate, read and validate
9. JwtAuthenticationFilter
10. Registering the filter in the security chain
11. POST /api/v1/auth/login
12. Refresh tokens: rotation and revocation
13. Signing out in a stateless world
14. Where the client stores the token
15. Documenting the scheme in OpenAPI and the production alternative
16. Testing the complete flow with curl
17. Common Mistakes and Tips
18. Exercises

The classic alternative to the token is the server-side session: the user signs in once, the server keeps their state in memory and hands them a cookie with an identifier. It works very well for a traditional website and very badly for CicloUrbana:

• The client is not a browser. A mobile application does not handle cookies naturally, and browsers' third-party policies make the web scenario more complicated all the time.
• The session lives on one instance. With three replicas behind a load balancer, Marta's session is on number 2 and the other two know nothing about it: the ways out are sticky sessions (fragile) or replication (expensive). With a token, any instance serves any request.
• It contradicts the REST constraint from 03-01, which demands that every request contain all the information needed, and it consumes memory in proportion to the number of connected users.

The stateless solution inverts the storage: the state travels with the client, signed by the server so that it cannot be tampered with. The server remembers nothing; it only verifies a signature.

The JWT's three drawbacks must be stated without embellishment, because they are almost never mentioned:

It cannot be revoked easily. A stolen token is valid until it expires and there is nothing on the server that invalidates it: if Marta loses her phone, her token keeps working. The main defence is a short expiry, and that is why section 12 introduces refresh tokens. It takes up space: a JWT with roles is around 400 bytes travelling on every request, a real cost over a mobile connection. And it is dangerous if stored badly: keeping it in localStorage makes it readable by any JavaScript on the page, so an XSS goes from being an annoying problem to a complete identity theft (section 14).

A JWT is not always the best option. For a classic web application with server-side views, the cookie session is still simpler and safer. CicloUrbana chooses the token because its client is mobile and its API is stateless, not because it is modern.

A JSON Web Token (RFC 7519) is three blocks encoded in Base64URL and separated by dots:

Decoding the first two blocks —which is trivial: echo '<block>' | base64 -d— yields JSON:

And the third block, the signature, is computed like this:

Base64URL is not encryption: it is a reversible encoding that exists only so that the token can travel without problematic characters in a URL or a header. Anyone can read the payload; what nobody can do without the secret is produce a valid signature. Verification works like this:

If an attacker changes "roles":["ROLE_CITIZEN"] to "roles":["ROLE_ADMIN"], the payload changes, the recomputed HMAC no longer matches the signature that accompanies the token and the server rejects it. They cannot recompute the correct signature because they do not have the secret.

Each field of the payload is a claim, an assertion about the subject. The RFC defines seven registered ones:

The first three matter more than they seem to. Validating iss and aud prevents a token issued by another system —or for another service in the same organisation— from being accepted here, a real and frequent failure in architectures with several services; and jti is what makes a revocation list possible (section 13). To these CicloUrbana adds two claims of its own:

Every claim you add is a commitment. It enlarges the token and, above all, freezes a piece of data: if an administrator removes the OPERATOR role from Luis, his token keeps saying he has it until it expires. With a fifteen-minute lifetime that is acceptable; with twenty-four hours it is not. It is the limitation we anticipated in exercise 3 of 05-03, and the underlying reason why the access token must be short.

CicloUrbana uses HS256, because today the same application issues and verifies the tokens and a shared secret is the simplest and perfectly secure solution in that scenario. You must switch to RS256 as soon as more than one service needs to verify: with HS256, whoever can verify can also issue, so sharing the secret with five microservices means five teams can manufacture administrator tokens. With RS256 the services receive only the public key and verify without being able to forge. That is the module 7 scenario, and the reason identity providers always use asymmetric algorithms.

The alg: none vulnerability. Early JWT implementations accepted a token whose header declared "alg":"none" and took it as valid with no signature. An attacker only had to strip the signature and change the header. Another variant consisted of changing RS256 to HS256 so that the server used the public key as the HMAC secret —a key the attacker knows. The defence is the same in both cases: the expected algorithm is decided by the server, never by the token. JJWT 0.12 does this correctly if you use verifyWith(key), which pins the algorithm from the key type. Never write code that reads alg from the header to decide how to verify.

Highlighted warning. A JWT's payload is readable by anyone who has the token: all it takes is decoding Base64URL, with no secrets and no tools. The signature guarantees integrity and authenticity, not confidentiality.

What must never go into a JWT:

• Passwords or password hashes.
• National ID numbers, postal addresses, phone numbers, health data or any sensitive personal data.
• Card numbers, banking details, API keys, internal secrets or infrastructure paths.
• Confidential commercial information, such as the accumulated amount of the rentals.

What is reasonable: the user's identifier, their email if the service treats it as a public identifier, their roles and the timestamps. The practical rule: if you would not write it on a postcard, do not put it in a JWT. When confidentiality really is needed there is JWE (JSON Web Encryption), which encrypts the payload; it is markedly more complex, and the usual solution is simpler: do not put the data in the token and look it up on the server when it is needed.

All three are necessary and the split is deliberate: jjwt-api holds the interfaces and is the only one you compile against; jjwt-impl and jjwt-jackson are implementations in runtime scope, which prevents your code from coupling to internal details. If a ClassNotFoundException about DefaultJwtBuilder shows up, jjwt-impl is missing. And beware: JJWT is not managed by the spring-boot-starter-parent, so the version has to be pinned by hand and reviewed periodically (05-05).

The configuration, with typed @ConfigurationProperties as in 02-05:

Four important decisions:

The secret comes from an environment variable. ${JWT_SECRET} with no default value: if the variable does not exist, the application does not start, which is exactly what we want. Writing a default secret into the YAML is worse than having no security, because it creates a false sense of having some: it ends up in Git, in the Docker image and on every team member's laptop, and that same value ends up in production with alarming frequency.

@Size(min = 43) is not arbitrary. HS256 requires a key of at least 256 bits, which in Base64 is 43 characters; JJWT rejects shorter keys with WeakKeyException, and validating it at startup turns that runtime failure into a comprehensible configuration error. A suitable secret is generated, never invented:

The compact constructor validates the policy, not only the format: somebody configuring expiration: 24h is not a type error but it is a security one, and startup prevents it. And the secret is rotated, like any credential: in production it lives in a secrets manager (Vault, AWS Secrets Manager, Kubernetes secrets) and is changed periodically, in the knowledge that rotating it invalidates every token in circulation.

Five details that make this code correct and not merely functional:

1. verifyWith(key) pins the algorithm from the key type. That is what closes the door on alg: none and on the RS256/HS256 confusion from section 5.
2. requireIssuer and requireAudience reject tokens from elsewhere. They are almost always forgotten.
3. clockSkewSeconds(30) tolerates clock drift between machines. Without it, two servers two seconds apart produce intermittent rejections that are impossible to reproduce. And the injected Clock —the bean from 03-03— will make it possible to test expiry in module 6 without waiting fifteen minutes.
4. An expired token is logged at DEBUG; an invalid signature, at WARN. The first is normal operation; the second may be an attack, and mixing them makes the log useless (09-05).
5. The token is never logged: a token in a log is a credential in a log. And .audience().add(...).and() is the JJWT 0.12 fluent API, which changed with respect to 0.11, so a lot of code from the internet will not compile against this version.

The filter is the piece that turns an HTTP header into an authenticated user. It extends OncePerRequestFilter, just like the TraceFilter from 03-06, to guarantee a single execution per request even when there are internal forwards.

Five decisions worth understanding:

The filter never rejects the request. If there is no token, or it is invalid, it simply does not authenticate and lets the chain continue: the one who decides whether that request needed authentication is the AuthorizationFilter from 05-01, and the one who produces the 401 is the AuthenticationEntryPoint from 05-03. This separation is what allows GET /api/v1/stations to remain public while /api/v1/rentals is not, with the same filter.

The database is not queried: all the information —id, email, roles— comes from the token. That is what makes the model stateless and fast, and also what freezes the roles until expiry; the alternative, loading the UserDetails on every request, is safer and sacrifices most of the advantage.

Whether there is already an authentication is checked before writing into the context, so as not to trample another mechanism's. AuthenticatedUser needs a second constructor taking id, email and authorities, with no entity and no hash: getPassword() will return null and that is fine, because on this path nobody compares passwords. And the details are stored with the IP: valuable information for the auditing from 05-03.

addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class) places the filter at a specific position in the 05-01 chain: after SecurityContextHolderFilter and CorsFilter —so the context is clean and CORS preflight requests have already been resolved— and before ExceptionTranslationFilter and AuthorizationFilter, which is the essential part: by the time authorisation evaluates the rules, the context must already hold the user. And here httpBasic and formLogin disappear, exactly as we announced in 05-02: from now on the only way to authenticate against the API is a token.

The controller is a @PostMapping("/login") in the AuthController from 05-03 that receives @Valid @RequestBody LoginRequest and returns 200 OK with the TokenResponse.

Three points. Authentication is not reimplemented: it is delegated to the AuthenticationManager, which already knows how to compare hashes in constant time, check whether the account is active and publish the failure events; rewriting an if (encoder.matches(...)) here would lose all of that. If it fails it throws BadCredentialsException, which must be translated into a uniform 401 in GlobalExceptionHandler —this one does see it, because it happens inside a controller. And the response reveals nothing about the user: only tokens.

There is an obvious tension. A short access token limits the damage of a theft, but it forces the citizen to type their password every fifteen minutes. A long one is convenient and dangerous.

The solution is two tokens with different roles:

The refresh token is not a JWT, and that is deliberate: since the server stores it anyway in order to be able to revoke it, there is no advantage in it being self-contained, and a long random string is shorter, more opaque and reveals nothing.

The SHA-256 of the token is stored, not the token, by the same reasoning as with passwords: if somebody reads the table, they do not obtain usable credentials. A fast hash is enough here, because the token is a random 256-bit string and not a password guessable from a dictionary. The refresh endpoint, with rotation:

Four key ideas:

Rotation: every use of the refresh token invalidates it and issues a new one. It reduces the window of a stolen token and, above all, makes the theft detectable.

Reuse detection: if an already revoked token arrives, either it is the thief using one the victim has already rotated, or the other way round; there is no way to know which, so all of that user's refresh tokens are revoked and they are forced to authenticate again. It is annoying and it is the right thing to do.

The roles are reloaded from the database, and that is the moment when the privilege change from exercise 3 of 05-03 takes effect: at most fifteen minutes later. The error message is always the same, whether the token does not exist, is revoked or has expired. And one operational piece is missing: a scheduled task that deletes the expired ones, or the table grows without limit (07-03).

POST /api/v1/auth/logout cannot invalidate the access token. It is signed, it is valid and the server keeps nothing about it. The real options:

CicloUrbana implements signing out as revoking the refresh token: the access token remains valid for up to fifteen minutes and then cannot be renewed. It is a conscious decision, and we must be honest about what it means: during those fifteen minutes, a stolen token keeps working.

When that is not tolerable —a banking operation, a sign-out on suspicion of compromise— the solution is a revocation list of the jtis in a fast cache such as Redis, with automatic expiry when the token expires; consulting it on every request reintroduces state, but bounded state, and distributed caching is covered in 09-02. In any case, the main defence remains the short expiry: everything else is mitigation.

This is the part of the system the backend does not control and where most real incidents happen.

Warning. localStorage is the most repeated piece of advice on the internet and the worst. Any XSS —a compromised JavaScript dependency, a badly escaped field— allows the token to be read and the user impersonated from another machine. An HttpOnly cookie is not readable by JavaScript, not even with an XSS.

CicloUrbana's mobile app, which is the main client, uses the system keychain: Keychain on iOS, EncryptedSharedPreferences or Keystore on Android. For the council's web panel the recommendation is the HttpOnly; Secure; SameSite=Strict cookie with CSRF protection switched back on —remember the warning from 05-02: once the credential goes back into a cookie, the condition that allowed CSRF to be disabled no longer holds— or else the mixed pattern of an access token in memory and a refresh token in an HttpOnly cookie. And in every case, HTTPS is mandatory: without TLS all of the above is irrelevant, because the token travels readable across the network (05-05).

The Swagger UI from 03-07 stopped working against the protected endpoints: it has nowhere to type the token. It is fixed by declaring the security scheme in OpenApiConfig:

The Authorize button then appears in the interface and springdoc adds the header to every call; the public endpoints are marked with an empty @SecurityRequirements so that the documentation does not lie.

All the code in this lesson is a home-grown implementation: excellent for understanding the mechanism, and in a real system it is better not to write it. Spring offers a maintained, audited module:

With those lines JwtService, JwtAuthenticationFilter and secret management all disappear: the BearerTokenAuthenticationFilter from 05-01 takes care of it using Nimbus underneath, and the public keys are obtained from the provider's JWKS and rotated automatically.

The criterion: if the system has a single service, one client and simple requirements, a home-grown implementation with a solid library is acceptable. As soon as several services, sign-in with external providers, a second factor or regulatory compliance requirements appear, use an identity provider. The cost of maintaining your own security grows far faster than it looks.

Steps 5 and 7 are the important ones: 5 proves that the token is readable by anyone —hence the warning in section 6— and 7, that it is not modifiable.

Putting sensitive data in the payload. It is signed, not encrypted: a national ID number in a JWT is a public national ID number.

Writing the secret into application.yml, or using a short, invented one. A secret in the YAML ends up in Git, in the image and on every team member's laptop; and mysecret123 does not reach 256 bits. Use an environment variable with no default, generated with openssl rand -base64 48. And no 24-hour access tokens "so it does not get in the way": they multiply the window of a theft by 96 and freeze the roles for that whole time.

Having the filter return 401 directly, or registering it at the wrong position in the chain. The first breaks the public endpoints —the filter authenticates if it can, and the decision belongs to the AuthorizationFilter—; the second, if it ends up after AuthorizationFilter, makes everything return 401.

Not validating iss or aud, which means a token issued by another system with the same secret would be accepted; or reading alg from the token to decide how to verify, which is the alg: none vulnerability. The algorithm is pinned by the server.

Storing the refresh token in the clear in the database, or logging any token even truncated. A token is a credential; store its SHA-256 and never write it down.

Tip: short expiry plus refresh with rotation —15 minutes of access, 30 days of rotating refresh with reuse detection— is the balance that works. And use the injected Clock in JwtService: in module 6 you will be able to test expiry by moving the clock forward instead of waiting.

A CicloUrbana token has this payload. Spot four security or design problems and propose the corrected version.

Implement JwtService.validate(String) so that it distinguishes three results —valid token, expired token and invalid token— through a type of your own instead of an Optional, and explain what the filter must do with each and which log level it corresponds to.

Design the complete flow for this council requirement: "when a citizen changes their password, all their open sessions on other devices must be closed immediately". Bear in mind that the access token cannot be revoked.

Solution 1

Problem 1 — nationalId. Identifying personal data, readable by anyone with the token and subject to GDPR. Out. Problem 2 — passwordHash, the most serious failure: it hands the hash to anyone who captures the token, allowing a dictionary attack with no attempt limit and leaving no trace on the server. Out, always.

Problem 3 — totalSpent. Confidential commercial data and, on top of that, a piece of data that changes: it would be frozen until expiry and would show stale figures if the client trusted it. It is looked up through the API. Problem 4 — a seven-day expiry (exp - iat = 604,800): a stolen token is good for a week, and role changes take a week to apply. iss, aud and jti are also missing, and without them the provenance cannot be validated nor can the token be revoked by identifier.

The rule for deciding what goes in: only what is needed on every request in order to authorise, does not change during the life of the token and would not be a problem on a postcard. The name could stay if the app displays it —it is not sensitive— but it fattens the token: it is better to ask for it once from /api/v1/users/me.

Solution 2

What the filter does with each case. Valid: it authenticates. Expired: it does not authenticate, but it is not an error either; it is normal operation every fifteen minutes, it goes to DEBUG, and the hint header lets the mobile app tell "renew the token" from "sign in again" without exposing anything. Invalid: it does not authenticate and it goes to WARN, because an incorrect signature is either a tampering attempt or a broken client, and a spike of these events should trigger an alert (09-05). The advantage of the sealed type over the Optional is that it is impossible to forget a case: a switch over a sealed interface must be exhaustive or it does not compile, and in the module 6 tests you can assert on the exact reason.

Solution 3

The problem: the access token on the other devices is valid and there is nothing on the server that invalidates it; revoking the refresh tokens closes the future door, but leaves up to fifteen minutes of live access. Complete solution, in four pieces. 1. An invalidation marker on the user, with a V7__add_token_invalidation.sql migration that runs ALTER TABLE users ADD COLUMN tokens_invalid_before TIMESTAMPTZ;. 2. When changing the password, in the same transaction: store the new hash, set tokensInvalidBefore = now and revoke all of that user's refresh tokens. 3. A check in the filter, taking advantage of the fact that the token's iat says when it was issued: if it is earlier than the marker, the token dies.

4. The cost, and how to pay it. This reintroduces one query per request, exactly what the stateless model was avoiding. Three ways to soften it, from least to most effort: cache the marker per user with a short expiry (09-02); keep in cache only the users with a recent invalidation, which are very few indeed, and treat absence as "no invalidation"; or include the marker as a claim in the token, although then it only protects from the next refresh onwards and does not meet the requirement.

The underlying lesson: the requirement "sign out immediately everywhere" is incompatible with purely stateless authentication. Every solution pays with state on the server. The honest thing is to acknowledge it, choose where the price is paid and document it, not to pretend that JWT solves everything. And it is worth asking first whether "immediately" really means zero seconds or whether fifteen minutes are acceptable: the answer changes the architecture completely.

CicloUrbana now authenticates like a modern API. You know why a mobile application needs stateless authentication —the client is not a browser, the session does not survive the load balancer and the REST constraint from 03-01 demands it— and you have compared session and token honestly, without hiding the JWT's three real drawbacks: it is not easily revoked, it takes up space on every request and it is dangerous if the client stores it badly. You also know that for a classic website with server-side views the cookie session is still the simplest and safest option: CicloUrbana chooses the token because of its requirements, not because of fashion.

You know a JWT from the inside: header, payload and signature in Base64URL, the HMAC that ties the first two parts to the server's secret, and the central fact that Base64URL is not encryption. You handle the registered claims —iss, sub, aud, exp, iat, jti— and the project's own two, roles and userId, knowing that each of them enlarges the token and freezes a piece of data until expiry. You have compared HS256 with RS256 and you know when it forces an architecture change: as soon as a second service has to verify, because with a shared secret whoever verifies can also issue. And you know the alg: none vulnerability and its defence: the algorithm is decided by the server, never by the token.

You have implemented the complete system with JJWT 0.12: the three dependencies with their scopes, JwtProperties validated with a secret arriving through an environment variable and with no default value —so that the application does not start if it is missing— with a minimum length of 43 Base64 characters and a policy check that prevents configuring tokens lasting more than an hour. JwtService generates, extracts and validates with verifyWith, requireIssuer, requireAudience, clock tolerance and an injected Clock that will make it possible to test expiry in module 6. JwtAuthenticationFilter, a OncePerRequestFilter registered with addFilterBefore in front of UsernamePasswordAuthenticationFilter, never rejects: it authenticates if it can and leaves the decision to the AuthorizationFilter, which is exactly what allows public and protected endpoints to coexist in the same chain. And with POST /api/v1/auth/login delegating to the AuthenticationManager from 05-03, HTTP Basic and the login form have disappeared from the configuration.

You have added refresh tokens with the refresh_tokens table from the V6 migration, which stores the SHA-256 of the token and not the token, with rotation on every use, reuse detection that revokes all of the user's sessions at the first sign of theft, and roles reloaded from the database on every refresh. And you have looked squarely at the two problems that JWT marketing tends to hide: signing out in a stateless world means revoking the refresh token and accepting up to fifteen minutes of live access, or paying with state through a revocation list by jti; and storage on the client, where localStorage is the most repeated advice and the worst, against the system keychain in the mobile app and the HttpOnly; Secure; SameSite cookie —with CSRF switched back on— in the web panel. The Swagger UI from 03-07 works again with its Authorize button, and you know the mature alternative for production: spring-boot-starter-oauth2-resource-server with an identity provider that rotates its keys through JWKS and brings SSO and a second factor as standard.

One hole remains, and it is the same one we noted in 05-01 and 05-03. Marta has a valid token with the ROLE_CITIZEN role, so POST /api/v1/rentals/9/finish passes every rule in the chain: the path is legitimate and the role is correct. But rental number 9 belongs to another citizen. No URL-based rule can express "only your own rentals", because the answer depends neither on the path nor on the role, but on the data. It is the A01/BOLA risk from the OWASP Top 10, the most exploited one in REST APIs. In 05-05, Method-Level Security and API Hardening, we will take security down to the service layer with @EnableMethodSecurity, @PreAuthorize and SpEL expressions, we will write a permission evaluator of our own for the rentals rule, and we will close the module by hardening the whole API: CORS per environment, rate limiting, mandatory HTTPS, hiding the documentation in production, auditing security events, reviewing vulnerable dependencies and a checklist before going to production.