DEV Community: TeKa IT

Why You Should Hash Refresh Tokens with SHA-256

TeKa IT — Sat, 03 Oct 2026 11:31:46 +0000

Refresh tokens are often treated as an implementation detail.

Generate a random string, store it in the database, return it to the client, and use it later to issue a new access token.

It works.

But there is an important security question hiding in that design:

What happens if someone gets read access to your refresh-token database?

If the database contains the actual refresh tokens, the answer is uncomfortable.

An attacker who can read the database may be able to use those tokens immediately.

That is why refresh tokens should generally be treated like other authentication secrets: the server should be able to verify them without storing the original value in plaintext.

In this article, we'll build that idea from first principles and implement it with SHA-256.

We'll look at:

why storing refresh tokens in plaintext is risky
why hashing is useful for refresh tokens
why SHA-256 is appropriate for high-entropy tokens
why BCrypt is the wrong tool for this particular job
how to generate cryptographically random refresh tokens
how to hash and validate them in Spring Boot
how hashing fits together with refresh-token rotation
what hashing does — and does not — protect you from

The important distinction throughout this article is this:

Passwords and refresh tokens are both secrets, but they have very different security properties.

1. A Refresh Token Is a Bearer Secret

Consider a typical authentication flow.

A user logs in and receives:

access token
refresh token

The access token might be a JWT:

eyJhbGciOiJIUzI1NiJ9...

The refresh token is usually just an opaque random value:

V4Z8v2mQ4Qm7Qe7z...

The client later sends the refresh token to an endpoint such as:

POST /api/auth/refresh

The server validates it and issues a new access token.

The important property is that the refresh token is a bearer credential.

Whoever possesses a valid refresh token can potentially use it.

There is no username and password challenge attached to the token.

There is no proof that the person presenting the token is the original user.

Possession is the credential.

That means this:

refresh token = authentication secret

And that leads directly to the database question.

If the database contains:

V4Z8v2mQ4Qm7Qe7z...

then anyone who obtains that value may have obtained an authentication credential.

A database dump therefore becomes more than a data confidentiality problem.

It can become a session hijacking problem.

2. Why Plaintext Storage Is Unnecessary

Suppose the server generates this refresh token:

RANDOM_SECRET

The client receives:

RANDOM_SECRET

But the database does not actually need to know the original value.

The server only needs to answer one question later:

"Does the refresh token presented by the client correspond to a valid token stored in the database?"

That means we can store a one-way representation instead:

RANDOM_SECRET
      |
      v
   SHA-256
      |
      v
HASHED_VALUE

When the client later sends the refresh token:

RANDOM_SECRET

the server performs the same transformation:

RANDOM_SECRET
      |
      v
   SHA-256
      |
      v
HASHED_VALUE

Then it compares the resulting hash with the value stored in the database.

The original refresh token never needs to be stored.

This changes the security properties of a database compromise.

Plaintext storage

Database:

refresh_token
--------------------------------
V4Z8v2mQ4Qm7Qe7z...

If an attacker reads the database, they have the token.

Hashed storage

Database:

token_hash
----------------------------------------------------------------
9f86d081884c7d659a2feaa0c55ad015...

The database contains a verifier rather than the credential itself.

That distinction matters.

OWASP's session-management guidance explicitly describes storing a one-way verifier for random session tokens when read-only disclosure of the session store is part of the threat model. It also notes that fast hashing is sufficient for these random verifiers.

3. But Why SHA-256?

This is where refresh tokens differ from passwords.

A common reaction is:

"We're storing something sensitive. Shouldn't we use BCrypt?"

Not necessarily.

In fact, using BCrypt for refresh tokens is usually solving the wrong problem.

To understand why, we need to look at the difference between a password and a randomly generated token.

4. Passwords Are Low-Entropy Secrets

Passwords are chosen by humans.

That creates a problem.

Consider:

password123

An attacker can make educated guesses.

They can try:

password
password1
password123
qwerty
letmein
summer2026
...

Even a reasonably long human-generated password may have much less entropy than its length suggests.

That's why password hashing algorithms deliberately make every guess expensive.

BCrypt, Argon2 and PBKDF2 are designed to make password guessing computationally expensive.

For example:

password
    |
    v
   BCrypt
    |
    v
stored password hash

The cost of BCrypt is a feature.

You want attackers to pay a significant computational price for every password guess.

Spring Security's BCryptPasswordEncoder is specifically designed around this model and deliberately uses a work factor to make password hashing expensive.

5. Refresh Tokens Should Have High Entropy

A properly generated refresh token has a very different property.

It should not be:

refresh-token-123

or:

user-42-refresh-token

or:

a8f3c91

Instead, generate it using a cryptographically secure random number generator.

For example:

SecureRandom secureRandom = new SecureRandom();

byte[] bytes = new byte[32];
secureRandom.nextBytes(bytes);

String refreshToken = Base64.getUrlEncoder()
        .withoutPadding()
        .encodeToString(bytes);

Here we generate:

32 random bytes

That's:

256 bits

of random input.

The important property isn't the string length.

It's the entropy.

If the token is generated correctly, an attacker cannot realistically predict the next valid token.

OWASP's session-management guidance similarly emphasizes that reference tokens should be generated using a cryptographically secure random number generator and have sufficient entropy.

So the security problem is no longer:

"How do we make every hash calculation expensive?"

The problem becomes:

"How do we prevent someone who can read our database from immediately obtaining the original bearer secret?"

That's exactly where SHA-256 fits.

6. SHA-256 Is Fast — and That's Fine Here

SHA-256 is designed to be fast.

For passwords, that is a problem.

For a high-entropy random token, it is not.

Consider the two scenarios.

Password

human password
      |
      v
slow password hash
      |
      v
database

The slow algorithm makes offline guessing expensive.

Refresh token

256-bit random token
      |
      v
SHA-256
      |
      v
database

The token itself is already designed to make guessing infeasible.

SHA-256 does not need to make guesses expensive because there should be no realistic sequence of guesses to make.

This is an important security principle:

The correct hashing algorithm depends on the properties of the secret being protected.

Don't blindly apply password-storage rules to every secret.

7. SHA-256 vs BCrypt

The difference becomes clearer when we compare them directly.

Property	Password	Refresh Token
Usually created by	Human	Server
Predictability	Potentially high	Should be extremely low
Entropy	Variable	High
Brute-force resistance	Needs slow hashing	Primarily comes from randomness
Appropriate hashing strategy	Argon2id / BCrypt / PBKDF2	Fast cryptographic hash such as SHA-256
Main goal	Make guessing expensive	Store a verifier without storing the secret

BCrypt is not "more secure" simply because it is slower.

It is optimized for a different problem.

Using BCrypt for a 256-bit random refresh token can add substantial computation without meaningfully improving the protection provided by the token's already-high entropy.

8. Hash the Token Before Storing It

The implementation can be very small.

A dedicated service keeps the hashing logic out of your controllers and authentication flow.

For example:

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;

public final class RefreshTokenHasher {

    private RefreshTokenHasher() {
    }

    public static String hash(String token) {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");

            byte[] hash = digest.digest(
                    token.getBytes(StandardCharsets.UTF_8)
            );

            return HexFormat.of().formatHex(hash);
        } catch (NoSuchAlgorithmException e) {
            throw new IllegalStateException(
                    "SHA-256 is not available",
                    e
            );
        }
    }
}

A SHA-256 digest contains 256 bits.

When represented as hexadecimal:

256 bits / 4 bits per hex character = 64 characters

So a database column can look like:

@Column(nullable = false, unique = true, length = 64)
private String tokenHash;

The actual refresh token should never be persisted.

Only:

tokenHash

is stored.

9. The Complete Token Lifecycle

Let's put the pieces together.

Step 1 — Generate

At login:

SecureRandom
    |
    v
256-bit random refresh token

For example:

oW8n...random...value

Step 2 — Hash

The server calculates:

SHA-256(refreshToken)

Result:

9f86d081884c7d659a2feaa0c55ad015...

Step 3 — Store

The database receives:

token_hash
expires_at
revoked
user_id

It does not receive the original token.

Step 4 — Return

The raw refresh token is returned to the client:

{
  "accessToken": "...",
  "refreshToken": "oW8n...random...value"
}

The server no longer needs to persist that raw value.

Step 5 — Refresh

Later, the client sends:

{
  "refreshToken": "oW8n...random...value"
}

The server calculates:

SHA-256(receivedToken)

Then searches for that hash:

SELECT *
FROM refresh_tokens
WHERE token_hash = ?

