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:
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:
JdbcAuthConfigwithDaoAuthenticationProviderandJdbcUserDetailsManager - LDAP:
LdapAuthConfigwith embedded LDAP server - OAuth2:
OAuth2AuthConfigfor social login (GitHub, Google, etc.)
Protocol Security¶
- REST: Configured via
MultiAuthSecurityConfigfilter chain - WebSocket:
WebSocketSecurityInterceptorinChannelInterceptor.preSend() - gRPC:
GrpcSecurityInterceptorasServerInterceptor - GraphQL:
GraphQLSecurityInterceptor(scaffold)
🛡️ Security Patterns¶
- All authentication flows converge through
MultiAuthSecurityConfigfilter chain - Role-based access via
AuthorizationService.getUserRole()andhasPermission() - JWT tokens include
username(subject) androleclaims SecurityContextHolderused for downstream authorization- JWT filter runs before
UsernamePasswordAuthenticationFilterin 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.