DEV Community: esteban389

Why Our Next.js Deployments Took 30 Minutes

esteban389 — Fri, 28 Aug 2026 20:03:04 +0000

Frontend deployments could take anywhere from 18 to 30 minutes. Eventually, I
started letting changes accumulate so the wait felt more justified.

Sometimes that was fine. Sometimes it meant a change sat longer than it should
have. The same delay was harder to accept when the change was a critical fix. I
started to dread deploying the frontend, and the wait began influencing when I
chose to ship changes.

I did not write the Dockerfile behind those deployments. It was already in the
repository when I joined as a junior, and I did not have an opinion about it then.
For local development and builds, I usually ran Node.js directly. The Dockerfile
stayed mostly outside my field of view until I had more experience and was allowed
to perform deployments myself.

Once the cost became part of my own workflow, I investigated why the frontend job
took so much longer than two backend jobs in the same pipeline. Inspecting the
deployment path made the shipped artifact the next object to measure.

The deployment moved the whole image

The inspected deployment job did not pull the frontend image from a registry. It
used a command shaped like this:

docker save <image> | ssh <server> docker load

In this incident, the job streamed the complete image to the server and loaded it
there. A larger image meant more bytes for that path to transfer and load.

This was also why the two backend services were useful clues. They used the same
broad deployment mechanism but shipped a JRE base plus one application JAR. Their
jobs completed much sooner. The frontend image used Node.js and Next.js; different
runtime stacks need not produce equal image sizes. The comparison only gave us a
specific place to investigate.

This does not prove that image transfer consumed every minute of the observed
18-30 minute duration. Compilation, network throughput, remote disk performance,
image loading, container replacement, and health checks can all contribute. It
does establish that this job moved the entire artifact, making its contents part
of deployment performance.

Other pipelines may behave differently. A registry can reuse layers and changes
the transfer model. The diagnosis here belongs to the inspected full-image
transfer job, not to every slow Docker deploy.

The runtime image still contained the build workspace

The frontend Dockerfile already used multiple stages, but the final stage copied
far more than the application needed at runtime. Structurally, it looked like the
following example.

# Simplified, anonymized skeleton — not the production Dockerfile
FROM node:<full-version> AS build
WORKDIR /app

COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM node:<full-version> AS runtime
WORKDIR /app

COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/.next ./.next
COPY --from=build /app/public ./public
COPY --from=build /app/package.json ./package.json

CMD ["npm", "start"]

Multi-stage syntax did not make the runtime image small by itself. The final
COPY instructions still selected the complete dependency directory and the
complete Next.js build directory. That included development dependencies and build
output that the running server did not need.

We built and inspected the existing image rather than guessing from the
Dockerfile. It measured 9.48 GB. The .next directory accounted for 6.55 GB, and
node_modules accounted for another 1.78 GB. In this build, .next included the
persistent webpack cache along with runtime output.

Those numbers showed that the build workspace had become the runtime contract.

Make the runtime boundary explicit

Next.js standalone mode generated the .next/standalone output used by the final
stage. We enabled it in the Next.js configuration:

// Simplified configuration excerpt — not the production file
module.exports = {
  output: 'standalone',
};

That output gave the runtime stage a narrower set of files to copy. The replacement
structure looked like this:

# Simplified, anonymized skeleton — not the production Dockerfile
FROM node:<version> AS build
WORKDIR /app

COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM node:<slim-version> AS runtime
WORKDIR /app
ENV NODE_ENV=production

COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/public ./public

USER node
CMD ["node", "server.js"]

The copy boundary changed. The runtime stage receives the .next/standalone
output, static assets, and public files instead of the full node_modules and
.next directories. It also uses a slim Node base and runs as a non-root user.

Built from the same source, the resulting images landed in the approximate
350-380 MB range. That is about one twenty-fifth of the original size, or roughly
96% smaller.

Size alone was not enough to call the change complete. A narrow copy can omit a
file resolved at runtime. Changing the runtime user can expose a permission
mistake. The smaller artifact had to run the application, not merely finish
docker build.

A smaller image still has to run

We started the standalone container locally against live user and academic
services plus the identity service. Then we completed a real login and navigated
through an authenticated part of the application.

That path exercised more than a public health endpoint. It required the frontend
server to start, reach its dependencies, complete authentication, serve its
assets, and handle an authenticated route. During that validation we saw no
runtime errors, missing-file failures, or permission problems.

This test supports a specific conclusion: the reduced image contained what that
authenticated application path needed. It does not prove that every route is
covered, and it does not measure how long the image will take to reach the target
server.

These checks answer different questions. Artifact size answers “How much are we
shipping?” A real application flow answers “Did we keep enough for this runtime
behavior?” Neither result substitutes for the other.

Why I kept the deployment workflow out of scope

Changing the deployment workflow was technically possible. I chose not to start
there. We deploy per tenant, and some tenants use a different workflow because of
internal organizational decisions. Redesigning those paths would have widened the
scope beyond the problem I was trying to solve.

The image was shared across those paths, and it was the largest bottleneck we had
identified. Improving that artifact let us address the common transfer cost
without first changing the tenant-specific workflows.

After rollout, the workflow that had taken roughly 18-30 minutes came down to
approximately 5-6 minutes. A second workflow was already faster at roughly 5-10
minutes; with the smaller image, its deployments ranged from a few seconds to
approximately 2 minutes.

These are operational observations, not controlled benchmarks. The tenant
workflows and their conditions differ, so the two ranges should not be compared as
if only one variable changed. Both improved enough to confirm that the image had
been a material cost in each deployment path.

Inspect, minimize, test

I inherited a Dockerfile that I barely interacted with, then later inherited the
operational cost of what it shipped. Batching changes made the wait feel more
reasonable, but it did not make delivery faster. Looking inside the artifact gave
us a concrete source of transfer work to address.

This case supports three checks for an inherited runtime image:

Inspect the actual runtime image and measure its largest contents.
Minimize the final-stage copy boundary to what the application needs at runtime.
Test a real application path that can expose missing files, permissions, and dependency assumptions.

For this case, the first two steps reduced the image to about one twenty-fifth of
its previous size. The third showed that a real authenticated flow still worked.
The rollout then reduced one deployment path from roughly 18-30 minutes to 5-6
minutes and another from roughly 5-10 minutes to between a few seconds and 2
minutes. Future measurements can show whether another pipeline stage becomes the
next dominant cost.

What Duplicate Users Taught Me About Outbox and Idempotency

esteban389 — Thu, 27 Aug 2026 21:44:46 +0000

After enough support tickets involving students who couldn't log in, I stopped
seeing each case as an isolated data problem. Staff operations were failing too,
and I kept returning to the same boundary between two services.

For this post, I'll call those services Student and Users. The names are simplified,
but the requirement is one we had at work: creating a student in Student also
required an application-user record in Users.

On paper, the flow was short. Student asked Users to create the user, received a
userId, and then saved the student. The difficult part was everything the network
could leave unanswered between those two local transactions. Student might not
receive a response even though Users committed its work. Retrying could recover the
operation, or repeat an effect that had already happened.

Transactional outbox, idempotency, and inbox each address part of that problem. The
outbox preserves the work Student still needs done. An idempotency key gives
repeated attempts the same identity. The inbox remembers what Users already did and
what it returned. I'll add them in that order, starting with why the direct call
seemed reasonable.

I first worked on this path when I was a junior. We knew that one service's
transaction did not magically include the other service. The direct call was a
conscious tradeoff for a one-to-one interaction, not an attempt to pretend the
boundary did not exist.

Its appeal was easy to see on the happy path. Student called Users, took the returned
ID, and finished saving the student. The code could read almost like the requirement.

