DEV Community: srinivas reddy gouru

How Spring Security works with JWT, OAuth2, and SSO

srinivas reddy gouru — Tue, 26 May 2026 17:43:05 +0000

The 401 You Never Wrote: What Spring Security Actually Does Out of the Box

Spring Security is a framework that intercepts every HTTP request entering your application and enforces authentication and authorisation rules before that request ever reaches a controller. You do not write the interception logic yourself; adding the spring-boot-starter-security dependency to a Spring Boot project is enough to activate a default configuration that locks down every endpoint and returns a 401 (or redirects to /login) for any unauthenticated caller. No annotations, no filters, no @PreAuthorize, just a single dependency, and suddenly your previously open API is asking for credentials.

That out-of-the-box behaviour surprises a lot of engineers the first time they see it, but it reflects a deliberate design choice: security should be the default, not something you opt into. The alternative, checking credentials inside each controller method, means one forgotten check equals one unprotected route. Spring Security removes that category of mistake entirely by applying rules uniformly at the HTTP layer, before a single line of your business logic runs.

What makes this possible is the security filter chain. Spring Security is not a single interceptor sitting in front of your application; it is a carefully ordered sequence of servlet filters, each responsible for one concern. One filter handles CSRF token validation. Another manages session creation and lookup. Another reads the Authorisation header and tries to resolve a credential. Another checks whether the resolved identity actually has permission to reach the requested URL. These filters run in a fixed order on every incoming request, and each one can either pass the request downstream or short-circuit the chain with an error response.

At the centre of this pipeline sits the SecurityContext. By the time the authorisation filters run, the chain expects someone to have placed an Authentication object into the context, a wrapper that holds the verified identity (the principal) and the roles or authorities it carries. If the context is empty when the authorisation filter runs, the chain treats the caller as anonymous. If the requested URL requires an authenticated user, the request is rejected before your controller is ever invoked.

This is the mental model that makes all of Spring Security coherent: a pipeline of filters, a shared context object, and one job delegated to whichever filter is responsible for your chosen credential mechanism. Every token mechanism you'll configure, JWT, OAuth2, SSO, is simply a different strategy for putting that principal into the context. Get that strategy wrong, or register it at the wrong point in the chain, and you'll keep seeing 401s that your controllers never threw.

The FilterChain: Spring Security's Request Processing Pipeline

Every HTTP request that reaches a Spring application passes through a structure called the SecurityFilterChain before it ever touches a controller. Understanding this chain is what separates confident Spring Security configuration from trial-and-error annotation hunting.

Spring Security enters the picture through a DelegatingFilterProxy, a thin Servlet filter that the framework registers with the container at startup. [1] Its only job is to hand the request off to Spring's application context, where the real work happens inside a SecurityFilterChain: an ordered list of Spring-managed filters, each responsible for one specific concern. [1] [2] Think of it as a pipeline where each stage either passes the request forward, modifies it, or short-circuits the whole chain by writing a response directly, returning a 401, for example, before the request ever reaches your business logic.

The order of filters in that chain is not arbitrary. Spring Security ships with defaults that place CSRF protection early, session management in the middle, and the authorisation check (AuthorizationFilter) near the end. Authentication filters, wherever you insert them, must run before that authorisation check, because authorisation reads from something the authentication filter writes: the SecurityContextHolder.

The SecurityContextHolder is a thread-local container that holds the SecurityContext, and the SecurityContext holds the Authentication object for the current request. [1] [1] When an authentication filter validates a credential and calls SecurityContextHolder.getContext().setAuthentication(...), it is essentially leaving a note for every filter that comes after it: "this request belongs to a principal with these roles." The authorisation filter at the end of the chain reads that note and decides whether the principal's roles satisfy the rules you configured for that endpoint. If no authentication filter populates the context, the authorisation filter finds an anonymous token and rejects the request accordingly.

This design has a practical consequence for configuration. When you call http.addFilterBefore(myFilter, UsernamePasswordAuthenticationFilter.class) or addFilterAfter, you are specifying exactly where in this ordered pipeline your logic runs. [2] Getting that position wrong is one of the most common sources of mysterious 403 responses, because a filter that runs after the authorisation check can no longer influence the outcome of that check.

