Spring Security: Complete Architecture Guide

Let me break down Spring Security's architecture from a bird's eye view to the implementation details in your codebase.

---

🌍 Bird's Eye View: Spring Security Architecture

HTTP Request
    ↓
Filter Chain (Servlet Filters)
    ├─ CORS Filter
    ├─ JWT Authentication Filter ← Your custom filter
    ├─ UsernamePasswordAuthenticationFilter
    ├─ Exception Translation Filter
    └─ Authorization Filter
    ↓
SecurityContext (Thread-Local Storage)
    └─ Authentication Object
        ├─ Principal (UserDetails)
        ├─ Credentials (password)
        └─ Authorities (roles/permissions)
    ↓
Your Controller
    └─ Access SecurityContextHolder to get current user

---

🔑 Core Concepts & Relationships

1. UserDetails Interface

Location: org.springframework.security.core.userdetails.UserDetails

public interface UserDetails {
    String getUsername();                        // Unique identifier
    String getPassword();                        // Credentials
    Collection<? extends GrantedAuthority> getAuthorities(); // Roles/permissions
    boolean isAccountNonExpired();
    boolean isAccountNonLocked();
    boolean isCredentialsNonExpired();
    boolean isEnabled();
}

Purpose: Represents the user information that Spring Security needs for authentication and authorization.

In Your Code (User.java:15):

@Entity
public class User implements UserDetails {
    private Long id;
    private String email;
    private String password;
    private Set<Role> roles;

    @Override
    public String getUsername() {
        return email;  // Your email is the username
    }

    @Override
    public Collection<? extends GrantedAuthority> getAuthorities() {
        return roles.stream()
            .map(role -> new SimpleGrantedAuthority("ROLE_" + role.name()))
            .collect(Collectors.toList());
    }
    // ... other UserDetails methods
}

---

2. Authentication Interface

Location: org.springframework.security.core.Authentication

public interface Authentication extends Principal {
    Collection<? extends GrantedAuthority> getAuthorities(); // User roles
    Object getCredentials();                                  // Password (usually null after auth)
    Object getDetails();                                      // Additional details (IP, session, etc.)
    Object getPrincipal();                                    // The user (UserDetails object)
    boolean isAuthenticated();
    void setAuthenticated(boolean isAuthenticated);
}

Purpose: Represents an authentication request or an authenticated user.

Common Implementation: UsernamePasswordAuthenticationToken

In Your Code (JwtAuthenticationFilter.java:64-66):

UsernamePasswordAuthenticationToken authToken =
    new UsernamePasswordAuthenticationToken(
        userDetails,              // ← Principal (your User object)
        null,                     // ← Credentials (null after authentication)
        userDetails.getAuthorities() // ← Authorities (roles)
    );

---

3. Principal Interface

Location: java.security.Principal

public interface Principal {
    String getName();  // Returns the name of the principal
}

Purpose: Generic Java interface representing an identity. In Spring Security, the principal is typically the UserDetails object.

Relationship:

Authentication
    └─ getPrincipal() → Object (usually UserDetails)
        └─ In your case: User object (which implements UserDetails)

Extracting Principal:

// From Authentication object
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
Object principal = auth.getPrincipal();

// principal can be:
// 1. UserDetails (your User object) - when authenticated
// 2. String (username) - when not fully authenticated
// 3. AnonymousAuthenticationToken - for anonymous users

---

🔄 Complete Authentication Flow

Flow Diagram:

1. Client Request
   └─ Headers: { Authorization: "Bearer eyJhbGc..." }
        ↓
2. Servlet Container
   └─ Creates HttpServletRequest
        ↓
3. Filter Chain Starts
   ├─ CORS Filter (handles cross-origin)
   ├─ YOUR JWT Filter ← We are here!
   │   │
   │   ├─ Extract JWT from header
   │   ├─ Validate token
   │   ├─ Extract username from token
   │   ├─ Load UserDetails from database
   │   └─ Create Authentication object
   │       └─ Store in SecurityContext
   │
   ├─ Other Security Filters
   └─ Authorization Filter (checks permissions)
        ↓
4. SecurityContext (Thread-Local)
   └─ Contains Authentication object
        └─ principal: User object
        └─ authorities: [ROLE_USER, ROLE_ADMIN]
        ↓
5. Your Controller
   └─ Can access current user via SecurityContextHolder
        ↓
6. Response

---

🧵 Thread-Local Security Context

What is ThreadLocal?

Spring Security uses ThreadLocal to store the authentication for each HTTP request thread.

// Simplified version of SecurityContextHolder
public class SecurityContextHolder {
    private static ThreadLocal<SecurityContext> contextHolder = new ThreadLocal<>();

    public static SecurityContext getContext() {
        return contextHolder.get();  // Gets context for CURRENT thread only
    }

    public static void setContext(SecurityContext context) {
        contextHolder.set(context);  // Sets for CURRENT thread only
    }
}

Why ThreadLocal?

• Each HTTP request runs in its own thread
• ThreadLocal ensures each thread has its own isolated SecurityContext
• Request A's authentication cannot interfere with Request B's authentication

---

📝 Step-by-Step: Your JWT Authentication Flow

Let's trace a real request through your system:

Request: GET /api/cart with Authorization: Bearer <jwt_token>

Step 1: JwtAuthenticationFilter Intercepts