The support cases made the limit harder to ignore. One student's login reached the
application-user lookup and failed there. When we inspected the data, we found three
enabled user records sharing the same document number. Other cases involved students
who couldn't log in or staff operations that failed because the expected student/user
relationship was missing or inconsistent.

The symptoms varied, but I kept ending up at the same boundary. Student expected one
usable Users record for the student. When that relationship was missing or
ambiguous, an operation that looked like a student problem could fail in Users
instead.

My reaction was not particularly sophisticated: this is absurd. I knew I could
control the requests to Users better, yet I was still spending time repairing the
consequences when that boundary went wrong.

I still do not know which historical operation created those three records. A
repeated request is possible, but other sequences are possible too. I can explain
the failure at the service boundary without pretending that it proves the cause of
that incident.

The direct call still contains two transactions

At the business level, creating a student and its application user sounds like one
action. The state is still split. Student owns the student record, while Users owns
the user record.

User creation is part of student creation. Student needs the returned userId to
connect the records and finish its work. Losing that result leaves the business
operation unfinished from Student's perspective, even if Users has already done its
part.

Each service can make its own changes atomic. What the call cannot do is merge those
local transactions into a single commit or rollback across both services.¹
Once Users commits, Student cannot undo that transaction as if both changes belonged
to one database.

The direct request also makes Student wait for Users. A failure before Users commits
can stop student creation. A failure after Users commits is more awkward because the
user may exist even though Student did not finish its side.

Suppose Users creates the user and returns a userId, but the response never reaches
Student. Student knows that the answer is missing. It does not know whether Users
completed the request. Sending the request again may recover the operation, or it
may repeat the effect unless Users can recognize the attempt.²

A timeout says that the answer did not arrive. It does not say what Users committed.

The outbox preserves Student's intent

I first reached for an outbox after dealing with notifications that had not been
delivered. What bothered me was not only that they failed. Once the original
request was gone, we had little durable state to help us send them again.

While designing that flow, I started looking at other service boundaries where the
same idea could help. Student and Users was one of them.

Here, the problem was no longer only that the call could fail. Student's need to
create a user lived inside that one request, and once the request was gone, Student
had no durable record it could return to.

An outbox gives Student that record. Student saves its own change and a create-user
intent in the same local transaction. If the transaction commits, both are stored.
If it rolls back, neither is stored. A separate sender can process the intent
afterward.¹

That was the part I had been missing on the Student side. The request could end
without taking the required work with it. The outbox row would still say which
operation needed to happen and which student it belonged to.

But keeping the intent available also means a sender may deliver it more than once.
Suppose Users creates the user and returns the result, but Student does not record
that success. The outbox row still looks unfinished, so sending it again is
reasonable from Student's side. Users, meanwhile, may have completed the work
already.¹

Student now has a way to recover the intent. Users needs a way to recognize that the
next delivery belongs to the same operation.

Repeated delivery introduces idempotency

This is where idempotency enters the design. Student assigns one idempotencyKey to
the create-user operation and reuses it every time the outbox sender delivers that
operation. A fresh key on each attempt would make those attempts look like separate
operations to Users.²

Student can still retry. The key gives Users a stable identity for understanding
that those attempts belong to the same piece of work.

The terminology can make this sound more abstract than the Student-side code needs
to be. The TypeScript examples in this post are invented, incomplete, and use
Prisma-style calls only to illustrate the two local transactions. They are not
production code.³

The Student transaction creates the student and its outbox row together:

async function createStudent(studentData: StudentData, idempotencyKey: string) {
  return prisma.$transaction(async (tx) => {
    const student = await tx.student.create({ data: studentData });

    await tx.outbox.create({
      data: {
        idempotencyKey,
        studentId: student.id,
        operation: 'create-user',
      },
    });

    return student;
  });
}

The outbox row keeps the same idempotencyKey whenever the sender tries to deliver
this create-user operation again.

The inbox keeps the Users result

Once Student can retry, Users needs more than a way to say, “I have seen this
before.” Student still needs the userId from the first attempt.

If Users stores only the key, it can avoid creating another user but cannot finish
the original conversation. The inbox needs to keep both the idempotencyKey and the
result that belongs to it. A repeated request can then receive the same answer
instead of triggering the same change again.⁴

Here, the inbox is an ordinary table. When the key is new, Users creates the user and
the inbox row in one local transaction. When the key already exists, Users returns
the result it stored earlier.

Keeping both writes in the same transaction is what makes the record trustworthy.
If user creation fails, there should be no inbox entry claiming it succeeded. If the
inbox write fails, the user creation rolls back with it.

The Users-side code can stay fairly small:

async function createUser(userData: UserData, idempotencyKey: string) {
  return prisma.$transaction(async (tx) => {
    // Ensure it is processed once.
    const previous = await tx.inbox.findUnique({
      where: { idempotencyKey },
    });

    if (previous) return previous.result;

    const user = await tx.user.create({ data: userData });
    const result = { userId: user.id };

    await tx.inbox.create({
      data: { idempotencyKey, result },
    });

    return result;
  });
}

The example assumes idempotencyKey is unique. Two concurrent calls might both check
the inbox before either one inserts the row, but only one can claim that key. The
other transaction rolls back and can retry. On its next attempt, findUnique
returns the result already stored for the operation.³

Put the two local transactions side by side and the change becomes easier to see:

Current synchronous flow
Student -> Users: create user
Users -> Users state: save user
Users --> Student: userId
Student -> Student state: save student

Outbox and inbox flow
Student -> Student state: save student + outbox (local transaction)
Outbox sender -> Users: create user [idempotencyKey]
Users -> Users state: save user + inbox result (local transaction)
Users --> Outbox sender: userId
Outbox sender -> Student state: associate userId
Outbox sender -> Users: repeat create user [same idempotencyKey]
Users --> Outbox sender: stored userId

This flow trades immediate agreement for recoverability. Student can commit its
record and outbox entry before Users creates the user, so the relationship may
remain incomplete for a while. The outbox does not decide what the application
should expose during that window; that is a separate product decision.

Idempotency does not replace business rules

The same idempotencyKey tells Users that this is another attempt at the same
operation. A different key identifies a different operation, even when some fields
in the two requests happen to match.²

That is all the inbox should decide. It should not compare different requests and
silently merge them because their payloads look similar. Whether two separate
operations are both allowed belongs to domain validation and uniqueness rules, not
to the inbox.

Repeated delivery, one business effect

The outbox may send the same operation more than once. For one idempotencyKey,
Users can recognize the repeat, skip the second user creation, and return the
userId it saved the first time.

The delivery still happened more than once. The create-user effect did not. That is
the scoped guarantee here, rather than literal exactly-once delivery.⁵

What I wanted from this design was not a magical transaction across two services. I
wanted each service to know what it owned once the easy request path stopped being
easy. Student keeps the work it still needs done. Users keeps the result of the
operation it already processed.

I first built the direct path as a junior. Later outbox work gave me a better way to
reason about it, so I came back to the same boundary with different questions. That
is a separate article I want to write: how revisiting earlier work has become part
of how I learn.

AWS Prescriptive Guidance, “Transactional outbox pattern”; Chris Richardson, Microservices.io, “Pattern: Transactional outbox”. ↩
IETF, RFC 9110: HTTP Semantics, section 9.2.2; Malcolm Featonby, AWS Builders' Library, “Making retries safe with idempotent APIs”. ↩
Prisma Documentation, “Transactions and batch queries”, “Prisma Client API”, and “Error Reference”. ↩
Chris Richardson, Microservices.io, “Pattern: Idempotent Consumer”; Malcolm Featonby, AWS Builders' Library, “Making retries safe with idempotent APIs”. ↩
IETF, RFC 9110: HTTP Semantics, section 9.2.2; AWS Prescriptive Guidance, “Transactional outbox pattern”. ↩