Each of the three token mechanisms covered in the next sections plugs into this chain at a different point and populates the SecurityContextHolder in a different way. A JWT filter reads the Authorisation header, validates the token cryptographically, and sets the authentication directly, all within a single filter. OAuth2's resource server support does something similar but delegates signature verification to a remote or locally cached JWK set. SSO flows are different again: they redirect the browser entirely, establish a session on return, and then rely on a session-reading filter to restore the SecurityContext on subsequent requests. Same chain, same SecurityContextHolder contract, three different plug-in points. That consistency is what makes Spring Security composable once you internalise the pipeline model.

JWT Authentication: Stateless Token Validation in the Filter Chain

With the filter chain's structure in mind, it's worth seeing exactly how a real token mechanism plugs into it. JWT is the most common starting point, partly because it requires no session storage and no round-trip to an authorisation server; the token itself carries everything the application needs to make an access decision.

When a client sends a request to a secured endpoint, it includes a bearer token in the Authorisation header. Spring Security doesn't know what to do with that header on its own; nothing in the default chain extracts a JWT. That gap is your extension point. You create a filter that extends OncePerRequestFilter, extract the token from the header, validate its signature and expiry, and then construct an Authentication object that you write into the SecurityContextHolder. [1] From that moment forward in the chain, the request looks just like any other authenticated request; downstream filters and your controllers see a populated security context and never need to know a JWT was involved.

Position matters here. Your custom filter must be registered before UsernamePasswordAuthenticationFilter in the chain, which you do with addFilterBefore in your SecurityFilterChain configuration. If it runs after the authorisation filters have already evaluated the request, the SecurityContext will be empty at the moment it counts, and the request will be rejected as unauthenticated regardless of whether the token was valid.

@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

 private final JwtUtility jwtUtility;
 private final UserDetailsService userDetailsService;

 @Override
 protected void doFilterInternal(HttpServletRequest request,
 HttpServletResponse response,
 FilterChain filterChain)
 throws ServletException, IOException {

 String authHeader = request.getHeader(HttpHeaders.AUTHORIZATION);
 if (authHeader == null ||!authHeader.startsWith("Bearer ")) {
 filterChain.doFilter(request, response);
 return;
 }

 String token = authHeader.substring(7);
 String username = jwtUtility.extractUsername(token);

 if (username!= null && SecurityContextHolder.getContext().getAuthentication() == null) {
 UserDetails user = userDetailsService.loadUserByUsername(username);
 if (jwtUtility.isTokenValid(token, user)) {
 UsernamePasswordAuthenticationToken auth =
 new UsernamePasswordAuthenticationToken(user, null, user.getAuthorities());
 auth.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
 SecurityContextHolder.getContext().setAuthentication(auth);
 }
 }
 filterChain.doFilter(request, response);
 }
}

Because the server stores no session state, every request must be validated independently. The filter re-verifies the signature and the expiry claim on each call. This is what makes JWT genuinely stateless: the token is self-contained, and the server-side footprint is just the public key or shared secret used for verification.

The filter is also the right place to handle more advanced concerns. Token revocation, for example, can be layered in by checking a blocklist inside the same doFilterInternal method before the Authentication object is written to the context. Compromised password detection follows the same pattern. The filter becomes the single choke point for every token lifecycle decision, which keeps your authorisation logic clean and your business controllers unaware of authentication mechanics.

OAuth2 Login & Resource Server: Delegating Trust to an Authorisation Server

Where JWT authentication is a two-party handshake between your application and the token, OAuth2 introduces a third party: an authorisation server that your application has to coordinate with in real time. Spring Security handles all of that coordination, but you need to tell it which role your application is playing, because the configuration and the filter chain behaviour are meaningfully different depending on the answer.

Spring Security's OAuth2 support draws a clean line between two roles. oauth2Login() configures your application as an OAuth2 client: it performs the redirect to the authorization server, receives the callback, exchanges the authorization code for tokens, and logs the user in. oauth2ResourceServer() configures your application as an API backend that accepts and validates bearer tokens issued by an external authorization server. These two modes are not interchangeable. A browser-facing web app typically uses oauth2Login(); a REST API consumed by other services typically uses oauth2ResourceServer(). Some architectures need both in separate security filter chains.