If the record exists and is valid, the refresh operation can continue.

10. Validation Is More Than Checking the Hash

A matching hash does not automatically mean that the refresh token should be accepted.

A production implementation should also validate the token's state.

For example:

String tokenHash = refreshTokenHasher.hash(rawToken);

RefreshToken refreshToken = repository
        .findByTokenHash(tokenHash)
        .orElseThrow(() -> new InvalidRefreshTokenException());

if (refreshToken.isRevoked()) {
    throw new InvalidRefreshTokenException();
}

if (refreshToken.getExpiresAt().isBefore(Instant.now())) {
    throw new InvalidRefreshTokenException();
}

Conceptually:

                 refresh token
                       |
                       v
                  SHA-256
                       |
                       v
              find token record
                       |
          +------------+------------+
          |            |            |
       exists?       revoked?    expired?
          |            |            |
          v            v            v
         yes           no           no
                       |
                       v
                  accept token

This is one reason refresh tokens are often stored server-side even when access tokens are JWTs.

The database record provides server-controlled state.

11. Hashing and Rotation Solve Different Problems

Hashing is only one part of a secure refresh-token design.

Consider this attack.

An attacker somehow steals a valid refresh token from a browser:

ATTACKER
   |
   | stolen refresh token
   v
POST /api/auth/refresh

Hashing does not prevent that.

The attacker already has the original secret.

Hashing protects against a different threat:

ATTACKER
   |
   | database read access
   v
token_hash

The attacker sees the verifier, not the original token.

Refresh-token rotation addresses another problem: reuse of a token after it has already been consumed.

A simplified rotation flow looks like this:

Old refresh token
       |
       v
validate
       |
       v
revoke old token
       |
       v
generate new refresh token
       |
       v
hash new token
       |
       v
store new hash
       |
       v
return new token pair

The public demo for the starter follows this model: the raw refresh token is returned to the client, only its SHA-256 hash is stored, and refresh operations rotate the token.

OAuth 2.0 Security Best Current Practice also describes refresh-token rotation as a mechanism for detecting refresh-token replay: a previously invalidated token being presented again can indicate that the token was compromised.

So think of the protections as separate layers:

Random token generation
        +
SHA-256 storage
        +
Expiration
        +
Revocation
        +
Refresh-token rotation

Each addresses a different part of the problem.

12. What Happens If the Database Is Leaked?

This is where the design becomes interesting.

Plaintext storage

Suppose the database contains:

refresh_tokens

id | user_id | token
----------------------------------------
1  | 42      | abc123...

An attacker dumps the database.

They now have:

abc123...

If the token is still valid, they may be able to present it directly to the refresh endpoint.

Hashed storage

Now suppose the database contains:

refresh_tokens

id | user_id | token_hash
----------------------------------------
1  | 42      | 9f86d081...

The attacker cannot simply send:

9f86d081...

as the refresh token.

That's only the SHA-256 representation.

They would need to find an input whose SHA-256 digest matches the stored value.

With a properly generated high-entropy refresh token, that is a fundamentally different problem from guessing a human password.

This is why token randomness and token hashing must be considered together.

Hashing a weak token does not magically make it strong.

For example:

"password123"
       |
       v
SHA-256
       |
       v
hash

does not make the original secret cryptographically strong.

An attacker can simply hash common guesses offline.

The correct design is:

cryptographically random token
             +
        SHA-256 hash

13. Why Not Encrypt the Refresh Token?

Encryption is another possible approach.

You could store:

encrypted(refreshToken)

instead of:

SHA-256(refreshToken)

But encryption gives you something you don't actually need: the ability to recover the original token.

For validation, the server only needs to answer:

Does this presented token match a valid stored token?

A one-way verifier is sufficient.

Encryption also introduces another secret-management problem:

database
   +
encryption key

If the application needs the encryption key to decrypt the stored tokens, compromise of both the database and the key may expose the original credentials.

With one-way hashing:

database
   |
   v
token hash

there is no decryption operation.

This follows the principle of storing the minimum information necessary to perform the operation.

14. Don't Use the Same Storage Strategy for Passwords

One of the easiest mistakes is to create a generic:

HashingService

and use SHA-256 for everything.

Don't.

Passwords and refresh tokens have different threat models.

For passwords:

Password
   |
   v
Argon2id / BCrypt / PBKDF2
   |
   v
Database

For refresh tokens:

CSPRNG-generated token
   |
   v
SHA-256
   |
   v
Database

The distinction matters because a password can be guessed from a relatively small search space.

A properly generated 256-bit random token has an enormously larger search space.

The hash algorithm is therefore only one part of the security equation.

15. A Small Spring Boot Service

A practical implementation can hide the details behind a service.

For example:

@Service
public class RefreshTokenService {

    private final RefreshTokenRepository repository;

    public RefreshTokenService(RefreshTokenRepository repository) {
        this.repository = repository;
    }

    public String createToken(User user) {
        String rawToken = generateToken();

        RefreshToken entity = new RefreshToken();
        entity.setUser(user);
        entity.setTokenHash(hash(rawToken));
        entity.setExpiresAt(Instant.now().plus(30, ChronoUnit.DAYS));
        entity.setRevoked(false);

        repository.save(entity);

        return rawToken;
    }

    private String generateToken() {
        byte[] bytes = new byte[32];
        new SecureRandom().nextBytes(bytes);

        return Base64.getUrlEncoder()
                .withoutPadding()
                .encodeToString(bytes);
    }

    private String hash(String token) {
        try {
            MessageDigest digest =
                    MessageDigest.getInstance("SHA-256");

            return HexFormat.of().formatHex(
                    digest.digest(
                            token.getBytes(StandardCharsets.UTF_8)
                    )
            );
        } catch (NoSuchAlgorithmException e) {
            throw new IllegalStateException(e);
        }
    }
}

In a real application, the SecureRandom instance should normally be reused rather than instantiated for every token generation, and the hashing logic is better extracted into its own component.

The important architecture is:

Controller
    |
    v
Authentication Service
    |
    v
Refresh Token Service
    |
    +---- generate raw token
    |
    +---- hash token
    |
    +---- persist hash
    |
    +---- return raw token

The controller never needs to know how the token is generated or stored.

16. The Database Should Store State, Not Secrets

A refresh-token table might contain:

refresh_tokens

id
user_id
token_hash
expires_at
revoked
created_at

Notice what is missing:

token

That's intentional.

The database needs to know:

which user owns the token
whether it has expired
whether it has been revoked
when it was created
which hash corresponds to the token

It does not need the original bearer credential.

This is a useful general security principle:

If your database only needs to verify a secret, don't automatically store the secret itself.

17. One Important Caveat: Rotation Needs Concurrency Protection

There is one subtle problem worth calling out.

Imagine two requests arrive at almost exactly the same time with the same refresh token:

Request A ────────> refresh endpoint
Request B ────────> refresh endpoint

If both requests validate the old token before either transaction revokes it, both may succeed.

Hashing does not solve this.

Rotation alone does not necessarily solve it either.

A production-grade implementation may need stronger concurrency control, depending on the application's requirements:

transactional boundaries
row-level locking
optimistic locking
atomic state transitions
refresh-token families
replay detection

This is an important distinction because "hashed refresh tokens" does not mean "complete refresh-token security."

It solves one specific problem extremely well:

protecting the stored representation of the token if the database is exposed.

18. The Security Model

The final design can be summarized like this:

                  LOGIN
                    |
                    v
          Generate random token
                    |
                    v
             Raw refresh token
                /         \
               /           \
              v             v
         Client          SHA-256
                           |
                           v
                       Database
                       token_hash


                 REFRESH
                    |
                    v
             Client sends raw token
                    |
                    v
                 SHA-256
                    |
                    v
             Database lookup
                    |
          +---------+---------+
          |                   |
       invalid              valid
          |                   |
          v                   v
        reject          revoke old token
                              |
                              v
                       generate new token
                              |
                              v
                         store hash
                              |
                              v
                      return new pair

Each layer has a specific responsibility.

Cryptographic randomness

Prevents attackers from predicting tokens.

SHA-256

Prevents the database from containing reusable plaintext refresh credentials.

Expiration

Limits the lifetime of a token.

Revocation

Allows the server to invalidate a token before its natural expiration.

Rotation

Limits token reuse and provides a mechanism for detecting replay.

None of these replaces the others.

19. The Practical Rule

If you remember only one thing from this article, make it this:

Don't choose a hashing algorithm based on the fact that the value is called a "secret." Choose it based on the properties of the secret.