How Java's Concurrency APIs Fit Together

esteban389 — Thu, 20 Aug 2026 23:14:16 +0000

A concurrency problem can begin with an ordinary requirement: let two independent
operations make progress without forcing one to wait for the other. The requirement
is easy to state. Choosing among Thread, ExecutorService, Future,
CompletableFuture, locks, atomics, queues, and synchronizers is harder when they
look like competing answers to the same question.

These APIs answer different questions. Some describe work, some decide how it
runs, some represent results, and others protect shared state or coordinate tasks.
Grouping them by responsibility turns the standard library from a list of names
into a map.

We will build that map around a small customer-dashboard example, then use shorter
examples for the problems the dashboard does not cover. The examples assume basic
Java, not prior concurrency knowledge. Start with the responsibility the program
needs; choose the class after that.

Start with a program that waits twice

Suppose an endpoint builds a customer dashboard from a profile and a list of recent
orders:

var profile = loadProfile();
var orders = loadOrders();

return new Dashboard(profile, orders);

The code fragments below omit imports and surrounding class definitions when those
details do not affect the concurrency mechanism.

The second call starts after the first one returns. If the operations are independent
and spend most of their time waiting for remote services, that order leaves an
obvious opportunity: start both, then assemble the dashboard when both results are
available.

That small change already involves three separate responsibilities: describe each
operation, decide how to execute it, and obtain its result. The full map uses seven
questions:

Question	Representative APIs
What work should happen?	`Runnable`, `Callable<V>`
Where and how should it run?	`Thread`, `Executor`, `ExecutorService`, virtual threads
How do I obtain or combine results?	`Future<V>`, `CompletableFuture<T>`
How do I protect shared state?	`synchronized`, `volatile`, `Lock`, atomic variables
How do I share data safely?	`ConcurrentHashMap`, `BlockingQueue`
How do tasks coordinate?	`Semaphore`, `CountDownLatch`, `CyclicBarrier`
How do I divide computation?	`ForkJoinPool`, parallel streams

These groups overlap. CompletableFuture, for example, represents a result and can
also arrange dependent execution. Treat the groups as questions for locating a
problem rather than rigid boxes for classifying every type.

On a first pass, focus on tasks, executors, futures, and the shared-state sections.
Learn queues and semaphores as named solutions for handoff and limits. Leave
CyclicBarrier, fork/join, and continuation-scheduling rules as landmarks until a
program gives you one of those problems.

One vocabulary distinction will help throughout the map. Concurrent tasks make
progress during overlapping periods; they do not have to execute at the same
instant. Parallel work does execute at the same instant. A single CPU core can
interleave concurrent tasks, while parallel execution requires hardware resources
that can run work simultaneously. We will use concurrency for the waiting-heavy
dashboard and reserve parallel computation for a separate data-processing example.

Tasks describe work

A task describes work. A thread is one possible execution mechanism.

Java's basic task interfaces make that separation visible. Runnable represents
an operation with no result,¹ while Callable<V> returns a value and
may throw an exception.² Neither interface chooses the thread that
will run it. Their contracts only describe the operation.

Runnable refreshCache = () -> cache.refresh();

Callable<String> loadProfile =
        () -> profileClient.fetchProfile(customerId);

Creating either value does not start the work. A caller could invoke run() or
call() directly, or it could hand the task to an executor. That later choice
determines the execution policy.

The code that describes a cache refresh stays unchanged whether the application
runs it immediately, schedules it in a pool, or starts a virtual thread for it.

Use Thread directly when the program intentionally owns one thread's identity or
lifecycle, such as naming it, installing its uncaught-exception handler, or joining
that specific thread. An executor is the better fit when thread creation,
scheduling, and lifecycle belong to an execution policy rather than the task
itself.³

Executors decide how work runs

An Executor receives a Runnable and applies an execution policy. Its interface
separates task submission from details such as thread creation, reuse, and
scheduling. The Executor contract does not promise asynchronous execution: a
minimal executor is allowed to call command.run() in the submitting thread, while
other implementations create threads or reuse them from a pool.⁴

ExecutorService adds lifecycle operations and methods such as submit, which
returns a Future.⁵ An application should close or shut down
an executor service when it no longer needs it. In modern Java, the interface is
AutoCloseable, so a try-with-resources block can own that lifecycle.

The executable examples target Java 21 or newer because they use virtual threads;
the responsibility map and the older APIs apply more broadly. Here is the dashboard
using one virtual thread per submitted task:

Dashboard loadDashboard() throws Exception {
    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
        Future<String> profile =
                executor.submit(this::loadProfile);
        Future<List<String>> orders =
                executor.submit(this::loadOrders);

        return new Dashboard(profile.get(), orders.get());
    }
}

Both tasks are submitted before the code waits for either result. Their executions
can therefore overlap when the executor can run them concurrently. Submission
alone is not a guarantee of overlap; the executor owns that policy and may be
constrained by available resources.

The following order prevents the two dashboard operations from overlapping:

var profile = executor.submit(this::loadProfile).get();
var orders = executor.submit(this::loadOrders).get();

The first get() may block before the second line can submit loadOrders. Keep
the handles first and the waits after both submissions when the operations are
independent.

Virtual threads became a final feature in Java 21. They are Thread instances
scheduled by the JDK rather than permanent one-to-one wrappers around operating
system threads. They suit thread-per-task code with many concurrent operations that
often wait, which describes calls to remote services. They do not make CPU-bound
code run faster or make timing-dependent access to shared mutable state safe. JEP
444 also advises against pooling virtual threads.⁶ Create one per task; use
a separate mechanism when a scarce resource needs a concurrency limit.

Results can be waited for or composed

A Future<V> is a handle to a result that may not exist yet. get() waits when
necessary and then returns the value or reports the computation's failure. A
Future also exposes completion status and cancellation. Under the Future
contract, cancel(...) attempts cancellation; already-running work may continue,
depending on timing and whether the task responds to interruption.⁷

The dashboard example uses two plain futures because its control flow is short:
submit two operations, wait for both, and build one value. The blocking get()
calls do not erase the earlier concurrency because both submissions already
happened.

CompletableFuture<T> becomes useful when later work should depend on earlier
results. It implements both Future<T> and CompletionStage<T>, which adds
operations for transforming and combining completed stages.

Start with one result and one transformation:

CompletableFuture<String> profile =
        CompletableFuture.supplyAsync(this::loadProfile, executor);

CompletableFuture<String> label =
        profile.thenApply(name -> "Customer: " + name);

After profile completes normally, thenApply passes its result to the function
and produces another stage containing the label. No get() separates the two
steps.⁸

If we translated the earlier two-input dashboard directly, CompletableFuture
would mostly look like a syntax swap around the same fixed fan-out. Add one real
dependency instead: recommendations can start only after the profile is available,
while orders can still load independently.

profile + orders ----------> dashboard -------------\
profile -------------------> recommendations --------+--> personalized dashboard

The code mirrors that dependency graph:

try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    CompletableFuture<String> profile =
            CompletableFuture.supplyAsync(this::loadProfile, executor);
    CompletableFuture<List<String>> orders =
            CompletableFuture.supplyAsync(this::loadOrders, executor);

    CompletableFuture<List<String>> recommendations = profile.thenCompose(
            loadedProfile -> loadRecommendations(loadedProfile, executor));

    CompletableFuture<Dashboard> dashboard =
            profile.thenCombine(orders, Dashboard::new);

    return dashboard.thenCombine(
                    recommendations,
                    (loadedDashboard, loadedRecommendations) ->
                            new PersonalizedDashboard(
                                    loadedDashboard.profile(),
                                    loadedDashboard.orders(),
                                    loadedRecommendations))
            .join();
}