In the Authorisation Code flow, OAuth2LoginAuthenticationFilter does the heavy lifting on the client side. When the authorisation server redirects the browser back to your app with a ?code=... parameter, this filter intercepts the request, calls the authorisation server's token endpoint to exchange the code for an access token and ID token, loads the user's identity from the user-info endpoint or from the ID token directly, and populates the SecurityContext. You do not write any of that exchange logic yourself. The minimal configuration to enable it looks like this:

@Configuration
@EnableWebSecurity
public class SecurityConfig {

 @Bean
 public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
 http
.authorizeHttpRequests(auth -> auth
.anyRequest().authenticated()
 )
.oauth2Login(Customizer.withDefaults());
 return http.build();
 }
}

Spring Boot auto-configuration picks up the client registration details from application.yml, client ID, client secret, authorisation URI, and token URI, so the Java config stays short.

On the resource server side, oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt) swaps in a BearerTokenAuthenticationFilter that reads the Authorisation: Bearer... header, validates the JWT's signature against the authorisation server's published JWKS endpoint, and populates the SecurityContext with the decoded claims. Introspection, calling the authorisation server's introspect endpoint on every request instead of validating locally, is also supported, and is the right choice when you need real-time token revocation checks rather than relying on a short expiry window.

Token lifecycle is another area where Spring Security saves work. When a stored access token has expired, the OAuth2 client support automatically attempts a refresh token grant before forwarding the request. Your application layer never sees the expired token.

One configuration pitfall is worth calling out explicitly. If you want to run custom logic after the token endpoint responds, setting a cookie from the token, for example, that logic must be placed inside the SecurityFilterChain at the correct position using addFilterAfter(), not in a plain servlet filter sitting outside Spring Security. Filters registered outside the chain execute at a different point in the request lifecycle and cannot reliably observe the outcome of Spring Security's token processing.

SSO with Spring Security: Session-Backed Identity Federation

The sharpest difference between SSO and the JWT path covered earlier is not in the configuration, it's in what survives a request boundary. JWT authentication is stateless: every request carries its own proof of identity in the Authorization header, and the filter validates that proof from scratch each time. SSO via oauth2Login() works the opposite way. Once a user completes the redirect dance with the identity provider, Spring Security stores the resulting Authentication object in the HTTP session, and every subsequent request is resolved against that session rather than against a fresh token.

That session-backed model is what makes SSO feel seamless to the end user: they authenticate once with Google or GitHub, get redirected back to your application, and from that point on the browser's session cookie is the credential. The identity provider is not consulted again until the session expires or the user explicitly signs out.

The application.yml registration for a Google-backed SSO looks like this:

spring:
 security:
 oauth2:
 client:
 registration:
 google:
 client-id: YOUR_CLIENT_ID
 client-secret: YOUR_CLIENT_SECRET
 scope: openid, profile, email
 provider:
 google:
 authorization-uri: https://accounts.google.com/o/oauth2/v2/auth
 token-uri: https://oauth2.googleapis.com/token
 user-info-uri: https://www.googleapis.com/oauth2/v3/userinfo

The Java security configuration that activates this is identical to the OAuth2 Login example in the previous section, http.oauth2Login() is all that's needed, with no additional filter registration. What changes is what happens inside the filter chain after the callback completes.

In the JWT path, SecurityContextHolderFilter reconstructs the SecurityContext on every request by validating the bearer token. In the SSO path, the same filter reconstructs the SecurityContext by reading it from the HttpSession, no token validation occurs because the session already holds a fully populated OAuth2AuthenticationToken. That is the meaningful delta: the persistence strategy changes from token-per-request to session-per-user, and SecurityContextHolderFilter adapts accordingly through HttpSessionSecurityContextRepository rather than the stateless repository wired in the JWT configuration.

The older @EnableOAuth2Sso annotation from the Spring Security OAuth2 legacy project achieved the same redirect-and-session behaviour, but required you to manually wire an OAuth2ClientContext and build an OAuth2ClientAuthenticationProcessingFilter yourself. Spring Security 5's native oauth2Login() DSL absorbed all of that plumbing, which is why a single YAML block and one DSL method call are now sufficient for a fully working SSO integration against Google, GitHub, or any standards-compliant identity provider.