For passwords:

human-generated
potentially guessable
        ↓
slow password hashing

For refresh tokens:

server-generated
cryptographically random
high entropy
        ↓
SHA-256 verifier

And most importantly:

Random token
      +
hashed database representation
      +
expiration
      +
revocation
      +
rotation

is much stronger than simply generating a random token and putting the raw value into PostgreSQL.

Conclusion

JWT authentication is often presented as a token-generation problem.

It isn't.

The difficult part is designing what happens around the token.

Refresh tokens are a good example.

They are long-lived bearer credentials, so storing their plaintext values in a database creates an unnecessary risk. The server doesn't need to recover the original token. It only needs to verify that the presented token corresponds to a valid server-side record.

That makes a one-way hash a natural fit.

The important distinction is that refresh tokens should be random enough that guessing is already impractical. SHA-256 then gives the database a verifier without requiring the database to store the original bearer secret.

And that is why the following design makes sense:

32-byte cryptographically random token
                    ↓
                 SHA-256
                    ↓
             PostgreSQL

While passwords should follow a different path:

human password
       ↓
Argon2id / BCrypt / PBKDF2
       ↓
   PostgreSQL

Security isn't about using the strongest-looking algorithm everywhere.

It's about matching the mechanism to the threat model.

AI disclosure

This article was created with the assistance of AI and reviewed for technical accuracy by the author. The implementation details and security decisions should be verified against the requirements of the application before production use.

ABotWroteThis

Production-Ready JWT Authentication with Spring Boot 4

TeKa IT — Thu, 30 Jul 2026 13:58:58 +0000

Access tokens, hashed refresh tokens, rotation, PostgreSQL, Flyway, and Testcontainers

Most JWT tutorials show how to generate a token.

This guide explains how to design the authentication system around it.

Authentication looks deceptively simple in a demo. A client submits an email address and password, the server creates a JWT, and the client uses that token to call protected endpoints.

The difficult questions appear later.

What happens when the access token expires? How does logout work in a stateless system? What if a refresh token is stolen? Should tokens be stored in PostgreSQL? How do multiple devices remain logged in independently? What should happen when an old refresh token is submitted twice? And how do we verify that the entire lifecycle works against a real database?

This guide answers those questions by building a production-minded authentication architecture with:

Java 21
Spring Boot 4
Spring Security
JWT access tokens
opaque refresh tokens
SHA-256 refresh-token hashing
refresh-token rotation
BCrypt password hashing
PostgreSQL
Flyway
Docker Compose
Swagger/OpenAPI
Testcontainers

The code examples follow the architecture of the Spring Boot JWT Starter Kit and use its actual package structure and service names.

The public demo repository is available at:

https://github.com/teka-it/spring-boot-jwt-starter-demo

Why Most JWT Tutorials Are Incomplete
Access Tokens and Refresh Tokens
Storing Refresh Tokens Securely
Refresh-Token Rotation
Where Tokens Should Live on the Client
Stateless Security with Spring Security
Registration and Login
Implementing the Refresh and Logout Flows
Common JWT Mistakes
Testing with PostgreSQL and Testcontainers
Production Hardening
The Complete Architecture
Appendix A — JWT Claims
Appendix B — Authentication Status Codes
Appendix C — Authentication Timeline
Conclusion

Part I — Foundations

1. Why Most JWT Tutorials Are Incomplete

Every week, new tutorials explain how to add JWT authentication to a Spring Boot application.

Most follow roughly the same path:

Accept a username and password.
Load the user from a database.
Generate a JWT.
Add a filter.
Protect an endpoint.

The result works. A valid token reaches the API, Spring Security recognizes the caller, and protected resources become accessible.

But generating a JWT is not the same as designing an authentication system.

A real system must continue behaving correctly when:

an access token expires;
a user logs in on multiple devices;
a refresh token is copied;
a database backup is exposed;
a user logs out;
a password is reset;
an account is disabled;
two refresh requests arrive at nearly the same time;
a signing secret needs to be rotated;
an attacker repeatedly submits old credentials.

A basic JWT tutorial usually stops before these questions become visible.

JWT Is a Token Format, Not a Session Strategy

A JSON Web Token is a signed set of claims. It can carry a subject, issuer, expiration time, and roles. A server can validate those claims without loading session state from a database.

That is useful, but it does not define:

how long a login should last;
how credentials should be renewed;
how sessions should be revoked;
how logout should work;
how compromised credentials should be contained.

Those responsibilities belong to the authentication architecture surrounding the JWT.

A useful mental model is:

JWT
└── proves information about one request

Session architecture
├── decides how long login persists
├── decides how credentials are renewed
├── manages revocation
├── manages logout
└── limits damage after compromise

Server Sessions and Stateless Access Tokens

Traditional server-side authentication stores session state on the server.

Traditional server-side session lookup

The browser sends a session identifier. The server loads the corresponding session and determines who the user is.

JWT access tokens invert that model.

Stateless JWT access-token validation

The token carries the information required to authenticate the request. The server validates it cryptographically and does not need to retrieve an access-token record.

That stateless property improves scalability, but it introduces a trade-off: a valid access token is difficult to revoke immediately without adding state back into the request path.

Why One Long-Lived Token Is Not Enough

The simplest JWT design issues one token that remains valid for days or weeks.

That design is pleasant during development because it avoids refresh logic. It is also dangerous.

A bearer token works for whoever possesses it. If a thirty-day access token is copied, the attacker can use it for thirty days. The signature remains valid, and a stateless server has no automatic way to know that the token changed hands.

The safer model separates two concerns:

short-lived authorization, handled by access tokens;
long-lived session continuity, handled by refresh tokens.

The access token may remain valid for fifteen minutes. The refresh token may keep the session alive for thirty days, but it is stateful, revocable, stored securely, and rotated after use.

Design Decision — Accept bounded access-token risk

The starter does not persist access tokens. A stolen access token therefore remains usable until it expires. The risk is bounded by a short lifetime, while the normal request path remains stateless and does not require a database lookup.

What to Remember

A JWT is not a complete authentication system.
Long-lived access tokens create large attack windows.
Stateless access-token validation and stateful session management can coexist.
Refresh tokens exist because access tokens should expire quickly.
Security depends on the lifecycle around the token, not merely its signature.

2. Access Tokens and Refresh Tokens

Access tokens and refresh tokens are often returned together, but they have different responsibilities, lifetimes, storage requirements, and failure modes.

Access Tokens Authorize API Requests

The client sends an access token with a protected request:

GET /api/users/me HTTP/1.1
Host: localhost:8080
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

The API validates:

the cryptographic signature;
the issuer;
the expiration time;
other configured claims.

When validation succeeds, Spring Security establishes an authenticated SecurityContext.

A typical access-token payload might look like:

{
  "iss": "spring-boot-jwt-starter",
  "sub": "alice@example.com",
  "iat": 1785402000,
  "exp": 1785402900,
  "roles": ["USER"]
}

The starter uses the email address as the subject and stores role names in a custom roles claim.

Refresh Tokens Maintain Sessions

A refresh token is not sent with ordinary API requests. It is presented only to the refresh endpoint:

POST /api/auth/refresh HTTP/1.1
Content-Type: application/json

{
  "refreshToken": "a-long-random-url-safe-value"
}

The server hashes the supplied value, finds the matching session record, verifies that it has not expired or been revoked, revokes it, and issues a replacement pair.

The refresh token therefore acts as a stateful session credential.

Different Lifetimes

The starter’s default configuration expresses the difference clearly:

app:
  jwt:
    issuer: ${JWT_ISSUER:spring-boot-jwt-starter}
    secret: ${JWT_SECRET}
    access-token-ttl: ${JWT_ACCESS_TOKEN_TTL:15m}
    refresh-token-ttl: ${JWT_REFRESH_TOKEN_TTL:30d}

Credential	Default lifetime	Primary purpose
Access token	15 minutes	Authorize protected API requests
Refresh token	30 days	Continue an authenticated session

Fifteen minutes is not a universal rule, and thirty days is not automatically appropriate for every product. Financial, healthcare, administrative, and consumer applications may choose different values. The important property is the asymmetry: access tokens are deliberately brief, while refresh tokens receive stronger lifecycle controls.

Stateless and Stateful Layers

The architecture combines two models:

Short-lived authorization and stateful session continuity

Most application traffic uses only the access token and does not query the refresh-token table. Authentication-related endpoints use PostgreSQL to create, consume, rotate, and revoke sessions.

Behind the Starter Kit