The asynchronous suppliers receive the executor explicitly because
CompletableFuture async methods without one normally use
ForkJoinPool.commonPool().⁸

profile and orders start independently. After profile completes normally,
thenCompose invokes the recommendation function and flattens the
CompletableFuture it returns. The first thenCombine builds a dashboard after
both independent inputs arrive. The second combines that dashboard with the
recommendations, and join() waits once at the request boundary.

Plain Future and CompletableFuture overlap, but they encourage different control
flow. Plain Future remains adequate for a short, fixed set of independent tasks
when the caller can submit them together and wait at one clear boundary. Completion
stages help when one result starts later work or several branches must converge.
The example stops at composition. Production code still needs an explicit policy
for errors, cancellation, timeouts, and executor ownership.

Shared state has three separate questions

Choosing an executor does not make shared mutation safe. Imagine adding a counter
that every completed dashboard task increments:

volatile int completed;

void markCompleted() {
    completed++;
}

The volatile declaration gives reads and writes memory-consistency guarantees,
but completed++ is a compound read-modify-write operation. Two threads can read
the same value and both write the same incremented value, losing one update. The
Java Language Specification separates these memory actions,⁹
and the atomic package supplies operations that perform the complete update
atomically.

Shared-state safety involves three separate questions:

Atomicity: must other threads observe a group of operations as one indivisible action?
Visibility: when one thread writes a value, what guarantees that another thread sees it?
Ordering: what constrains the order in which actions become observable across threads?

Consider a one-time handoff in which one thread publishes a dashboard and another
reads it:

Dashboard publishedDashboard;
volatile boolean dashboardReady;

void publish(Dashboard value) {
    publishedDashboard = value;
    dashboardReady = true;
}

Dashboard readIfReady() {
    return dashboardReady ? publishedDashboard : null;
}

The dashboard write occurs before the volatile flag write in the publishing
thread. If another thread later reads dashboardReady as true, the Java Memory
Model's volatile happens-before rule makes the earlier dashboard write visible to
that reader.¹⁰ The flag does not lock either method or make a
compound update atomic.

synchronized can provide mutual exclusion for a critical section and a
visibility relationship around the same monitor. When one thread unlocks a
monitor, that action happens-before a later lock of the same monitor, so writes
before the unlock become visible through that synchronization relationship. The
java.util.concurrent memory-consistency summary also documents similar guarantees
for task submission, successful Future.get(), concurrent collections, and
synchronizers.¹¹

volatile provides visibility and ordering for reads and writes of one field. It
does not provide mutual exclusion around a sequence such as an increment. The
Lock interfaces provide explicit locking plus options such as interruptible or
timed acquisition and multiple conditions.¹² That flexibility comes with
explicit acquire/release code and does not make Lock an automatic upgrade over
synchronized.

For one independent counter, AtomicInteger matches the operation directly:

AtomicInteger completed = new AtomicInteger();

Future<Integer> task =
        executor.submit(completed::incrementAndGet);

The java.util.concurrent.atomic package provides thread-safe read-modify-write
operations on single variables, including increment and compare-and-set.¹³
One atomic variable does not make a multi-value invariant atomic. If a rule spans a
balance and a ledger entry, or requires several objects to change together, a lock
around the invariant or a design that avoids shared mutation may fit better.

Concurrent collections protect documented operations

Shared data often needs more structure than one counter. Java supplies concurrent
maps, queues, deques, and other collections with documented safety and consistency
guarantees. That protection applies to their operations. It does not turn any
sequence written by the caller into one atomic action.

Consider a cache registration backed by a ConcurrentHashMap:

if (!cache.containsKey(customerId)) {
    cache.put(customerId, loadCustomer(customerId));
}

Even with a concurrent map, another thread can change the map between the check and
the put. ConcurrentMap supplies compound operations such as putIfAbsent,
compute, and merge for transitions covered by their
contracts:¹⁴

cache.computeIfAbsent(customerId, this::loadCustomer);

Use one of those operations when its documented semantics match the state change.
An invariant that spans several map entries or external side effects still needs a
larger design. ConcurrentHashMap documents the guarantees and restrictions of its
computeIfAbsent implementation.¹⁵

BlockingQueue solves another shared-data problem: handing items from producers to
consumers.¹⁶ Its operations let a producer fail immediately,
wait for space, or wait up to a timeout; a consumer has corresponding choices when
the queue is empty. Capacity depends on the implementation. ArrayBlockingQueue is
bounded, while other implementations may be unbounded or have different handoff
semantics.

BlockingQueue<Job> jobs = new ArrayBlockingQueue<>(100);

jobs.put(new Job(customerId)); // waits when this bounded queue is full
Job next = jobs.take();        // waits when it is empty

The queue owns safe transfer of each element. The Job object may still need its
own safe design if producers and consumers mutate it after handoff.

Coordination describes who may proceed

A two-request dependency limit is a coordination policy. A semaphore represents
that policy with permits:

String fetchWithLimit(Semaphore permits, String requestId)
        throws InterruptedException {
    permits.acquire();
    try {
        return dependency.fetch(requestId);
    } finally {
        permits.release();
    }
}

Constructing new Semaphore(2) lets at most two successful acquisitions proceed
at once. The finally block returns the permit when the call completes or fails.
The virtual-thread executor used earlier creates a new virtual thread per task and
does not impose a thread-count bound. JEP 444 recommends keeping that model and
using a semaphore to represent the actual limit on a scarce service.⁶

Other synchronizers encode other policies. A CountDownLatch lets tasks wait until
a count reaches zero, which fits a one-time startup gate. A CyclicBarrier
coordinates a group that must all reach the same phase before continuing. A
BlockingQueue coordinates through data availability and capacity. The
java.util.concurrent synchronizer overview groups these APIs by
policy.¹⁷

These policies do not protect every object touched by the participating tasks. The
semaphore limits calls in the example; it says nothing about the thread safety of
dependency or other shared state. Use a synchronizer when the rule concerns who
may proceed, and analyze shared invariants separately.

Parallel computation splits data or work

The dashboard spends time waiting. A sum over a large collection presents a
different problem: divide computation over data and combine the partial results.

ForkJoinPool is an ExecutorService built around work-stealing and tasks that can
split into smaller tasks. Its contract does not guarantee compensating threads for
blocked I/O or unmanaged synchronization.¹⁸ Do not treat a
fork/join pool as the default executor for many blocking network calls. It is a
better conceptual fit for decomposable computation than for replacing the
waiting-oriented dashboard executor.

Parallel streams expose data-parallel execution through the stream API:

long sum = values.parallelStream()
        .mapToLong(value -> (long) value * value)
        .sum();

This reduction follows the java.util.stream requirements because the mapping is
stateless, it does not modify the source, and addition is
associative.¹⁹ Those properties allow the stream implementation to
partition work and combine partial results safely. Stateful operations,
encounter-order requirements, coordination overhead, small inputs, and the
available processors can change the tradeoff. Calling parallelStream() does not
promise a speedup.

Measure a representative workload before choosing parallel execution for
performance. The appropriate comparison includes the real data size, operation
cost, ordering requirements, and environment. A tiny example can prove behavior;
it cannot establish that production code will run faster.

Choose the responsibility before the class

Start with the sentence that describes the problem. Let the API name come second.