File: JwtAuthenticationFilter.java:34-77

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

    // 1. Extract JWT token from header
    final String requestTokenHeader = request.getHeader("Authorization");
    String jwtToken = null;
    String username = null;

    if (requestTokenHeader != null && requestTokenHeader.startsWith("Bearer ")) {
        jwtToken = requestTokenHeader.substring(7);  // Remove "Bearer "
        username = jwtUtil.getUsernameFromToken(jwtToken);  // Extract email from JWT
    }

    // 2. Check if already authenticated
    if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {

        // 3. Load user from database
        UserDetails userDetails = userService.loadUserByUsername(username);
        //     ↑ This returns your User object (which implements UserDetails)

        // 4. Validate token
        if (jwtUtil.validateToken(jwtToken, userDetails)) {

            // 5. Create Authentication object
            UsernamePasswordAuthenticationToken authToken =
                new UsernamePasswordAuthenticationToken(
                    userDetails,                    // ← Principal (your User)
                    null,                          // ← Credentials (null for JWT)
                    userDetails.getAuthorities()   // ← Roles [ROLE_USER]
                );

            // 6. Add request details (IP, session ID, etc.)
            authToken.setDetails(
                new WebAuthenticationDetailsSource().buildDetails(request)
            );

            // 7. Store in SecurityContext (ThreadLocal)
            SecurityContextHolder.getContext().setAuthentication(authToken);
            //                                                      ↑
            //                                                      This is now available
            //                                                      in your controller!
        }
    }

    // 8. Continue filter chain
    filterChain.doFilter(request, response);
}

Step 2: Authorization Filter Checks Permissions

File: SecurityConfig.java:77

.requestMatchers(AntPathRequestMatcher.antMatcher("/api/cart/**"))
    .hasAnyRole("USER", "ADMIN")  // ← Checks authorities in Authentication

Spring Security automatically:

1. Gets Authentication from SecurityContext
2. Calls authentication.getAuthorities()
3. Checks if authorities contain ROLE_USER or ROLE_ADMIN
4. Allows/denies access

Step 3: Your Controller Accesses Current User

@GetMapping("/cart")
public ResponseEntity<CartDto> getCart(Authentication authentication) {
    //                                   ↑ Spring automatically injects this!

    // Extract principal
    Object principal = authentication.getPrincipal();

    if (principal instanceof User user) {
        Long userId = user.getId();  // Direct access to your User entity
        // ... fetch cart ...
    }
}

---

🏗️ Class Hierarchy & Interface Relationships

java.security.Principal (interface)
    ↑
org.springframework.security.core.Authentication (interface)
    ↑
AbstractAuthenticationToken (abstract class)
    ↑
UsernamePasswordAuthenticationToken (class)  ← You use this
    └─ principal: Object (your User object)
    └─ credentials: Object (password or null)
    └─ authorities: Collection<GrantedAuthority>


org.springframework.security.core.userdetails.UserDetails (interface)
    ↑
com.automotive.ecommerce.business.entity.User (your class)  ← Your implementation
    └─ implements all UserDetails methods
    └─ adds custom fields (id, email, firstName, etc.)

---

🎯 How UserDetails is Extracted from Authentication

Method 1: Direct Cast (Type-Safe)

Authentication auth = SecurityContextHolder.getContext().getAuthentication();
Object principal = auth.getPrincipal();

if (principal instanceof User user) {
    // ✅ Type-safe access to your User entity
    Long userId = user.getId();
    String email = user.getEmail();
}

Method 2: Generic UserDetails Cast

if (principal instanceof UserDetails userDetails) {
    // ✅ Access to UserDetails methods only
    String username = userDetails.getUsername();
    Collection<? extends GrantedAuthority> authorities = userDetails.getAuthorities();

    // ❌ Cannot access User-specific fields like getId()
    // Long userId = userDetails.getId();  // Compile error!
}

Method 3: Spring's @AuthenticationPrincipal

@GetMapping("/cart")
public ResponseEntity<CartDto> getCart(@AuthenticationPrincipal User user) {
    //                                    ↑ Spring automatically extracts and casts
    Long userId = user.getId();  // Direct access!
}

---

🔐 SecurityContext & SecurityContextHolder

Structure:

SecurityContextHolder (Thread-Local Storage)
    └─ SecurityContext
        └─ Authentication
            ├─ principal: UserDetails (your User)
            ├─ credentials: null
            ├─ authorities: [ROLE_USER, ROLE_ADMIN]
            ├─ details: WebAuthenticationDetails (IP, session)
            └─ authenticated: true

Accessing Current User Anywhere:

// In any service, controller, or component
Authentication auth = SecurityContextHolder.getContext().getAuthentication();

if (auth != null && auth.getPrincipal() instanceof User user) {
    System.out.println("Current user: " + user.getEmail());
    System.out.println("User ID: " + user.getId());
}

---

📊 Summary: The Big Picture

Concept	Purpose	Example in Your Code
UserDetails	Contract for user information Spring Security needs	Your User entity implements this
Authentication	Represents an authenticated user with credentials & authorities	UsernamePasswordAuthenticationToken
Principal	The identity (usually UserDetails)	Your User object stored in Authentication
SecurityContext	Container for Authentication	Thread-local storage per request
SecurityContextHolder	Static accessor for SecurityContext	Access current user anywhere
Filter Chain	Intercepts requests to authenticate	Your JwtAuthenticationFilter
AuthenticationManager	Validates credentials	Used in login (AuthController)
UserDetailsService	Loads user from database	Your UserService.loadUserByUsername()

---

🚀 Key Takeaways

1. UserDetails = Your User entity with Spring Security requirements
2. Authentication = Container holding the authenticated user (principal) + authorities
3. Principal = The "who" (your User object) inside Authentication
4. SecurityContext = Thread-local storage for Authentication (one per request thread)
5. Filter Chain = Where authentication happens before reaching your controller
6. JWT Flow = Extract token → Load user → Create Authentication → Store in SecurityContext

---

Next Steps: Now that you understand Spring Security's architecture, explore how it integrates with your backend scenarios in the Backend Scenarios guide.