Security

Overview (C4 Component)

Black-box description of components

Component	Responsibility	Provided Interface(s)	Consumed Interface(s)
AuthenticationController	Public REST endpoints /v1/auth/login, /refresh, /logout.	OpenAPI REST	—
AuthenticationService	Verifies password, issues access & refresh JWT, persists token rows, revokes old tokens.	Spring service API	UserRepository, TokenRepository, JwtTokenProvider
JwtTokenProvider	Stateless creation & validation of HS-256 JWT; handles custom “typ = refresh” claim.	Java util class	TokenRepository (black-list lookup)
JwtAuthenticationFilter	Runs before every request, extracts Bearer, calls JwtTokenProvider, builds Spring Authentication.	Servlet Filter	JwtTokenProvider, UserDetailsService
CustomLogoutHandler	/v1/auth/logout – marks both access & refresh tokens as logged-out in DB.	Spring LogoutHandler	JwtTokenProvider, TokenRepository, UserRepository
AuthorizationHelper	High-level helper used from service layer, e.g. isEsStaff(), isProvider(), isQuoteAuthor(nr)	Java helper	CurrentUserService, QuoteRepository
CurrentUserService	Single source of truth for current User / AuthInfo.	Java service	UserRepository, SecurityContext
RestSecurityConfig	Configures Spring Security: stateless, CORS, JWT filter, exception handlers.	Spring SecurityFilterChain bean	JwtAuthenticationFilter, CustomLogoutHandler
RestAuthenticationEntryPoint	Returns JSON 401, clears context.	Spring AuthenticationEntryPoint	—
RestAccessDeniedHandler	Returns JSON 403 on authorization failures.	Spring handler	—
UserRepository / RoleRepository / PrivilegeRepository / TokenRepository	Standard Spring-Data JPA persistence.	Spring-Data repository interfaces	MySQL via Hibernate
Entities (User, Role, Privilege, Token)	Domain data model for authentication & authorization.	JPA entities	—

Important internal interfaces

Name	Signature / Protocol	Notes
login	POST /v1/auth/login – body LoginRequest → 200 OK LoginResponse	Returns access-token & refresh-token
refreshToken	POST /v1/auth/refresh – body { refreshToken } → 200 OK AuthToken	Requires valid & not-blacklisted refresh token.
logout	POST /v1/auth/logout – header Authorization: Bearer <access> & X-Refresh-Token	CustomLogoutHandler black-lists all active tokens of the user, returns 204 No Content.
JWT Bearer	Authorization: Bearer <accessToken>	Every secured endpoint → JwtAuthenticationFilter → SecurityContext.
403 handler	Any Spring AccessDeniedException → JSON body {status:403, error:"Forbidden", ...}	Implemented by RestAccessDeniedHandler.
401 handler	Invalid / expired JWT → JSON body {status:401, error:"Unauthorized", ...}	Implemented by RestAuthenticationEntryPoint.