Problem statement	Useful starting point	Check before committing to it
"I need to represent work with or without a result."	`Runnable`, `Callable<V>`	Who owns execution and failure handling?
"I need to run independent waiting operations."	`ExecutorService`; often one virtual thread per task in modern Java	What owns the executor, and what limits scarce dependencies?
"I need to retrieve one result later."	`Future<V>`	Where will waiting happen, and what does cancellation really do?
"I need to transform or combine dependent results."	`CompletableFuture<T>`	Which executor and error policy does each stage use?
"Several tasks update one counter."	`AtomicInteger` or a lock	Does the invariant extend beyond that variable?
"Several tasks share keyed state."	`ConcurrentHashMap` and its compound operations	Is the whole state transition covered by one documented operation?
"Producers hand work to consumers."	A suitable `BlockingQueue`	Should capacity apply backpressure, and which operations may wait?
"Only N tasks may use a dependency."	`Semaphore`	Are permits always released, including on failure?
"I need to divide CPU-oriented computation."	Fork/join or a parallel stream	Is the work large, independent, non-interfering, and measured?

After choosing the responsibility, evaluate lifecycle, failure policy, workload,
contention, ordering, and resource limits before selecting the concrete API.

As a practice exercise, return to the dashboard and write five sentences before
changing its code: which operations are independent, what results they produce,
where waiting is acceptable, what state they share, and which dependency limits
must survive higher concurrency. Each answer points to one part of the map and to
the next piece of documentation or testing the program needs.

Runnable API documentation ↩
Callable<V> API documentation ↩
Thread API documentation ↩
Executor API documentation ↩
ExecutorService API documentation ↩
JEP 444: Virtual Threads ↩
Future<V> API documentation ↩
CompletableFuture<T> API documentation and CompletionStage<T> API documentation. The CompletableFuture policy section also explains that non-async dependent actions may run in the thread that completes the current stage or another caller of a completion method. ↩
Java Language Specification, §17.4.2: Actions ↩
Java Language Specification, §17.4.5: Happens-before Order ↩
java.util.concurrent memory-consistency properties ↩
Lock API documentation ↩
java.util.concurrent.atomic package documentation ↩
ConcurrentMap API documentation ↩
ConcurrentHashMap API documentation ↩
BlockingQueue API documentation ↩
java.util.concurrent synchronizer overview ↩
ForkJoinPool API documentation ↩
java.util.stream package documentation ↩

Demystifying Authentication in Spring Security

esteban389 — Wed, 19 Mar 2025 01:53:51 +0000

Authentication is one of the most fundamental features in modern applications—whether you’re logging into a website, accessing an API, or even verifying a one-time password. If you’re working within the Spring ecosystem, you’ve probably heard of Spring Security, the go-to framework for handling authentication and security.

But let’s be honest… Spring Security can feel overwhelming! 🌀 Between authentication providers, user details, and authentication managers, it’s easy to get lost. If you've ever found yourself wondering "Where does my password even get checked?"—you're not alone!

In this article, I’ll break down authentication in Spring Security into simple, easy-to-follow steps. We’ll compare a basic authentication flow (like checking a username and password) with how Spring Security handles each step under the hood. By the end, you'll have a clear understanding of what’s happening behind the scenes. 🚀

Let’s dive in! 🔍

Understanding Basic Authentication

Before we jump into how Spring Security handles authentication, let’s talk about why we need authentication in the first place. In most applications, you want to control access to certain features or data. That means you need a way to confirm that users are who they say they are. That’s exactly what authentication does!

In a computer system, authentication (“auth” for short) is the process that verifies that a user is who they claim to be. IBM What is Authentication? | IBM

Although web applications can be quite different from each other, the authentication flow is often very similar. A single, generalized flow might cover the vast majority of use cases. Here’s a diagram of a common authentication flow:

Let’s break it down step by step. 🏃‍♂️💨

Visiting the server

It all starts when a user visits your site or makes an initial request to your server. In some cases, the server may include a CSRF token in its response, depending on your security needs (these are steps 1 and 1.1 in the diagram).

Think of the CSRF token as a little “secret handshake” 🤝 that helps protect against certain security attacks.

Request an Authenticated Resource

Next, the user attempts to access a resource that requires authentication—for example, a page or an API endpoint that only logged-in users should see. The server then responds with a prompt for credentials, asking the user to prove they’re really who they claim to be.

Commonly, these credentials are:
Username and password
Email (for sending a magic link)
WebAuthn credentials (hardware security keys, etc.)
Or any other unique proof of identity.

This is all covered in steps 2 to 4 in the diagram. 🛂

Search user

When the user’s credentials arrive at the server, the next step is to look them up in the database (or another storage system).
If the user doesn’t exist, the server immediately returns an error (steps 5 to 7.1).

If the user is found, we move on to the final phase: checking the validity of their credentials.

Authenticate

At this point, the server validates the credentials. The exact process depends on your chosen authentication method:

Username & Password: The server will hash the incoming password and compare it with the hashed password stored in the database.
Magic Link: The server checks if the link’s token is valid and hasn’t expired.
WebAuthn: The server verifies the security challenge with the user’s device or browser.

If the credentials are valid, the server returns a success response along with some identifier—often a session cookie or a token (like a JWT)—so the user doesn’t have to log in again on every request. This corresponds to steps 7.2 and 8 in the diagram.

Think of this identifier as your “I’m logged in” badge. 🏷️

Now that you understand the core concepts, we’ll see how Spring Security manages each of these steps under the hood. Buckle up! 🚀

Mapping Authentication Steps to Spring Security Components

Now that we understand a typical authentication flow, let’s see how Spring Security tackles each step. Before diving in, let’s clear up one thing: if you've tried learning Spring Security before, you might have heard about a lot of additional concepts like CORS, the security filter chain, and more. But for this article, we’re keeping our focus solely on authentication. I’ll be showing you how Spring Security handles authentication in a REST API style. (I’ve personally never used Spring as a full-stack framework, so this approach suits my experience—but don’t worry, the concepts translate easily if you need a full-stack solution!)

Here’s an overall view mapping a standard authentication flow to Spring Security components:

Authentication Flow	Spring Security Component
User submits credentials	`Authentication` (e.g., `UsernamePasswordAuthenticationToken`)
Server searches for user	`UserDetailsService`
Check if user exists	`UsernameNotFoundException`
Verify credentials	`AuthenticationProvider` (e.g., `DaoAuthenticationProvider`)
Authentication success/failure	`AuthenticationManager` orchestrates this
Return authentication identifier	Typically handled by a session or token mechanism

This is a high-level overview of how authentication works within Spring Security. I’ve intentionally skipped some details that we’ll dig into as we break down each part further. Let’s dive in!

Authentication

Every time a user accesses a protected resource, they must prove their identity using credentials. This is where the Authentication interface comes into play. According to the Spring docs, it “represents the token for an authentication request or for an authenticated principal once the request has been processed by the AuthenticationManager.authenticate(Authentication) method.”
The Authentication object contains:

Credentials (e.g., a password)
Permissions/Authorities
Principal (a representation of the authenticated user)
Authentication status (authenticated or not)
And other details regarding the authentication request

A common implementation that you’ll likely use in many projects is the UsernamePasswordAuthenticationToken. Other examples include:

OneTimeTokenAuthenticationToken
AnonymousAuthenticationToken
JwtAuthenticationToken
BearerTokenAuthenticationToken

There are many more out there, or you can roll your own (though I recommend doing so only for learning purposes) 😊.

UserDetailsService

If you’ve spent any time with Spring and the MVC pattern, you’ve likely encountered the concept of services. These act as a bridge between your business logic and your database interactions. In Spring Security, the UserDetailsService is your go-to for retrieving user data.

The interface defines a single method: loadUserByUsername(String username). This method’s job is to:

Locate the user based on the provided username.

Return a UserDetails object representation of the user that focuses on authentication and authorization data.