The public API returns a TokenResponse containing an access token, refresh token, token type, and access-token lifetime. The access token is a signed JWT. The refresh token is an opaque random value with no claims for the client to inspect.

Multiple Devices

Each successful login creates a new refresh-token record.

A user can therefore have separate sessions for:

a personal laptop;
a mobile phone;
a work computer.

The current starter revokes a specific refresh token during logout. It does not yet expose a session-management screen or “log out everywhere” endpoint, but its one-record-per-token model provides a foundation for those features.

What to Remember

Access tokens authorize requests.
Refresh tokens preserve login continuity.
Access tokens are stateless and short-lived.
Refresh tokens are stateful and long-lived.
Each login can create an independent device session.

3. Storing Refresh Tokens Securely

A refresh token can generate new access tokens. That makes it a high-value credential.

Storing it in plaintext would turn a database read breach into immediate session compromise.

The Plaintext Problem

Consider this table:

CREATE TABLE refresh_token (
    id BIGSERIAL PRIMARY KEY,
    token VARCHAR(255) NOT NULL UNIQUE,
    user_id BIGINT NOT NULL,
    expires_at TIMESTAMP WITH TIME ZONE NOT NULL
);

The schema itself does not reveal whether token contains plaintext or a hash. If the raw value is stored, anyone who can read the table can submit it to /api/auth/refresh.

Encryption at rest helps protect disks and backups, but the application still needs the ability to decrypt the value. A one-way hash provides a stronger property: the server does not need to recover the original token at all.

Generate a High-Entropy Opaque Token

The starter generates 32 random bytes using SecureRandom:

private static final SecureRandom SECURE_RANDOM = new SecureRandom();

byte[] bytes = new byte[32];
SECURE_RANDOM.nextBytes(bytes);

String rawToken = Base64.getUrlEncoder()
        .withoutPadding()
        .encodeToString(bytes);

Thirty-two bytes provide 256 bits of randomness before encoding. URL-safe Base64 makes the result convenient to transport in JSON, headers, or cookies.

The token is opaque. It contains no user ID, timestamp, role, or other claims. The client only needs to preserve and return it.

Hash Before Persistence

The raw value is hashed with SHA-256:

private String hash(String value) {
    try {
        byte[] digest = MessageDigest.getInstance("SHA-256")
                .digest(value.getBytes(StandardCharsets.UTF_8));

        return HexFormat.of().formatHex(digest);
    } catch (NoSuchAlgorithmException exception) {
        throw new IllegalStateException(
                "SHA-256 is niet beschikbaar",
                exception
        );
    }
}

The stored entity receives the hash:

RefreshToken refreshToken = new RefreshToken();
refreshToken.setToken(hash(rawToken));
refreshToken.setUser(user);
refreshToken.setExpiresAt(
        OffsetDateTime.now().plus(jwtProperties.refreshTokenTtl())
);

refreshTokenRepository.save(refreshToken);

return rawToken;

The raw token is returned to the client. Only the 64-character hexadecimal SHA-256 digest remains in PostgreSQL.

Generating and hashing an opaque refresh token

Why SHA-256 Instead of BCrypt?

Passwords and refresh tokens are different kinds of secrets.

Passwords are usually:

chosen by humans;
low entropy;
reused;
vulnerable to dictionary attacks.

BCrypt deliberately makes each guess expensive.

Refresh tokens should be:

generated by a cryptographically secure random generator;
high entropy;
unique;
infeasible to guess.

A slow password hash provides little additional protection against brute-forcing a genuinely random 256-bit token, while making every lookup more expensive.

SHA-256 also enables a direct indexed lookup:

refreshTokenRepository.findByToken(hash(rawToken))

BCrypt normally uses a random salt, so the same input does not produce a stable lookup value. Applications using BCrypt for tokens often have to load candidate records and call matches, which is less efficient and more complex.

Design Decision — Match the hash to the secret

BCrypt is appropriate for human passwords. SHA-256 is appropriate here because the refresh token is already a high-entropy random credential and the application needs a deterministic lookup key.

Database Shape

The starter uses this migration:

CREATE TABLE refresh_token (
    id          BIGSERIAL PRIMARY KEY,
    token       VARCHAR(255) NOT NULL UNIQUE,
    user_id     BIGINT NOT NULL REFERENCES app_user(id) ON DELETE CASCADE,
    expires_at  TIMESTAMP WITH TIME ZONE NOT NULL,
    revoked     BOOLEAN NOT NULL DEFAULT FALSE,
    created_at  TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);

The JPA entity constrains the token field to 64 characters, matching the hexadecimal SHA-256 output:

@Column(nullable = false, unique = true, length = 64)
private String token;

The migration allows 255 characters while the entity declares 64. This is not functionally unsafe, but aligning both definitions to 64 would make the schema more precise.

What Hashing Does Not Solve

Hashing protects refresh tokens at rest. It does not protect a raw token that is stolen from:

browser JavaScript storage;
malware on the client device;
application logs;
network traffic without HTTPS;
an insecure analytics or error-reporting integration.

That risk is addressed by secure client storage, HTTPS, careful logging, and token rotation.

What to Remember

Never store reusable refresh tokens in plaintext.
Generate tokens with a cryptographically secure random generator.
Store only a deterministic cryptographic hash.
BCrypt protects weak human passwords; SHA-256 fits high-entropy random tokens.
Hashing at rest does not replace secure delivery and client storage.

4. Refresh-Token Rotation

A static refresh token remains useful until it expires or is revoked. If it is copied, the attacker and legitimate client can both use it.

Rotation changes the token after every successful refresh.

Single-Use Credentials

Assume a login produces:

Access token:  A1
Refresh token: R1

When the client submits R1, the server:

validates it;
marks its database record as revoked;
creates R2;
stores the hash of R2;
creates A2;
returns A2 and R2.

Refresh-token rotation from R1 to R2

A subsequent attempt to use R1 fails.

How the Starter Consumes a Token

The RefreshTokenService performs the state transition:

@Transactional
public RefreshToken consume(String rawToken) {
    RefreshToken token = refreshTokenRepository
            .findByToken(hash(rawToken))
            .orElseThrow(InvalidRefreshTokenException::new);

    if (token.isRevoked()
            || token.getExpiresAt().isBefore(OffsetDateTime.now())) {
        throw new InvalidRefreshTokenException();
    }

    token.setRevoked(true);
    return token;
}

The record is retained and marked as revoked rather than deleted.

This has useful audit value: the database can distinguish a token that never existed from a token that existed and was consumed. The public error remains intentionally generic.

Rotation in One Transaction

TokenRefreshService.refresh is transactional:

@Transactional
public TokenResponse refresh(String rawRefreshToken) {
    RefreshToken consumedToken =
            refreshTokenService.consume(rawRefreshToken);

    var user = consumedToken.getUser();

    var authorities = user.getRoles().stream()
            .map(role -> new SimpleGrantedAuthority(
                    "ROLE_" + role.getName().name()
            ))
            .toList();

    var authentication =
            UsernamePasswordAuthenticationToken.authenticated(
                    user.getEmail(),
                    null,
                    authorities
            );

    return new TokenResponse(
            jwtTokenService.createAccessToken(authentication),
            refreshTokenService.create(user),
            "Bearer",
            jwtProperties.accessTokenTtl().toSeconds()
    );
}

The old token is revoked and the new record is created within the transaction boundary. If persistence fails, the state changes roll back together.

Common Pitfall — Partial rotation

Revoking the old token and creating the replacement in separate transactions can leave the session in an inconsistent state. The user may lose the session, or two usable tokens may coexist.

Rotation Reduces the Attack Window

Suppose an attacker steals R1.

If the legitimate client refreshes first, R1 becomes revoked and the attacker’s later request fails.

If the attacker refreshes first, the attacker receives R2, while the legitimate client’s next use of R1 fails.

Rotation therefore does not magically identify who is legitimate. It makes token reuse observable and limits the period in which the copied credential remains usable.

Reuse Detection: Current Behavior and a Stronger Variant

Version 1.0.0 rejects reuse because revoked records remain in the database and consume checks isRevoked().

It currently returns the same InvalidRefreshTokenException for:

an unknown token;
an expired token;
a revoked token.

That is a good public response because it avoids leaking unnecessary information.

A more advanced internal policy could distinguish reuse in security telemetry and respond by:

revoking every active refresh token for the user;
requiring a new login;
recording IP address and user agent;
notifying the user;
creating a security alert.

That stronger response requires retaining enough session-family information to identify related tokens. The current model does not yet store a family ID or replacement-token relationship.