One practical implication worth naming: because the session holds the Authentication, horizontal scaling requires either sticky sessions or a shared session store like Redis. This is the trade-off you accept relative to the stateless JWT model, where any node can validate a request independently.

Comparing the Three Mechanisms: Which Hook, Which Flow, Which Config

The three token mechanisms are not strict alternatives to one another, they solve slightly different problems, and they plug into the filter chain at different points. Knowing which slot each one occupies is the fastest way to choose between them and to diagnose failures when they occur.

JWT authentication is the right choice for stateless APIs and microservices where no session should be kept server-side. Your application is the sole verifier of the token: it checks the signature, extracts claims, and populates the SecurityContext, all within a single OncePerRequestFilter placed before UsernamePasswordAuthenticationFilter. Nothing about the user's identity is stored between requests.

OAuth2 resource server configuration is appropriate when a separate authorisation server issues tokens, and your application should validate them against a well-known JWKS endpoint. Spring's built-in BearerTokenAuthenticationFilter handles the extraction and delegates to the JwtDecoder you configure, so you write almost no filter code yourself. The trust anchor is the authorisation server's public key, not anything your application generates.

SSO via oauth2Login applies when a browser-based user needs to authenticate once and have that identity recognised across multiple applications. It reuses the same OAuth2LoginAuthenticationFilter that handles a standard OAuth2 login callback, but the session becomes the persistence mechanism rather than a token the client presents on each request. The identity provider, not your application, manages when that session expires.

When a 401 appears, and you need to find out why, the filter chain position is almost always the first thing worth examining. In a JWT setup, a silent 401 with no accompanying error body usually means one of two things: the custom filter ran but did not write to the SecurityContext, or the filter was registered at a position that places it after the authorisation check rather than before it. In an OAuth2 resource server setup, the failure is more often a misconfigured issuer-uri or an expired token that the decoder rejects. In an SSO setup, a 302 redirect rather than a 401 is the more common symptom; the session wasn't found, so the user is sent back to the identity provider.

The filter chain is the right mental model to carry into all three of these situations. Once you see JWT validation, OAuth2 token introspection, and SSO session lookup as separate plug-ins wired into the same ordered pipeline, the framework stops behaving like an unpredictable wall and starts behaving like a predictable sequence you can reason about step by step. Every 401 is answerable by asking: which filter was responsible for this request, did it run, and if it ran, did it write to the SecurityContext? You can make that question concrete immediately by enabling TRACE logging on org.springframework.security, the output prints each filter in the chain as it executes, which turns a confusing status code into a visible gap in the sequence. That visibility is a direct consequence of the model: when you understand the pipeline, you know exactly where to look.

Sources

How Spring Data JPA, JPA, and Hibernate work together

srinivas reddy gouru — Tue, 26 May 2026 17:24:05 +0000

The Magic Line That Raises the Right Question

Spring Data JPA is a library that lets you query a relational database by writing a Java interface method and nothing else: no SQL, no ResultSet parsing, no PreparedStatement boilerplate. You declare what you want, and the framework figures out how to fetch it.

Here is the moment that stops most backend engineers in their tracks:

public interface UserRepository extends JpaRepository<User, Long> {
 Optional<User> findByEmail(String email);
}

That is the entire implementation. You inject UserRepository into a service, call userRepository.findByEmail("alice@example.com"), and get back a populated User object from the database. [1] The method works on the first try, which is satisfying until something breaks, or until you need to understand why a query is slow, why a LazyInitializationException keeps appearing, or why your transaction did not roll back the way you expected.

At that point, the magic stops feeling helpful and starts feeling like a wall.

The wall exists because findByEmail is not a single thing. It is the visible surface of three separate layers, each with its own responsibilities, failure modes, and configuration surface. Spring Data JPA translated your method name into a query. JPA, the Java Persistence API, provided the standard contract that queries had to follow. Hibernate actually executed it against the database. Without knowing which layer owns which job, you cannot know which layer to look at when something goes wrong.

To answer why that one line works, you need a clear picture of all three layers. That is what the rest of this article builds.