Remember, your user entity can still have other attributes and extend different classes; the UserDetails interface just provides a focused view for security. You could technically bypass using UserDetailsService or UserDetails if you implement a custom authentication provider, but then you’d be fighting the framework’s conventions.

Spring even offers some default implementations:

InMemoryUserDetailsManager (great for prototyping, since it stores data only in memory)
JdbcDaoImpl (retrieves user details from a database using JDBC queries)
JdbcUserDetailsManager (an enhanced version of JdbcDaoImpl with additional features)

UsernameNotFoundException

When the UserDetailsService can’t find a user, it throws a UsernameNotFoundException. This exception is a subclass of AuthenticationException, the base class for all exceptions related to failed authentication attempts. Other exceptions in this family include:

BadCredentialsException
AuthenticationCredentialsNotFoundException
CompromisedPasswordException

These exceptions help Spring Security signal what went wrong during the authentication process ⚠️.

AuthenticationManager and AuthenticationProvider

Now we’re at the stage where we verify that the credentials are correct 🧐. This is handled by the AuthenticationManager, which processes an Authentication object (remember, the representation of your user’s credentials, whether authenticated or not).

The most common implementation of AuthenticationManager is the ProviderManager. This manager maintains a list of AuthenticationProvider instances and iterates over them until one can successfully handle the authentication request. Here’s a simplified snippet to illustrate this:

public Authentication authenticate(Authentication authentication) throws AuthenticationException {
    Class<? extends Authentication> toTest = authentication.getClass();
    AuthenticationException lastException = null;
    Authentication result = null;

    for (AuthenticationProvider provider : getProviders()) {
            if (!provider.supports(toTest)) {
                continue;
            }
            result = provider.authenticate(authentication);
            if (result != null) {
                copyDetails(authentication, result);
                break;
            }
        }
}

Notice how the ProviderManager checks each provider to see if it supports the type of authentication being attempted. It stops once it finds one that successfully authenticates the request ✅.

The AuthenticationProvider interface itself defines just two methods:

supports(Class<?> authentication): Checks if the provider can handle the given authentication type.
authenticate(Authentication authentication): Contains the logic for verifying the credentials.

Spring Security provides several implementations, like DaoAuthenticationProvider for username/password checks or JwtAuthenticationProvider for JWT-based authentication. For example, a snippet from the JwtAuthenticationProvider might look like this:

    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {
        BearerTokenAuthenticationToken bearer = (BearerTokenAuthenticationToken) authentication;
        Jwt jwt = getJwt(bearer);
        AbstractAuthenticationToken token = this.jwtAuthenticationConverter.convert(jwt);
        if (token.getDetails() == null) {
            token.setDetails(bearer.getDetails());
        }
        this.logger.debug("Authenticated token");
        return token;
    }

    @Override
    public boolean supports(Class<?> authentication) {
        return BearerTokenAuthenticationToken.class.isAssignableFrom(authentication);
    }

In this example, the provider casts the Authentication object to the expected type, processes the JWT, and converts it back to an authenticated token. If a provider returns null, the ProviderManager moves on to the next one. This mechanism ensures that your application finds the right way to authenticate each request 🔍.

Returning a response

At the end of the authentication process, your application needs to return a response. If you’re building your own implementation, this could mean:

Setting a cookie in a cookie-based authentication.
Returning a JWT token for stateless APIs.
Or any other mechanism you choose.

For a quick example, you might create an AuthController with a login endpoint that accepts a record like this:

public record LoginRequest(String username, String passsword){}

This controller would create a UsernamePasswordAuthenticationToken, trigger the authentication process, and then return a response containing either a cookie or a token based on the result.

Diving Deeper: Exploring Spring Security’s Built-In Login Mechanism

So far, we’ve covered the essentials, and you could build your own authentication flow with these pieces. But if you’re curious about the “Spring way” of doing things, here’s a sneak peek into how Spring handles login by default.

Tip: If this next section feels a bit heavy or introduces additional concepts you’re not yet comfortable with, feel free to skip ahead and come back later. Understanding these concepts—even at a high level—will help you grasp how Spring Security works under the hood.

How Does Spring Security Handle Login?

Spring Security provides a default login mechanism, but how does it actually work?

When a user submits their credentials, the request is sent to the configured login endpoint.

Spring Security intercepts this request using a filter, specifically UsernamePasswordAuthenticationFilter.

The filter attempts authentication, following the flow we discussed earlier. If authentication succeeds, Spring Security stores the Authentication object in the SecurityContextHolder. Before responding to the client, the SecurityContextis persisted via a SecurityContextRepository. This sequence allows Spring Security to maintain authentication across multiple requests.

WOW that was a lot of info and new concepts in such a short amount of time right? Let’s, once again, define what we need and how those needs are solved by different components of spring.
First things first,

WHAT THE F*CK IS A FILTER?

Spring Security relies on a Security Filter Chain, a series of filters that process requests and responses. These filters handle security tasks such as authentication, authorization, and CSRF protection.

Architecture::Spring Security

When a client makes an HTTP request:

The request passes through multiple security filters.
The request is authenticated and authorized.
If allowed, it reaches the servlet for further processing.

Spring Boot automatically configures these filters, but you can inspect them with the following example:

    @Bean
    public UserDetailsService inMemoryUserDetails() {
        UserDetails admin = User.builder()
                .username("admin")
                .password("{noop}admin")
                .roles("ADMIN")
                .build();
        return new InMemoryUserDetailsManager(admin);
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
                .authorizeHttpRequests(authorizeHttp -> {
                    authorizeHttp.requestMatchers("/login").permitAll();
                    authorizeHttp.anyRequest().authenticated();
                })
            .formLogin(withDefaults());
        return http.build();
    }

This configuration:

Creates an in-memory admin user.
Enables default login behavior.
Allows access to /login while protecting other endpoints.

Exploring the Security Filter Chain

Spring Security manages filters using a Filter Chain Proxy, which contains one or more Security Filter Chains. The Security Filter Chain is Spring-specific and integrates deeply with the Spring framework, unlike the standard Servlet Filter Chain.
You can inspect the active Security Filter Chains using this endpoint:

    @GetMapping
    private Map<Integer, Map<Integer, String>> getSecurityFilterChainProxy(){
        Map<Integer, Map<Integer, String>> filterChains = new HashMap<>();

        int i = 1;
        for (SecurityFilterChain securityFilterChain : this.filterChainProxy.getFilterChains()){
            Map<Integer, String> filterChain = new HashMap<>();
            int j = 1;
            for (Filter filter : securityFilterChain.getFilters()){
                filterChain.put(j, filter.getClass().getName());
                j++;
            }
            filterChains.put(i, filterChain);
        }

        return filterChains;
    }

Do you remember how i explained the filters work? Well, I kinda lied, spring security actually uses a filter chain proxy to have the filters defined in the Security Filter Chain, which is different from the Filter Chain, while the former is a Spring Thingy and can then take advantage of other spring features like the ApplicationContext, and is actually the one you’ll be using 99.99% of the time, the later is a Servlet thing, the Security Filter Chain is called inside the Filter Chain, you don’t really have to worry too much about those details but if you do want to go deper you can read the spring security documentation on the Servlet Applicatoins / Architecture section
What this endpoint i showed you does is it will get the Security Filter Chains that are registerd in the Filter Chain Proxy (the one that spring wires inside the Servlet Filter Chain) and return the class names of the Filters inside the Security Filter Chain, you will get a response like this