Production Tip — Separate public errors from internal signals

Return a generic 401 response to the client, but record whether the failure was caused by expiration, revocation, or reuse in structured security logs.

Concurrency

Two refresh requests carrying the same valid token could arrive concurrently.

Both transactions might read the record before either commits the revoked update. A robust high-concurrency system should make consumption atomic, for example through:

pessimistic locking;
an atomic conditional update;
optimistic locking with a version column;
a database constraint combined with session-family modeling.

The starter’s implementation is suitable as a clear foundation, but applications expecting concurrent refresh traffic should explicitly test and harden this race.

What to Remember

Treat refresh tokens as single-use credentials.
Revoke the old token before completing rotation.
Keep rotation transactional.
Reuse is a security signal, not merely a validation error.
Concurrency control matters when multiple refreshes can race.

5. Where Tokens Should Live on the Client

The server can issue credentials securely and still lose the session through unsafe client storage.

There is no browser storage option that removes every risk. The correct choice depends on architecture, threat model, and client type.

Local Storage

Local Storage is convenient:

localStorage.setItem("accessToken", response.accessToken);
localStorage.setItem("refreshToken", response.refreshToken);

Any JavaScript running in the page can also read those values. An XSS vulnerability may therefore exfiltrate the long-lived refresh token.

Session Storage has a shorter persistence model, but the same JavaScript accessibility problem.

HttpOnly Cookies

An HttpOnly cookie cannot be read through normal page JavaScript:

Set-Cookie: refreshToken=...; HttpOnly; Secure; SameSite=Strict; Path=/api/auth

This reduces direct token theft through XSS, although malicious JavaScript may still perform actions as the user while it is executing.

Cookies are sent automatically by the browser, so the application must also consider CSRF. SameSite, origin checks, narrowly scoped cookie paths, and CSRF tokens can be part of that defense.

A Practical Browser Pattern

A common browser architecture is:

keep the access token in memory;
deliver the refresh token through an HttpOnly, Secure cookie;
use a narrowly scoped refresh endpoint;
issue a new in-memory access token after page reload.

A practical browser token-storage pattern

This pattern is not implemented automatically by the starter. Version 1.0.0 accepts and returns the refresh token in JSON so that the backend remains client-agnostic. The README explicitly recommends considering an HttpOnly, Secure cookie for browser frontends.

Non-Browser Clients

Mobile, desktop, and machine clients have different storage mechanisms:

mobile keychains or keystores;
operating-system credential vaults;
encrypted application storage;
workload identity rather than refresh tokens for machine-to-machine communication.

JWT design should not assume that every client is a browser.

What to Remember

Browser storage is part of authentication security.
Local Storage exposes tokens to JavaScript.
HttpOnly cookies reduce direct token exfiltration but require CSRF consideration.
Keeping access tokens in memory can reduce persistence.
The starter’s JSON transport is intentionally client-neutral.

Part II — Implementation

6. Stateless Security with Spring Security

The starter does not implement a custom JWT filter. It uses Spring Security’s OAuth2 resource-server support for bearer-token parsing and JWT validation.

That is an important architectural choice: security-sensitive token handling is delegated to established framework components.

SecurityFilterChain

The central configuration is:

@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http)
        throws Exception {

    return http
            .csrf(csrf -> csrf.disable())
            .sessionManagement(session ->
                    session.sessionCreationPolicy(
                            SessionCreationPolicy.STATELESS
                    )
            )
            .authorizeHttpRequests(auth -> auth
                    .requestMatchers(
                            "/api/health",
                            "/api/auth/register",
                            "/api/auth/login",
                            "/api/auth/refresh",
                            "/api/auth/logout",
                            "/v3/api-docs/**",
                            "/swagger-ui.html",
                            "/swagger-ui/**"
                    ).permitAll()
                    .anyRequest().authenticated()
            )
            .oauth2ResourceServer(resourceServer ->
                    resourceServer.jwt(jwt ->
                            jwt.jwtAuthenticationConverter(
                                    jwtAuthenticationConverter()
                            )
                    )
            )
            .build();
}

Stateless Session Management

.sessionManagement(session ->
        session.sessionCreationPolicy(
                SessionCreationPolicy.STATELESS
        )
)

Spring Security will not use an HTTP session to preserve authentication between requests. Every protected request must carry its own bearer token.

Public and Protected Routes

Registration, login, refresh, logout, health, and API documentation are public. Every other route is authenticated.

This default-deny shape is safer than individually remembering to protect each new controller.

The fact that /api/auth/logout is public at the filter-chain level does not mean it performs no authentication. It authenticates the session by validating the supplied refresh token. The endpoint does not require a still-valid access token, which allows a client to log out after access-token expiration.

JWT Encoder and Decoder

The starter uses HS256 and requires a Base64-encoded secret of at least 32 bytes:

@Bean
SecretKey jwtSecretKey(JwtProperties properties) {
    byte[] keyBytes =
            Base64.getDecoder().decode(properties.secret());

    if (keyBytes.length < 32) {
        throw new IllegalStateException(
                "JWT_SECRET moet minimaal 256 bits (32 bytes) bevatten"
        );
    }

    return new SecretKeySpec(keyBytes, "HmacSHA256");
}

The encoder and decoder use Spring Security’s Nimbus integration:

@Bean
JwtEncoder jwtEncoder(SecretKey secretKey) {
    return NimbusJwtEncoder.withSecretKey(secretKey)
            .algorithm(MacAlgorithm.HS256)
            .build();
}

@Bean
JwtDecoder jwtDecoder(
        SecretKey secretKey,
        JwtProperties properties
) {
    NimbusJwtDecoder decoder =
            NimbusJwtDecoder.withSecretKey(secretKey)
                    .macAlgorithm(MacAlgorithm.HS256)
                    .build();

    decoder.setJwtValidator(
            JwtValidators.createDefaultWithIssuer(
                    properties.issuer()
            )
    );

    return decoder;
}

createDefaultWithIssuer adds standard validation and checks the configured issuer.

Design Decision — Framework validation instead of a custom filter

A custom OncePerRequestFilter can work, but it creates more security-sensitive code for the application to own. The starter relies on Spring Security’s resource-server machinery for token extraction, decoding, claim validation, authentication failures, and SecurityContext integration.

Mapping Roles

JWT roles are converted into Spring authorities:

@Bean
JwtAuthenticationConverter jwtAuthenticationConverter() {
    JwtAuthenticationConverter converter =
            new JwtAuthenticationConverter();

    converter.setJwtGrantedAuthoritiesConverter(jwt -> {
        List<String> roles =
                jwt.getClaimAsStringList("roles");

        if (roles == null) {
            return List.of();
        }

        return roles.stream()
                .<GrantedAuthority>map(role ->
                        new SimpleGrantedAuthority(
                                "ROLE_" + role
                        )
                )
                .toList();
    });

    return converter;
}

The JWT contains USER; Spring Security receives ROLE_USER.

Creating Access Tokens

JwtTokenService keeps access-token creation focused:

public String createAccessToken(Authentication authentication) {
    Instant issuedAt = Instant.now();
    Instant expiresAt =
            issuedAt.plus(properties.accessTokenTtl());

    List<String> roles =
            authentication.getAuthorities().stream()
                    .map(GrantedAuthority::getAuthority)
                    .map(authority ->
                            authority.replaceFirst("^ROLE_", "")
                    )
                    .toList();

    JwtClaimsSet claims = JwtClaimsSet.builder()
            .issuer(properties.issuer())
            .issuedAt(issuedAt)
            .expiresAt(expiresAt)
            .subject(authentication.getName())
            .claim("roles", roles)
            .build();

    return jwtEncoder.encode(
            JwtEncoderParameters.from(claims)
    ).getTokenValue();
}

The service does not know about HTTP, refresh tokens, repositories, or password verification.

What to Remember

Use stateless session management for bearer-token APIs.
Prefer framework-supported JWT validation over unnecessary custom filters.
Validate the issuer as well as signature and time-based claims.
Convert JWT claims into Spring authorities in one clear place.
Keep token creation separate from login and refresh orchestration.

7. Registration and Login

A token should only be issued after Spring Security has verified the credentials.

Registration

The starter’s registration flow:

normalizes the email address;
validates the request;
rejects duplicate email addresses;
hashes the password with BCrypt;
assigns the USER role;
persists the user.

The BCrypt encoder is configured as a bean:

@Bean
PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
}

Applications should never compare plaintext passwords manually or store them in reversible form.