Three Layers, Three Jobs: The Stack in One Mental Model

When you call findByEmail("alice@example.com") on a repository interface you never implemented, what actually runs? The answer involves three distinct layers, each with a single clear job, and conflating any two of them is the source of most of the confusion engineers run into.

At the bottom sits Hibernate. Hibernate is a full ORM framework. It owns a SessionFactory, manages an in-memory representation of your entities, generates SQL, and fires that SQL over JDBC to the database. [2] When things go wrong at the database level, a bad join, an unexpected number of queries, or a lazy-loading exception, Hibernate is the layer to examine.

In the middle sits JPA (Java Persistence API). JPA is not a library you can download and run; it is a specification, a set of interfaces, annotations, and contracts that any compliant ORM must honour. [3] It defines what @Entity, @OneToMany, and EntityManager mean, but it ships no implementation of its own. Hibernate is Spring Boot's default JPA provider, meaning Hibernate is the concrete code that fulfils those contracts. [2] This distinction matters because your annotations belong to JPA, while the SQL they produce belongs to Hibernate.

At the top sits Spring Data JPA. Its sole job is to eliminate boilerplate in the data-access layer. [1] You write a repository interface; Spring generates a proxy implementation at startup that translates method names and annotations into JPA operations. [1] Spring Data JPA does not talk to your database directly, and it is not itself an ORM. Every call it receives flows downward through JPA's EntityManager and on into Hibernate, which finally issues the JDBC call.

Laid out as a delegation chain, the flow looks like this:

Your code
 → Spring Data JPA (repository proxy)
 → JPA EntityManager (standard contract)
 → Hibernate (SQL generation + JDBC)
 → Database

Each arrow in that chain crosses a responsibility boundary. Spring Data JPA knows about Spring conventions and method-name patterns. JPA knows about entities and the persistence context lifecycle. Hibernate knows about SQL dialects and connection pooling. None of the three layers was designed to do each other's jobs, which is exactly why each one is replaceable in theory. You could swap Hibernate for EclipseLink and keep all your JPA annotations untouched, or swap Spring Data JPA for plain EntityManager calls and keep Hibernate doing exactly what it already does.

Keeping this map in your head pays off the moment something goes wrong. A LazyInitializationException is a Hibernate story. A @Transactional annotation that seems to do nothing is a Spring story. A repository method that generates a query you didn't expect is a Spring Data JPA story, though Hibernate ultimately executes it. The next three sections go bottom-up through the stack, starting with the layer that actually touches your database.

Hibernate: The Engine That Actually Talks to the Database

When your Spring application saves an entity and an SQL INSERT appears in the logs, Hibernate wrote that statement. It is an Object-Relational Mapping framework whose single job is bridging the gap between Java objects and relational tables, translating method calls and object state into the SQL your database actually understands, so you don't have to hand-write every query for routine CRUD operations. [2]

At the centre of Hibernate's runtime is the SessionFactory, a heavyweight, thread-safe object built once at application startup. From that factory, Hibernate creates per-request Session instances (or, in the JPA vocabulary you'll see more often in Spring code, EntityManager instances). Those per-request objects are not thread-safe, so Spring handles their lifecycle carefully. The EntityManager you inject with @PersistenceContext is actually a thread-bound proxy that delegates to whichever transactional EntityManager is currently active for that request, falling back to a freshly created one if no transaction is in progress. [4] That indirection is invisible in normal usage but matters when you start debugging concurrency issues.

Several behaviours that surface as runtime surprises are owned entirely by Hibernate, not by the layers above it.

Dirty checking is one of the most useful and least understood. Inside an active transaction, Hibernate holds a snapshot of every entity it has loaded. When the transaction commits, it compares current field values against those snapshots and issues UPDATE statements automatically for anything that changed, even if you never called save(). This is a feature, but it confuses engineers who expect no SQL to run unless they explicitly persist something.

First-level cache (the session cache) means that within a single EntityManager lifetime, calling find(User.class, 1L) twice returns the same Java object from memory on the second call, with no second database round-trip. This cache is scoped to the session, not the application, so it disappears when the session closes.