{
    "1": {
        "1": "org.springframework.security.web.session.DisableEncodeUrlFilter",
        "2": "org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter",
        "3": "org.springframework.security.web.context.SecurityContextHolderFilter",
        "4": "org.springframework.security.web.header.HeaderWriterFilter",
        "5": "org.springframework.security.web.csrf.CsrfFilter",
        "6": "org.springframework.security.web.authentication.logout.LogoutFilter",
        "7": "org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter",
        "8": "org.springframework.security.web.authentication.ui.DefaultResourcesFilter",
        "9": "org.springframework.security.web.authentication.ui.DefaultLoginPageGeneratingFilter",
        "10": "org.springframework.security.web.authentication.ui.DefaultLogoutPageGeneratingFilter",
        "11": "org.springframework.security.web.savedrequest.RequestCacheAwareFilter",
        "12": "org.springframework.security.web.servletapi.SecurityContextHolderAwareRequestFilter",
        "13": "org.springframework.security.web.authentication.AnonymousAuthenticationFilter",
        "14": "org.springframework.security.web.access.ExceptionTranslationFilter",
        "15": "org.springframework.security.web.access.intercept.AuthorizationFilter"
    }
}

Key Filters in Spring Security

I’m not gonna explain every single filter but instead let’s go with the ones we care those being:

SecurityContextHolderFilter
Retrieves the SecurityContext for requests.
CsrfFilter
Ensures CSRF tokens are included in requests (if enabled).
LogoutFilter
Manages user logout by calling LogoutHandlers and redirecting upon success.
UsernamePasswordAuthenticationFilter
Handles login requests, extracting credentials and passing them to authentication mechanisms.
DefaultLoginPageGeneratingFilter
Generates the default login page.
DefaultLogoutPageGeneratingFilter
Creates the default logout page.
AnonymousAuthenticationFilter
Assigns anonymous authentication when no user is authenticated.
ExceptionTranslationFilter
Converts AccessDeniedException and AuthenticationException into HTTP responses.
AuthorizationFilter
Enforces authorization policies.

Configuring the Security Filter Chain

Below is an example of configuring key security filters:

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
                .securityContext(securityContextConfigurer ->
                        securityContextConfigurer.securityContextRepository(new MyCustonSecurityContextRepository())
                )
                .csrf(csrfConfigurer -> csrfConfigurer.disable())
                .logout(logoutConfigurer -> {
                    logoutConfigurer.logoutUrl("/logout");
                    logoutConfigurer.invalidateHttpSession(true);
                })
                .formLogin(loginConfigurer -> {
                            loginConfigurer.loginPage("/login");
                            loginConfigurer.failureForwardUrl("/login?error");
                            loginConfigurer.usernameParameter("username");
                        }
                )
                .anonymous(anonymousConfigurer -> {
                    anonymousConfigurer.principal("anonymous");
                })
                .exceptionHandling(exceptionHandlingConfigurer -> {
                    exceptionHandlingConfigurer.accessDeniedPage("/access-denied");
                })
                .authorizeHttpRequests(authorizeHttp -> {
                    authorizeHttp.requestMatchers("/login").permitAll();
                    authorizeHttp.anyRequest().authenticated();
                });
        return http.build();
    }

This configuration:

Defines a custom SecurityContextRepository.
Disables CSRF (if needed).
Customizes login/logout behavior.
Handles anonymous users and access denial.
Enforces authentication for all routes except /login.

This is all good and great but let’s go a little deeper into how the spring team normally implements authentication inside filters, for this we dive into the implementation of the UsernamePasswordAuthenticationFilter, LogoutFilter, AnonymousFilter, SecurityContextHolderFilter and lastly SecurityContextRepository

SecurityContextHolderFilter

Ensures that the SecurityContext is correctly set before proceeding with request handling. Runs early in the filter chain and guarantees that any downstream filters can access security details.

    private void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {
        if (request.getAttribute(FILTER_APPLIED) != null) {
            chain.doFilter(request, response);
            return;
        }
        request.setAttribute(FILTER_APPLIED, Boolean.TRUE);
        Supplier<SecurityContext> deferredContext = this.securityContextRepository.loadDeferredContext(request);
        try {
            this.securityContextHolderStrategy.setDeferredContext(deferredContext);
            chain.doFilter(request, response);
        }
        finally {
            this.securityContextHolderStrategy.clearContext();
            request.removeAttribute(FILTER_APPLIED);
        }
    }

In the implementation you can see that it will check whether the filter has already been applied, if it hasn’t it will pass the method to load the context to the SecurityContextHolder and continue with the next filter.

SecurityContextRepository

Restores and retrieves the SecurityContext during request processing.
Works with session-based authentication to persist the SecurityContext between requests.
Common implementations:
- HttpSessionSecurityContextRepository: Stores the SecurityContext in the HTTP session.
- RequestAttributeSecurityContextRepository: Stores the SecurityContext in request attributes.

AnonymousFilter

Assigns an anonymous Authentication object when no authenticated user is present. It ensures that unauthenticated users still have a valid SecurityContext. The anonymous authentication has a special role (ROLE_ANONYMOUS), allowing fine-grained access control.

Let’s look at a small part of the filter’s implementation

private SecurityContext defaultWithAnonymous(HttpServletRequest request, SecurityContext currentContext) {
    Authentication currentAuthentication = currentContext.getAuthentication();
    if (currentAuthentication == null) {
        Authentication anonymous = createAuthentication(request);
        if (this.logger.isTraceEnabled()) {
            this.logger.trace(LogMessage.of(() -> "Set SecurityContextHolder to " + anonymous));
        }
        else {
            this.logger.debug("Set SecurityContextHolder to anonymous SecurityContext");
        }
        SecurityContext anonymousContext = this.securityContextHolderStrategy.createEmptyContext();
        anonymousContext.setAuthentication(anonymous);
        return anonymousContext;
    }
    else {
        if (this.logger.isTraceEnabled()) {
            this.logger.trace(LogMessage.of(() -> "Did not set SecurityContextHolder since already authenticated "
                    + currentAuthentication));
        }
    }
    return currentContext;
}

protected Authentication createAuthentication(HttpServletRequest request) {
    AnonymousAuthenticationToken token = new AnonymousAuthenticationToken(this.key, this.principal,
            this.authorities);
    token.setDetails(this.authenticationDetailsSource.buildDetails(request));
    return token;
}

This two methods are the ones we actually care about for the purposes of this article, the defeaultWithAnonymous method will get the current authentication and check if it’s null, if it isn’t it logs that it wasn’t necessary to set the SecurityContextHolder, if it is, it creates an AnonymousAuthenticationToken and then an empty context and sets the authentication in it, finally it returns the SecurityContext, the anonymous token will use a key, a principal as a String (which you can configure as you saw in the example) and the details, the details willfrom the http request and those will be the ip address and the session id

UsernamePasswordAuthenticationFilter

This filter a little bit special, normally when you want to create a filter to add to the spring security filter chain you would extend your class with either GenericFilterBeanor OncePerRequestFilter but the filters that deal with broswer based http based authentications such as this filter or Oauth2LoginAuthenticationFilter, WebAuthnAuthenticationFilter, etc…, they extend a different class instead, the AbstractAuthenticationProcessingFilter this filter will require an AuthenticationManager to process the authentication request and a RequestMatcher to check if it should attempt authentication for the current request, it has three important methods the attemptAuthentication which will receive both the request and response objects and will perform the actual authentication, if the authentication passess the Authentication result will be placed into the SecurityContext and it will call a configured AuthenticationSuccessHandler and if it fails it will delegate to a configured AuthenticationFailurehandler
From the actual implementation of the UsernamePasswordAuthenticationFilter we see relatively how simple this is