DatabaseUserDetailsService

Spring Security loads users through the database-backed service:

@Override
@Transactional(readOnly = true)
public UserDetails loadUserByUsername(String email)
        throws UsernameNotFoundException {

    User user = userRepository
            .findByEmailIgnoreCase(email)
            .orElseThrow(() ->
                    new UsernameNotFoundException(
                            "Gebruiker niet gevonden"
                    )
            );

    var authorities = user.getRoles().stream()
            .map(role -> new SimpleGrantedAuthority(
                    "ROLE_" + role.getName().name()
            ))
            .toList();

    return new org.springframework.security.core.userdetails.User(
            user.getEmail(),
            user.getPassword(),
            user.isEnabled(),
            true,
            true,
            true,
            authorities
    );
}

This adapter translates the application’s User entity into Spring Security’s UserDetails.

LoginService

The real login orchestration is concise:

@Transactional
public TokenResponse login(LoginRequest request) {
    String email = request.email()
            .trim()
            .toLowerCase(Locale.ROOT);

    var authentication =
            authenticationManager.authenticate(
                    UsernamePasswordAuthenticationToken
                            .unauthenticated(
                                    email,
                                    request.password()
                            )
            );

    User user = userRepository
            .findByEmailIgnoreCase(email)
            .orElseThrow(() ->
                    new IllegalStateException(
                            "Ingelogde gebruiker bestaat niet"
                    )
            );

    return new TokenResponse(
            jwtTokenService.createAccessToken(authentication),
            refreshTokenService.create(user),
            "Bearer",
            jwtProperties.accessTokenTtl().toSeconds()
    );
}

The sequence is deliberate:

normalize the email;
delegate credential verification to AuthenticationManager;
load the domain entity needed to create the refresh-token relation;
create the access token;
create and persist the refresh-token hash;
return both credentials.

Why Load the User Again?

The authenticated principal contains the email, password hash, enabled state, and authorities, but RefreshToken has a JPA relationship to the application’s User entity.

The service therefore loads the entity after authentication.

A future optimization could use a custom principal carrying the user ID or domain reference, but the current implementation is explicit and easy to understand.

AuthController

The HTTP layer delegates instead of implementing business rules:

@PostMapping("/login")
TokenResponse login(
        @Valid @RequestBody LoginRequest request
) {
    return loginService.login(request);
}

A successful response resembles:

