Auth Server (Spring Authorization Server)

Authentication and authorization server built on Spring Authorization Server, acting as a central Identity and Access Management (IAM) service for multi-tenant applications.

It focuses on:

• Standards-based OAuth2/OIDC authentication
• A multi-tenant user, role, and permission model
• Email verification and core account management flows
• Operational concerns like rate limiting, session management, and key management

---

1. Features (Overview)

Authentication & Authorization

• OAuth2 / OIDC Authorization Server using Spring Authorization Server
• Authorization Code, Refresh Token, and JWT Bearer grants for first-party clients
• JDBC-backed client registration via JdbcRegisteredClientRepository
• Resource server configuration for /api/** endpoints secured via JWT
• Form-based login for browser-based users with a custom login page (/login)
• Logout endpoint (/op-logout) that invalidates the session, clears the security context, and removes session cookies

User & Account Management

• User model backed by Spring Data JDBC
• UserService implementing UserDetailsService for Spring Security integration
• Account lifecycle operations:
  • Load user by email
  • Change password with current password verification
  • Initial password change on first login via InitialPasswordChangeFilter
  • Update profile with password verification
• Email verification:
  • Token generation and persistence
  • HMAC-signed verification URLs
  • Endpoint that validates and consumes tokens and marks user emails as verified
• Email change (WIP):
  • Request model and service method to initiate a new email verification
  • Planned confirmation step to complete the email change

Multi-Tenancy

• Tenant and branch model under dev.akbas.auth.tenant.*
• TenantService for managing tenants, branches, and user-branch relationships
• UserService enriches authenticated users with tenant/branch memberships

Role & Permission Management (RBAC)

• Role and permission entities and repositories under dev.akbas.auth.user.db.*
• RoleManagementService to aggregate user roles and permissions via join tables
• UserService packages roles and permissions into AuthUserDetails
• Custom JWT authorities mapping for downstream services

Security Hardening

• Rate limiting via Bucket4j + Caffeine (global and login-specific)
• CSRF protection enabled for form-based endpoints, disabled for JWT APIs (/api/**)
• Spring Session JDBC for persistent, database-backed sessions
• AES-based encryption for key material (AESEncryptionService)
• HMAC signing for verification links (HmacService, KeyService)
• Centralized error DTOs and exception hierarchy (ApiErrorHandler, AppException, etc.)

Status / WIP

Planned and partially implemented pieces include:

• Full email change flow (confirmation endpoint and UI)
• Tenant and role management APIs and/or UI
• Extended automated tests around email, auth flows, and rate limiting
• Containerization and deployment examples
• Optional MFA (TOTP / WebAuthn) and device/session management

---

2. Architecture & Tech Stack

High-Level Architecture

• Spring Boot application exposing:
  • Authorization Server endpoints (OAuth2/OIDC)
  • Form-based login & logout for browser usage
  • Resource server endpoints under /api/** secured via JWT bearer tokens
• Persistence with MySQL (or compatible) and Spring Data JDBC
• Spring Session JDBC for HTTP session persistence
• Custom servlet filters for initial password change and rate limiting

Tech Stack

• Language / Runtime: Java 25 (Gradle toolchain)
• Frameworks:
  • Spring Boot
  • Spring Security & Spring Authorization Server
  • Spring Data JDBC
  • Spring Session JDBC
  • Spring Mail
  • Spring MVC + Thymeleaf, thymeleaf-extras-springsecurity6
• Libraries:
  • Bucket4j (rate limiting) and Caffeine (caching)
  • Jackson + Kotlin module
  • MySQL JDBC driver
• Build & Test:
  • Gradle with Spring dependency management
  • JUnit Platform with Spring Boot test starters

---

3. Security Model (Key Points)

• Authorization Server configuration via SecurityConfig.authorizationServerSecurityFilterChain and OAuth2AuthorizationServerConfigurer
• Issuer configured from app.baseUrl (APP_BASE_URL), clients stored via JdbcRegisteredClientRepository
• Resource server for /api/** with JWT and a custom JwtAuthenticationConverter
• Session and cookies managed via Spring Session JDBC and application.yml cookie settings
• CSRF enabled for form-login endpoints; disabled for JWT-protected APIs
• Passwords stored via a delegating PasswordEncoder (e.g. BCrypt)
• AES encryption for key data (AESEncryptionService with app.aes.key)
• HMAC signing for verification URLs (HmacService, KeyPurpose, KeyService)
• Rate limiting implemented with Bucket4j + Caffeine, configurable via app.rateLimit

---

4. Project Structure (Summary)

• dev.akbas.auth
  • AuthApplication – Spring Boot entrypoint, configuration scanning, JDBC session enablement
• dev.akbas.auth.config
  • SecurityConfig – security filter chains, authorization server, resource server, JSON mapper, password encoder, client registration
  • AppProperties – typed configuration (base URL, AES key, rate limiting)
• dev.akbas.auth.email
  • Email verification entities, models, repositories, EmailService
• dev.akbas.auth.error
  • Error DTOs and exception hierarchy (ApiErrorHandler, AppException, etc.)
• dev.akbas.auth.key
  • Key models, repositories, and services (AESEncryptionService, HmacService, KeyService, Key, KeyPurpose, SymmetricKeyHolder)
• dev.akbas.auth.security
  • AuthLogoutHandler, InitialPasswordChangeFilter, PrincipalHolder
  • ratelimit – rate limiter abstractions and servlet filters
• dev.akbas.auth.session
  • SessionConfig – Spring Session integration and SessionRegistry
• dev.akbas.auth.tenant
  • Tenant, branch, and user-branch models, entities, repositories, TenantService
• dev.akbas.auth.user
  • User, roles, permissions, and account management (UserService, RoleManagementService, AuthUserDetails, User, Role, Permission)
• dev.akbas.auth.util
  • Utilities: AuthenticationTokenMixin, AuthInfo, UUIDs, JSON helpers
• src/main/resources
  • application.yml – core configuration (ports, datasource, mail, app settings)
  • schema.sql – database schema initialization
  • Thymeleaf templates for login and related pages

---

5. Configuration Basics

Key configuration is in src/main/resources/application.yml. Notable entries:

• Server port and session cookie settings
• Mail server configuration (spring.mail.*)
• Data source (SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME, SPRING_DATASOURCE_PASSWORD)
• Schema initialization from classpath:schema.sql
• Logging levels for Spring Security
• app.baseUrl, app.rateLimit.enabled, and app.aes.key