Lazy loading lets Hibernate defer fetching associated collections until your code actually accesses them. A User with a @OneToMany list of Orders won't load those orders until you call user.getOrders(). The downside is the N+1 problem: if you load 50 users in a list and then touch .getOrders() for each one inside a loop, Hibernate fires one query to fetch the users and then 50 separate queries to fetch each user's orders. The fix usually involves a JOIN FETCH in your query or switching the fetch type, but the first step is recognising that Hibernate is what's generating those 50 extra statements.

SQL dialect translation means Hibernate handles the differences between database engines. You configure spring.jpa.database-platform to point at a dialect class, and Hibernate adapts its generated SQL to match the syntax of PostgreSQL, MySQL, Oracle, or whatever you're running.

All of these behaviours, dirty checking, caching, lazy loading, dialect generation, live at the Hibernate layer. When something breaks, the explanation usually lives there too. The layer above it, JPA, doesn't implement any of this; it just defines the contract that Hibernate must honour.

JPA: The Standard Contract Every ORM Must Honour

The previous section covered what Hibernate actually does at runtime. But if you look at a typical Spring Boot entity class, you'll notice the imports don't say org.hibernate.*. They say jakarta.persistence.* (or javax.persistence.* on older versions). That's JPA, and understanding why it's there clarifies the whole stack.

JPA, the Jakarta Persistence API, is a specification, not a library you run. It defines a set of interfaces, annotations, and rules that any compliant ORM must implement. [2] The annotations you use every day, @Entity, @Id, @OneToMany, @Column, are all defined by JPA. The central API for interacting with the persistence context, EntityManager, is also defined by JPA, with methods like persist, find, merge, and remove. Hibernate is simply the most popular implementation of that contract.

This separation matters practically. Because your application code targets JPA interfaces rather than Hibernate-specific classes, you could swap Hibernate for EclipseLink or OpenJPA and recompile without touching your entity or service code. In practice, most teams never make that swap, but portability isn't the only benefit. The bigger win is that JPA gives the whole Java ecosystem a shared vocabulary. Documentation, Stack Overflow answers, and framework libraries all speak JPA, even when each is backed by a different provider.

JPA also introduced JPQL, the Java Persistence Query Language, which lets you query against entity class names and field names rather than table and column names. A JPQL query looks like this:

TypedQuery<Order> query = entityManager.createQuery(
 "SELECT o FROM Order o WHERE o.customer.email =:email", Order.class
);
query.setParameter("email", "alice@example.com");
List<Order> orders = query.getResultList();

Compare that to raw JDBC, where you would write a SQL string against orders.customer_email, manually open a ResultSet, and map each column back to a field by hand. [5] JPQL keeps queries at the object level, so renaming a Java field and its corresponding column mapping stays in one place rather than scattered across SQL strings throughout the codebase.

The honest limitation of plain JPA is that it still requires you to wire up an EntityManagerFactory, manage EntityManager lifecycles, write those createQuery calls, and handle transactions explicitly. For a small application that's manageable. For a service with thirty entity types and hundreds of queries, it becomes a lot of repeated structural code. That gap is exactly what Spring Data JPA was designed to close.

Spring Data JPA: The Boilerplate Eliminator on Top

With the JPA specification and Hibernate's implementation both accounted for, the question that opened this article is still hanging: where exactly does findByEmail() come from? You never wrote a SQL query, never touched an EntityManager, never defined a concrete class. The answer lives entirely in Spring Data JPA's repository abstraction.

When your application starts up, Spring Data JPA scans for interfaces that extend JpaRepository (or one of its parent interfaces) and generates concrete implementations on the fly. [1] No DAO class needs to be written, because Spring creates a proxy object that wires in the actual behaviour at startup, before any request arrives. That proxy is what gets injected into your service layer when you use @Autowired or constructor injection.

The method-name translation is the part that feels most like magic. Spring Data JPA parses the method signature using reflection, breaks it down by the keywords it recognises (findBy, And, Or, OrderBy, Between, and so on), and constructs a JPQL query to match. A method named findByLastNameAndAgeGreaterThan becomes something like SELECT u FROM User u WHERE u.lastName =:lastName AND u.age >:age, assembled at startup rather than at call time. If you make a typo in the method name that produces an unresolvable expression, the application will fail to start, not fail at 2 AM when that code path is first hit in production.