{
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "mh8dJ2...url-safe-random-value",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Avoid Sensitive Logging

Do not log:

request bodies for authentication endpoints;
Authorization headers;
raw refresh tokens;
JWTs in exception messages;
complete cookies carrying session credentials.

Structured logs should contain non-secret identifiers and outcomes, not reusable credentials.

What to Remember

Authenticate before generating tokens.
Let AuthenticationManager and PasswordEncoder verify passwords.
Normalize identity fields consistently.
Keep controllers thin.
Never place passwords or raw tokens in logs.

8. Implementing Refresh and Logout

The refresh endpoint authenticates an existing session rather than a password.

Controller Endpoints

@PostMapping("/refresh")
TokenResponse refresh(
        @Valid @RequestBody RefreshTokenRequest request
) {
    return tokenRefreshService.refresh(
            request.refreshToken()
    );
}

@PostMapping("/logout")
ResponseEntity<Void> logout(
        @Valid @RequestBody RefreshTokenRequest request
) {
    tokenRefreshService.logout(request.refreshToken());
    return ResponseEntity.noContent().build();
}

Complete Refresh Flow

The complete refresh flow

The service reconstructs an Authentication from the user associated with the consumed refresh token. This lets JwtTokenService use the same access-token creation method for login and refresh.

Logout

Logout calls:

@Transactional
public void revoke(String rawToken) {
    refreshTokenRepository
            .findByToken(hash(rawToken))
            .ifPresent(token -> token.setRevoked(true));
}

The operation is idempotent from the caller’s perspective. An unknown token does not reveal whether a session existed.

The endpoint returns 204 No Content.

What Logout Can and Cannot Do

Logout revokes the refresh token, preventing future access-token renewal.

It does not invalidate an access token that has already been issued. That token may remain usable until its short expiration time.

This is a normal consequence of stateless access tokens.

Applications requiring immediate access-token revocation must introduce additional state, such as:

a denylist;
a user-level security version;
introspection;
very short lifetimes combined with gateway controls.

Those options add cost and complexity and should be selected deliberately.

Exception Handling

Invalid refresh tokens become a stable 401 response through GlobalExceptionHandler:

@ExceptionHandler(InvalidRefreshTokenException.class)
ResponseEntity<ApiError> handleInvalidRefreshToken(
        InvalidRefreshTokenException exception,
        HttpServletRequest request
) {
    return buildError(
            HttpStatus.UNAUTHORIZED,
            exception.getMessage(),
            request.getRequestURI(),
            Map.of()
    );
}

Validation failures become 400 responses, and duplicate registration becomes 409 Conflict.

Common Pitfall — Returning 500 for expected authentication failures

Expired, malformed, revoked, and missing credentials are expected client-facing failures. They should not be reported as unexpected server errors.

What to Remember

Refresh authenticates a session, not a password.
Consume and replace the refresh token transactionally.
Logout revokes renewal capability, not already-issued access tokens.
Keep authentication failures generic to clients.
Use correct HTTP status codes and stable error bodies.

Part III — Reliability and Production

9. Common JWT Mistakes

Mistake 1 — Long-Lived Access Tokens

A long-lived access token avoids refresh logic but magnifies the effect of theft.

Better: short-lived access tokens plus managed refresh sessions.

Mistake 2 — Persisting Access Tokens

Looking up every JWT in the database recreates server-side sessions in a less direct form.

Better: validate access tokens statelessly and persist only refresh-session state.

Mistake 3 — Plaintext Refresh Tokens

A database reader can immediately impersonate active sessions.

Better: store SHA-256 hashes of high-entropy opaque tokens.

Mistake 4 — Weak Randomness

Timestamps, UUID variants used without analysis, counters, or java.util.Random should not generate bearer credentials.

Better: SecureRandom with sufficient bytes.

Mistake 5 — BCrypt for Deterministic Token Lookup

BCrypt is intentionally slow and salted. That fits passwords, not direct lookup of high-entropy tokens.

Better: SHA-256 for the random refresh tokens used by this architecture.

Mistake 6 — Static Refresh Tokens

A copied token remains valid for its full lifetime.

Better: rotate after every successful use.

Mistake 7 — Validating Only the Signature

A valid signature does not make an expired token acceptable, and a token from the wrong issuer should not be trusted.

Better: validate time-based claims and issuer; add audience validation when the token is intended for a specific API.

Mistake 8 — Oversized JWT Payloads

JWT payloads are encoded, not encrypted. Clients and intermediaries can read claims.

Better: include only stable authorization data and non-sensitive identifiers.

Mistake 9 — Hardcoded Signing Secrets

Secrets committed to Git may survive in history even after deletion.

Better: inject secrets through environment configuration or a secrets manager.

Mistake 10 — Logging Tokens

Bearer credentials in logs may be copied into search systems, support tools, and backups.

Better: redact Authorization headers, cookies, passwords, and token fields.

Mistake 11 — Ignoring Refresh Races

Two concurrent requests may consume the same token without atomic database controls.

Better: use locking or an atomic update when the workload requires it.

Mistake 12 — Treating CORS as Authentication

CORS is a browser policy. It does not stop non-browser clients from calling the API.

Better: authenticate and authorize every protected server request.

Mistake 13 — Assuming Logout Revokes JWTs

Deleting or revoking the refresh token does not make a signed access token disappear.

Better: communicate this behavior clearly and keep the access-token lifetime short.

Mistake 14 — Returning Detailed Security Errors

Telling an attacker exactly whether a user exists, a token expired, or a token was revoked may help enumeration.

Better: return generic public messages and preserve detailed reasons in internal telemetry.

What to Remember

Convenience shortcuts often enlarge the attack surface.
Keep access tokens small, short-lived, and stateless.
Treat refresh tokens as managed, single-use session credentials.
Never expose secrets through source control or logs.
Test failure paths, not only successful login.

10. Testing with PostgreSQL and Testcontainers

Authentication code is easy to test incompletely.

A mocked unit test may prove that one method invokes another. It does not prove that:

Flyway creates the expected schema;
JPA mappings match PostgreSQL;
password authentication works through Spring Security;
bearer-token validation reaches protected endpoints;
token rotation is persisted;
reused tokens are rejected;
logout prevents later refresh.

The starter therefore includes an end-to-end integration test against a real temporary PostgreSQL instance.

Testcontainer Setup

@Testcontainers
@SpringBootTest(
        webEnvironment =
                SpringBootTest.WebEnvironment.RANDOM_PORT
)
class AuthenticationFlowIntegrationTest {

    @Container
    static final PostgreSQLContainer postgres =
            new PostgreSQLContainer("postgres:17-alpine")
                    .withDatabaseName("jwt_starter_test")
                    .withUsername("jwt_test")
                    .withPassword("jwt_test");
}

Dynamic properties connect Spring Boot to the container:

@DynamicPropertySource
static void configureProperties(
        DynamicPropertyRegistry registry
) {
    registry.add(
            "spring.datasource.url",
            postgres::getJdbcUrl
    );
    registry.add(
            "spring.datasource.username",
            postgres::getUsername
    );
    registry.add(
            "spring.datasource.password",
            postgres::getPassword
    );
    registry.add(
            "app.jwt.secret",
            () -> JWT_SECRET
    );
    registry.add(
            "app.jwt.access-token-ttl",
            () -> "15m"
    );
    registry.add(
            "app.jwt.refresh-token-ttl",
            () -> "30d"
    );
}

The Complete Lifecycle Test

The test performs the same actions as a real client:

register a unique user;
log in;
call /api/users/me with the bearer token;
refresh the session;
verify the old refresh token is rejected;
log out using the new refresh token;
verify the logged-out token is rejected.

The central assertions include:

TokenPayload refreshed = postForToken(
        "/api/auth/refresh",
        Map.of("refreshToken", firstRefreshToken)
);

String secondRefreshToken =
        refreshed.refreshToken();

assertThat(secondRefreshToken)
        .isNotBlank()
        .isNotEqualTo(firstRefreshToken);

Then reuse is rejected:

client.post()
        .uri("/api/auth/refresh")
        .contentType(MediaType.APPLICATION_JSON)
        .bodyValue(Map.of(
                "refreshToken",
                firstRefreshToken
        ))
        .exchange()
        .expectStatus()
        .isUnauthorized();

And logout is verified:

client.post()
        .uri("/api/auth/logout")
        .contentType(MediaType.APPLICATION_JSON)
        .bodyValue(Map.of(
                "refreshToken",
                secondRefreshToken
        ))
        .exchange()
        .expectStatus()
        .isNoContent();

Protected Endpoint Test

A separate test verifies that unauthenticated access is rejected:

@Test
void protectedEndpointRejectsMissingToken() {
    client.get()
            .uri("/api/users/me")
            .exchange()
            .expectStatus()
            .isUnauthorized();
}

Additional Tests Worth Adding

The included test covers the primary lifecycle. A production application should expand it with:

invalid password;
unknown email address;
duplicate registration;
malformed JWT;
expired access token;
wrong issuer;
modified JWT signature;
expired refresh token;
disabled account;
role-based authorization;
concurrent refresh attempts;
invalid request payloads;
database uniqueness and cleanup behavior.

Production Tip — Test time explicitly

Token tests become easier and less flaky when services depend on an injectable Clock instead of calling Instant.now() or OffsetDateTime.now() directly.

Why a Real Database Matters

H2 and PostgreSQL do not behave identically. Migrations, timestamp handling, constraints, identity columns, and SQL dialect details can differ.

Testcontainers gives the test suite the same database family used in production without requiring a permanently shared test database.

What to Remember

Test the authentication lifecycle through HTTP.
Run migrations against a real PostgreSQL container.
Assert rejection after rotation and logout.
Test malformed and expired credentials.
Add concurrency tests before relying on single-use guarantees under load.

11. Production Hardening

The starter is a foundation, not a substitute for application-specific security design.

The following controls belong around the core architecture.

HTTPS Everywhere

Bearer credentials must never travel over plaintext HTTP outside local development.

Enforce TLS at the load balancer or ingress layer, redirect HTTP, and consider HSTS for browser deployments.

Secret Management

The starter reads JWT_SECRET from configuration:

secret: ${JWT_SECRET}

Generate a Base64-encoded value containing at least 32 random bytes:

openssl rand -base64 32

Do not commit production secrets to:

Git;
Docker images;
sample configuration;
CI logs;
support tickets.

Use a deployment platform’s secret store or a dedicated secrets manager.

Symmetric vs Asymmetric Signing

HS256 is simple and appropriate when the same trusted application boundary signs and validates tokens.

As systems grow, asymmetric algorithms can provide cleaner separation:

the authorization service holds the private key;
APIs validate with public keys;
validators cannot mint tokens.

A public-key architecture also supports key identifiers and published JWK sets more naturally.

Key Rotation

A single static key creates operational risk.

A mature deployment should support:

key identifiers (kid);
overlap between old and new validation keys;
controlled token-signing rollover;
emergency rotation procedures;
audit trails for key access.

Audience Validation

The starter validates the issuer. Applications issuing tokens for a particular API should consider an aud claim and corresponding audience validation.

This prevents a token intended for one service from being accepted by another service that trusts the same issuer or key.

Rate Limiting and Abuse Controls

Protect:

registration;
login;
refresh;
password-reset endpoints.

Controls may include:

per-IP limits;
per-account limits;
exponential backoff;
CAPTCHA after suspicious behavior;
temporary lockouts designed to avoid denial-of-service abuse.

CORS

Configure only the origins, methods, and headers required by trusted browser clients. Avoid broad wildcard settings when credentials or sensitive APIs are involved.

Remember that CORS does not protect the API from scripts, mobile applications, or command-line clients outside a browser.

Cookies and CSRF

When refresh tokens are delivered in cookies:

set HttpOnly;
set Secure;
choose SameSite intentionally;
restrict Path;
consider CSRF tokens or origin verification;
define cookie expiration consistently with server-side session expiration.

Content Security Policy

A strong CSP reduces the chance and impact of script injection. It complements HttpOnly cookies and secure frontend engineering.

Logging and Monitoring

Record security-relevant events without recording credentials:

login success and failure;
refresh success;
expired or revoked refresh attempts;
logout;
account disablement;
role changes;
suspicious request rates.

Useful context may include:

internal user ID;
session ID;
timestamp;
IP address;
user agent;
request correlation ID;
reason category.

Review privacy and retention requirements before storing device or network metadata.

Session Metadata

The current refresh-token entity stores:

hash;
user;
expiration;
revoked flag;
creation time.

Possible additions include:

session ID;
token family ID;
last-used time;
device label;
IP address;
user agent;
revocation reason;
replaced-by token ID.

These fields enable session dashboards and stronger reuse response.

Cleanup

Expired and revoked rows accumulate over time.

Add a scheduled cleanup process with a retention policy. You may retain revoked records briefly for investigation while deleting old data after the security and audit window closes.

Add indexes that match actual queries and cleanup operations.

Account-State Changes

Consider revoking sessions when:

a password changes;
multi-factor authentication settings change;
an account is disabled;
a role is removed;
an administrator initiates a security reset.

Because access tokens remain valid until expiration, the access-token lifetime defines the maximum delay unless you introduce a user security version or another stateful check.

Error Handling

Return consistent, limited client errors. Avoid stack traces and database details.

The starter’s ApiError model provides a useful base for:

status;
reason;
message;
request path;
timestamp;
field validation errors.

Time and Clock Skew

JWT validation depends on reliable clocks.

Use synchronized infrastructure time and define a small, intentional clock-skew policy. Excessive tolerance weakens expiration guarantees.

Dependency Maintenance

Authentication depends on Spring Security, Nimbus JOSE/JWT through Spring, the PostgreSQL driver, Flyway, and other libraries.

Keep dependencies current, monitor advisories, and run automated tests during upgrades.

What to Remember

Production security is layered.
Manage signing keys as critical secrets.
Add audience validation when tokens target a specific API.
Rate-limit authentication endpoints.
Log security outcomes, never bearer credentials.
Plan session cleanup, key rotation, and incident response before they are needed.

12. The Complete Architecture

The final system combines stateless authorization with stateful session continuity.

Complete Spring Boot JWT authentication architecture

Complete Lifecycle

Registration

The client submits validated profile data.
The server normalizes the email.
BCrypt hashes the password.
The USER role is assigned.
Flyway-managed PostgreSQL tables store the account.

Login

The client submits email and password.
AuthenticationManager delegates to the configured authentication provider.
DatabaseUserDetailsService loads the account and roles.
BCrypt verifies the password.
JwtTokenService issues a fifteen-minute access token.
RefreshTokenService generates 32 random bytes.
The server stores only the SHA-256 hash.
The client receives the token pair.

Protected Request

The client sends Authorization: Bearer <access token>.
Spring Security’s resource server extracts the JWT.
JwtDecoder validates HS256, standard claims, and issuer.
JwtAuthenticationConverter maps roles.
Spring Security establishes the SecurityContext.
The controller handles the authenticated request.
No access-token database lookup occurs.

Refresh

The client submits the raw refresh token.
The server hashes it.
PostgreSQL returns the matching session record.
The service verifies expiration and revocation.
The old record is marked revoked.
A new access JWT is issued.
A new random refresh token is generated.
Its SHA-256 hash is stored.
The new pair is returned in the same transaction.

Logout

The client submits its current refresh token.
The server hashes it.
The matching record is marked revoked.
The endpoint returns 204.
The access token expires naturally.

Project Structure

src/main/java/nl/javalaunch/starter
├── auth
│   ├── controller
│   ├── dto
│   └── service
├── common
│   └── exception
├── config
├── health
├── refreshtoken
│   ├── entity
│   ├── repository
│   └── service
├── role
│   ├── entity
│   └── repository
├── security
└── user
    ├── controller
    ├── dto
    ├── entity
    └── repository

This feature-oriented organization keeps HTTP, orchestration, persistence, and security concerns discoverable without forcing every class into generic global controller, service, and repository folders.

Behind the Starter Kit

The full starter includes:

complete source code;
PostgreSQL migrations;
Docker Compose;
OpenAPI documentation;
sample API requests;
integration tests;
architecture and security notes;
configuration and customization guides.

The public demo intentionally exposes the architecture and usage examples without redistributing the commercial source code.

Appendix A — JWT Claims

`iss` — Issuer

Identifies the authority that issued the token.

The starter uses:

spring-boot-jwt-starter

The decoder validates this value.

`sub` — Subject

Identifies the principal represented by the token.

The starter uses the normalized email address.

For systems where email addresses can change, an immutable user ID may be a stronger long-term subject.

`iat` — Issued At

Records when the token was created.

`exp` — Expiration

Defines the time after which the token must be rejected.

`nbf` — Not Before

Optionally prevents acceptance before a specified time.

`aud` — Audience

Identifies the intended recipient or API.

The current starter does not add or validate an audience claim. Add it when tokens should be restricted to a particular service.

`jti` — JWT ID

Provides a unique identifier for a token.

The starter does not use jti because access tokens are not persisted or individually revoked. It can be useful for diagnostics or denylist-based designs, though it should not be added without a clear purpose.

`roles` — Custom Claim

Carries application roles:

{
  "roles": ["USER"]
}

The converter maps these to ROLE_USER.

Appendix B — Authentication Status Codes

Status	Authentication use
200 OK	Successful login or refresh
201 Created	Successful registration
204 No Content	Successful logout with no response body
400 Bad Request	Invalid request shape or validation failure
401 Unauthorized	Missing, invalid, expired, or revoked credentials
403 Forbidden	Authenticated user lacks required authority
409 Conflict	Registration conflicts with an existing email
429 Too Many Requests	Authentication endpoint rate limit exceeded
500 Internal Server Error	Unexpected server or configuration failure

The historical name “Unauthorized” is slightly misleading: 401 generally means the request is not successfully authenticated. A user who is authenticated but not permitted should receive 403.

Appendix C — Authentication Timeline

08:00  User logs in
       ├── Access token A1 expires at 08:15
       └── Refresh token R1 expires in 30 days

08:10  Client calls protected endpoint with A1
       └── Spring Security validates JWT without token lookup

08:15  A1 expires

08:16  Client submits R1
       ├── Server hashes R1
       ├── R1 record is marked revoked
       ├── Access token A2 is created
       └── Refresh token R2 is created and hashed

08:17  Reuse of R1
       └── 401 Unauthorized

08:30  Client logs out with R2
       └── R2 record is marked revoked

08:31  Refresh with R2
       └── 401 Unauthorized

Until A2 expires
       └── A2 may still authorize requests because access JWTs are stateless

Conclusion

Secure JWT authentication is not about producing a signed string after login.

It is about designing a lifecycle with explicit answers to difficult questions:

Which credentials authorize ordinary requests?
Which credentials preserve the session?
How long does each credential remain valid?
Which state is stored?
How is stored state protected?
What becomes invalid during refresh?
What does logout revoke?
How are suspicious retries detected?
How is the behavior verified against real infrastructure?
What happens when keys, accounts, roles, or production requirements change?

The architecture in this guide makes a deliberate split.

Access tokens are short-lived JWTs. They are validated statelessly through Spring Security’s resource-server support and are not stored in PostgreSQL.

Refresh tokens are opaque, high-entropy session credentials. Their SHA-256 hashes are stored, their records can be revoked, and each successful refresh rotates the credential.

Passwords are protected with BCrypt. Database structure is managed by Flyway. The full authentication lifecycle is tested through HTTP against PostgreSQL with Testcontainers.

That combination preserves the scalability of stateless API authorization without pretending that long-lived sessions can be managed safely without state.

The implementation is intentionally a foundation rather than the final word for every application. High-risk systems should extend it with audience validation, asymmetric signing, key rotation, atomic refresh consumption, richer session metadata, reuse response, rate limiting, monitoring, and application-specific security review.

But the central principle remains stable:

A production-ready authentication system is not defined by what happens when login succeeds. It is defined by how safely and predictably the system behaves after credentials expire, leak, rotate, fail, and are revoked.

Reference Implementation

The public demo repository contains the architecture overview and usage examples:

https://github.com/teka-it/spring-boot-jwt-starter-demo

The complete reference implementation—including source code, PostgreSQL migrations, Docker Compose, OpenAPI documentation, and integration tests—is available as the Spring Boot JWT Starter Kit:

https://tekait.gumroad.com/l/spring-boot-jwt-starter

DEV Community: TeKa IT

Why You Should Hash Refresh Tokens with SHA-256

1. A Refresh Token Is a Bearer Secret

2. Why Plaintext Storage Is Unnecessary

Plaintext storage

Hashed storage

3. But Why SHA-256?

4. Passwords Are Low-Entropy Secrets

5. Refresh Tokens Should Have High Entropy

6. SHA-256 Is Fast — and That's Fine Here

Password

Refresh token

7. SHA-256 vs BCrypt

8. Hash the Token Before Storing It

9. The Complete Token Lifecycle

Step 1 — Generate

Step 2 — Hash

Step 3 — Store

Step 4 — Return

Step 5 — Refresh

10. Validation Is More Than Checking the Hash

11. Hashing and Rotation Solve Different Problems

12. What Happens If the Database Is Leaked?

Plaintext storage

Hashed storage

13. Why Not Encrypt the Refresh Token?

14. Don't Use the Same Storage Strategy for Passwords

15. A Small Spring Boot Service

16. The Database Should Store State, Not Secrets

17. One Important Caveat: Rotation Needs Concurrency Protection

18. The Security Model

Cryptographic randomness

SHA-256

Expiration

Revocation

Rotation

19. The Practical Rule

Conclusion

AI disclosure

ABotWroteThis

Production-Ready JWT Authentication with Spring Boot 4

Access tokens, hashed refresh tokens, rotation, PostgreSQL, Flyway, and Testcontainers

Table of Contents

Part I — Foundations

1. Why Most JWT Tutorials Are Incomplete

JWT Is a Token Format, Not a Session Strategy

Server Sessions and Stateless Access Tokens

Why One Long-Lived Token Is Not Enough

What to Remember

2. Access Tokens and Refresh Tokens

Access Tokens Authorize API Requests

Refresh Tokens Maintain Sessions

Different Lifetimes

Stateless and Stateful Layers

Multiple Devices

What to Remember

3. Storing Refresh Tokens Securely

The Plaintext Problem

Generate a High-Entropy Opaque Token

Hash Before Persistence

Why SHA-256 Instead of BCrypt?

Database Shape

What Hashing Does Not Solve

What to Remember

4. Refresh-Token Rotation

Single-Use Credentials

How the Starter Consumes a Token

Rotation in One Transaction

Rotation Reduces the Attack Window

Reuse Detection: Current Behavior and a Stronger Variant

Concurrency

What to Remember

5. Where Tokens Should Live on the Client

Local Storage

HttpOnly Cookies

A Practical Browser Pattern

Non-Browser Clients

What to Remember

Part II — Implementation

6. Stateless Security with Spring Security