@Override
    public Authentication attemptAuthentication(HttpServletRequest request, HttpServletResponse response)
            throws AuthenticationException {
        if (this.postOnly && !request.getMethod().equals("POST")) {
            throw new AuthenticationServiceException("Authentication method not supported: " + request.getMethod());
        }
        String username = obtainUsername(request);
        username = (username != null) ? username.trim() : "";
        String password = obtainPassword(request);
        password = (password != null) ? password : "";
        UsernamePasswordAuthenticationToken authRequest = UsernamePasswordAuthenticationToken.unauthenticated(username,
                password);
        // Allow subclasses to set the "details" property
        setDetails(request, authRequest);
        return this.getAuthenticationManager().authenticate(authRequest);
    }

It first checks if it must be a post request and then it obtains both the username and password, it creates an Authentication with the details from the request and lastly it passes this Authentication to the AuthenticationManager
now let’s see how this is used in the AbstractAuthenticationProcessingFilter

    private void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws IOException, ServletException {
        if (!this.requiresAuthentication(request, response)) {
            chain.doFilter(request, response);
        } else {
            try {
                Authentication authenticationResult = this.attemptAuthentication(request, response);
                if (authenticationResult == null) {
                    return;
                }

                this.sessionStrategy.onAuthentication(authenticationResult, request, response);
                if (this.continueChainBeforeSuccessfulAuthentication) {
                    chain.doFilter(request, response);
                }

                this.successfulAuthentication(request, response, chain, authenticationResult);
            } catch (InternalAuthenticationServiceException failed) {
                this.logger.error("An internal error occurred while trying to authenticate the user.", failed);
                this.unsuccessfulAuthentication(request, response, failed);
            } catch (AuthenticationException ex) {
                this.unsuccessfulAuthentication(request, response, ex);
            }

        }
    }

    protected boolean requiresAuthentication(HttpServletRequest request, HttpServletResponse response) {
        if (this.requiresAuthenticationRequestMatcher.matches(request)) {
            return true;
        } else {
            if (this.logger.isTraceEnabled()) {
                this.logger.trace(LogMessage.format("Did not match request to %s", this.requiresAuthenticationRequestMatcher));
            }

            return false;
        }
    }

It will use the configured RequestMatcher to check if it should perform authentication and then it will call the attemptAuthentication method, if it is successful it will perform some aditional operations (not really important for the purposes of this article) and lastly it will use the succesfulAuthentication method which in turn will use the handler we passed, if it fails it will use the unsuccessfulAuthenticationmethod which uses our failure handler

protected void successfulAuthentication(HttpServletRequest request, HttpServletResponse response, FilterChain chain,
            Authentication authResult) throws IOException, ServletException {
        SecurityContext context = this.securityContextHolderStrategy.createEmptyContext();
        context.setAuthentication(authResult);
        this.securityContextHolderStrategy.setContext(context);
        this.securityContextRepository.saveContext(context, request, response);
        if (this.logger.isDebugEnabled()) {
            this.logger.debug(LogMessage.format("Set SecurityContextHolder to %s", authResult));
        }
        this.rememberMeServices.loginSuccess(request, response, authResult);
        if (this.eventPublisher != null) {
            this.eventPublisher.publishEvent(new InteractiveAuthenticationSuccessEvent(authResult, this.getClass()));
        }
        this.successHandler.onAuthenticationSuccess(request, response, authResult);
    }

Here we can see that it will do some aditional logic like event publishing, remember me services, etc…, but the part i want to highlight is the save of the context using the SecurityContextRepository this bean comes from the configuration, so let’s talk a little about the configuration of these special filters.

The default implementations of these filters are typically configured with the HttpSecurity builder spring provides for the SecurityFilterChain configuration, more specifically it will use special classes that extend the AbstractAuthenticationFilterConfigurer like the FormLoginConfigurer and such, allow me to show a small part of the code in this abstract class:

@Override
public void configure(B http) throws Exception {
    ...
    SecurityContextConfigurer securityContextConfigurer = http.getConfigurer(SecurityContextConfigurer.class);
    if (securityContextConfigurer != null && securityContextConfigurer.isRequireExplicitSave()) {
        SecurityContextRepository securityContextRepository = securityContextConfigurer
            .getSecurityContextRepository();
        this.authFilter.setSecurityContextRepository(securityContextRepository);
    }
    this.authFilter.setSecurityContextHolderStrategy(getSecurityContextHolderStrategy());
    F filter = postProcess(this.authFilter);
    http.addFilter(filter);
}

As you can see here it will use another configurer to get the repository that is going to be needed to save (and restore) the sessions if it was configured as such, do you remember the filter chain configuration example I showed where i provided a configuration example for each of the relevant filters? well, in that example the .securityContext() method is the SecurityContextConfigurer, let’s go see what repository it uses by default

SecurityContextRepository getSecurityContextRepository() {
    SecurityContextRepository securityContextRepository = getBuilder()
        .getSharedObject(SecurityContextRepository.class);
    if (securityContextRepository == null) {
        securityContextRepository = new DelegatingSecurityContextRepository(
                new RequestAttributeSecurityContextRepository(), new HttpSessionSecurityContextRepository());
    }
    return securityContextRepository;
}

As you can see here, it will use either the one you pass to the configuration or a DelegatingSecurityContextRepository one which is composed of the RequestAttributeSecurityContextRepository (it persits the context on the current request only) and the HttpSessionSecurityContextRepository (it persits the context on the http session) if you didn’t configure one, although there are some small extra details they are not exactly a must to understand the rest.

LogoutFilter

It uses a series of LogoutHandlers which will be used in the order they are specified, after a succesful logout it will perform a redirect using either the LogoutSuccessHandler or the logoutSuccessUrl configured.

The implementation of this filter is pretty similar to the previous one so instead of showing it I willl show you the implementation of a logout handler that spring provides.

@Override
    public void logout(HttpServletRequest request, HttpServletResponse response, Authentication authentication) {
        Assert.notNull(request, "HttpServletRequest required");
        if (this.invalidateHttpSession) {
            HttpSession session = request.getSession(false);
            if (session != null) {
                session.invalidate();
                if (this.logger.isDebugEnabled()) {
                    this.logger.debug(LogMessage.format("Invalidated session %s", session.getId()));
                }
            }
        }
        SecurityContext context = this.securityContextHolderStrategy.getContext();
        this.securityContextHolderStrategy.clearContext();
        if (this.clearAuthentication) {
            context.setAuthentication(null);
        }
        SecurityContext emptyContext = this.securityContextHolderStrategy.createEmptyContext();
        this.securityContextRepository.saveContext(emptyContext, request, response);
    }

This code comes from the SecurityContextLogoutHandler which is one of the default ones spring security uses, it will assert that there is a request, if configured it will invalidate the session, then it will clear the context and if set, it will also clear the authentication it will also use the SecurityContextRepository to update the context to unauthenticated.

Conclusion & What’s Next

So far we’ve explored the key components involved in Spring Security’s authentication flow, from simple things like the Authentication interface to more complext parts like the SecurityContextRepository, by understanding how these parts work together we can gain a deeper insight into how Spring Security manages authentication behind the scenes and allows you to write your own implementations or decide whether you should you the default ones or not.

Looking ahead, I plan to write follow-up articles exploring custom authentication implementations, such as integrating alternative authentication mechanisms beyond username-password authentication. I may also cover different Spring Security configurations, including OAuth2, JWT-based authentication, and fine-grained access control strategies.

If you’re interested in diving deeper into these topics, stay tuned for upcoming posts where we’ll explore practical examples and real-world use cases. 🚀

Do keep in mind that i’m by no means an expert in either security or spring so I will need lots and lots of documentation which means posting each article will take time, please comment any questions or sugestions you may have I'd be glad to read your thoughts 😁, with nothing else left to say, bye and best regards. 🎉🎉🎉