public interface UserRepository extends JpaRepository<User, Long> {
 List<User> findByLastName(String lastName);
 Optional<User> findByEmail(String email);
 List<User> findByAgeGreaterThanOrderByLastNameAsc(int age);
}

That is the entire file. Spring Data JPA does the rest.

When one of these methods is called at runtime, the proxy delegates to a SimpleJpaRepository implementation under the hood, which in turn uses a JPA EntityManager to execute the translated query. That EntityManager call flows down to Hibernate, which generates the SQL and sends it to the database. The call chain traverses all three layers: your repository interface, the JPA EntityManager, and Hibernate's SQL engine.

Spring Data JPA is part of the broader Spring Data umbrella project, which applies the same repository abstraction pattern to MongoDB, Redis, Cassandra, and other stores. Switching from a relational database to MongoDB doesn't require learning an entirely different programming model. You extend a MongoDB-specific repository interface, and the query derivation works the same way. That consistency is the deeper goal of Spring Data JPA's design.

Derived query methods cover a large surface area, but they are not the only option. For anything complex, @Query lets you write JPQL (or even native SQL with nativeQuery = true) directly on the method. The proxy mechanism stays in place; only the query source changes. This means you can stay in the repository interface without writing any implementation code, even for queries that method-name derivation cannot express cleanly.

Knowing which layer owns which behaviour is immediately useful when things go wrong.

When the Magic Breaks: Debugging Across the Three Layers

Each failure mode has a home layer, and pointing your debugger at the wrong one wastes time.

LazyInitializationException, Hibernate's session is closed

This exception means Hibernate tried to load a lazy association, looked for an open persistence context, and found none. [4] It is a Hibernate-layer error about session lifecycle, not a Spring Data JPA bug. The usual cause is accessing a @OneToMany collection after the repository method has returned and the EntityManager has closed. [2] Fix it at the layer that owns sessions: either annotate the calling service method with @Transactional so the persistence context stays open while you traverse the association, or switch the fetch type to eager for relationships you always need. A third option is a JPQL JOIN FETCH or @EntityGraph on the repository method itself, which tells Hibernate to load the association in the initial query rather than deferring it.

Unexpected query count, Hibernate's lazy-loading strategy

If your application issues far more SQL statements than you expect, the N+1 problem is the likely culprit. Hibernate's default for @OneToMany is FetchType.LAZY, so fetching ten authors and iterating their posts triggers one query for the author list and ten more for the post collections. [6] You won't see this in your repository interface; you have to look at what Hibernate is generating. Enable SQL logging with these two lines in application.properties:

spring.jpa.show-sql=true
logging.level.org.hibernate.SQL=DEBUG

Once you can see the queries, the fix is at the Hibernate or JPA layer, not the Spring Data layer. A JOIN FETCH in a @Query annotation collapses the N+1 into a single join. [6] @EntityGraph on the repository method achieves the same result declaratively. [6] For cases where you prefer to keep lazy loading but still want fewer round trips, setting spring.jpa.properties.hibernate.default_batch_fetch_size=10 tells Hibernate to load related collections in batches with an IN clause rather than one query per row. [6]

Transaction rollback surprises, Spring's @Transactional infrastructure

When a transaction does not behave the way you expect, changes not persisting, rollbacks firing on the wrong exception, or operations on a second data source not participating in the transaction, the problem lives at the Spring layer. @Transactional is managed entirely by Spring's AOP proxy, and its default behaviour is to roll back only on unchecked exceptions. If your application has multiple data sources, Spring applies @Transactional to the primary one by default; the secondary data source participates only if you configure a JtaTransactionManager or explicitly name the transaction manager in the annotation. [7] The fix is a Spring configuration change, not a Hibernate tuning exercise.

The mental model from earlier sections makes all three of these straightforward to triage: session lifecycle is Hibernate, query shape is Hibernate, transaction boundaries are Spring. When you see a stack trace or unexpected behaviour, ask which layer owns that concept, then inspect or configure exactly that layer. Turning on SQL logging in development is a good habit regardless; the raw queries Hibernate sends are the single most informative signal available, and most performance surprises reveal themselves within a few minutes of reading them.