Skip to content

Project Structure

This page explains the modular architecture and folder structure of the Spring Security Reference project.

🏗️ Overview

The project uses a layered modular architecture for clear separation of concerns:

rest-api → common-auth + common-security + authorization-service + jdbc-auth + ldap-auth + oauth2-auth
common-security → common-auth
authorization-service → standalone
common-auth → standalone
jdbc-auth → standalone
ldap-auth → standalone
oauth2-auth → standalone

📁 Folder Layout

apps/
    rest-api/
    gateway/
    saml-auth/
    graphql-service/
    grpc-service/
    websocket-service/
libs/
    common-auth/
    common-security/
    authorization-service/
    jdbc-auth/
    ldap-auth/
    oauth2-auth/
docs/
infrastructure/
build.gradle
settings.gradle
gradlew
README.md

apps/ groups application and protocol modules; libs/ groups shared authentication and authorization modules. The OAuth2 module also contains a standalone demo entry point. This grouping does not merge application contexts or change module dependencies.

Each module retains its own build.gradle, src/main/java, src/main/resources, and test sources where present. For example, the REST entry point is at apps/rest-api/src/main/java/com/example/spring/security/reference/api/RestApiApplication.java.

settings.gradle maps the existing Gradle project names to their new directories. Run commands from the repository root as before:

./gradlew :rest-api:bootRun
./gradlew :rest-api:test
./gradlew test

Reload the Gradle project in your IDE after moving to this layout.

🧩 Module Responsibilities

Module Purpose
rest-api Main application entry point, REST endpoints, integrates all authentication modules
common-auth Core authentication logic (session-based, JWT, 2FA hooks)
common-security Security configuration, filter chains, protocol interceptors
authorization-service Role and permission management
jdbc-auth Database-backed user authentication with H2 and BCrypt
ldap-auth LDAP/Active Directory authentication
oauth2-auth OAuth2/OpenID Connect social login integration
graphql-service GraphQL API with security integration (scaffold)
websocket-service WebSocket messaging with security

🔗 Authentication Methods & API Types

Authentication Providers

  • Session-based: CustomAuthenticationProvider + AuthService.authenticateSession()
  • JWT-based: JwtAuthenticationFilter + JwtTokenUtil
  • JDBC: JdbcAuthConfig with DaoAuthenticationProvider and JdbcUserDetailsManager
  • LDAP: LdapAuthConfig with embedded LDAP server
  • OAuth2: OAuth2AuthConfig for social login (GitHub, Google, etc.)

Protocol Security

  • REST: Configured via MultiAuthSecurityConfig filter chain
  • WebSocket: WebSocketSecurityInterceptor in ChannelInterceptor.preSend()
  • gRPC: GrpcSecurityInterceptor as ServerInterceptor
  • GraphQL: GraphQLSecurityInterceptor (scaffold)

🛡️ Security Patterns

  • All authentication flows converge through MultiAuthSecurityConfig filter chain
  • Role-based access via AuthorizationService.getUserRole() and hasPermission()
  • JWT tokens include username (subject) and role claims
  • SecurityContextHolder used for downstream authorization
  • JWT filter runs before UsernamePasswordAuthenticationFilter in the chain

📦 Package Naming Convention

All modules follow the base package: com.example.spring.security.reference

Module Package
rest-api ...reference.api
common-auth ...reference.commonauth
common-security ...reference.commonsecurity
authorization-service ...reference.authorizationservice
jdbc-auth ...reference.jdbcauth
ldap-auth ...reference.ldapauth
oauth2-auth ...reference.oauth2auth
graphql-service ...reference.graphqlservice
websocket-service ...reference.websocketservice

🚀 Next Steps


This modular structure demonstrates best practices for scalable, secure Spring applications and is designed for easy extension to WebSocket, gRPC, and GraphQL APIs as you continue learning.