What

  • CORS blocks non-whitelisted origins in AppSecurityConfig.
  • JWT is validated for protected endpoints in JwtAuthenticationFilter using AuthenticationManagerJWT.
  • API tiers restrict access even with a valid token; higher tiers grant access to more endpoints.

Flow (request lifecycle):

  1. Incoming request → CORS applied → non-whitelisted origins blocked.
  2. Public/No-Auth endpoints bypass JWT checks.
  3. Protected endpoints → JWT extracted and validated.
  4. Tier authorization matched against requested API tier.
  5. On success, controller executes; on failure, error is routed to global handler.

Why

  • Prevent misuse from unwanted domains via strict CORS.
  • Reject bad tokens: expired, blocked, reused/refresh-misuse.
  • Enforce progression: open → tier 4 → tier 3 → tier 2 → tier 1 as business rules demand.

How

  • CORS configuration (AppSecurityConfig.corsConfigurationSource()):
@Bean
fun corsConfigurationSource(): CorsConfigurationSource {
    val configuration = CorsConfiguration()
    configuration.allowedOrigins = listOf(
        "http://localhost:3000",
        "https://yourdomain.com"
    )
    configuration.allowedMethods = listOf("GET","POST","PUT","DELETE","OPTIONS","PATCH")
    configuration.allowedHeaders = listOf(
        "Authorization","Content-Type","X-Requested-With","Accept","Origin",
        KeywordsAndConstants.HEADER_TRACKING_ID,
        KeywordsAndConstants.HEADER_API_KEY,
        KeywordsAndConstants.HEADER_OTP,
        KeywordsAndConstants.HEADER_AUTH_TOKEN
    )
    configuration.allowCredentials = true
    configuration.exposedHeaders = listOf(
        KeywordsAndConstants.HEADER_TRACKING_ID,
        KeywordsAndConstants.HEADER_API_TIER
    )
    val source = UrlBasedCorsConfigurationSource()
    source.registerCorsConfiguration("/**", configuration)
    return source
}

Explanation:

  • allowedOrigins strictly whitelists domains that can call the APIs; everything else is blocked at the edge.

  • allowedHeaders/exposedHeaders explicitly permit and reveal only what clients need (tracking ID, API tier), reducing leakage.

  • allowCredentials = true enables cookies/authorization headers only for whitelisted origins.

  • JWT filter flow (JwtAuthenticationFilter):

override fun doFilterInternal(req: HttpServletRequest, res: HttpServletResponse, chain: FilterChain) {
    try {
        // Allow public and no-auth endpoints
        val path = req.requestURI
        if (isPublicEndpoint(path) || isNoAuthAPI(path)) {
            chain.doFilter(req, res); return
        }

        // Require token for protected endpoints
        val token = jwtUtilMaster.getJwtAuth(req, mustReturnTokenOrElseCrash = true)
        if (token != null) {
            val auth = JwtAuthenticationToken(
                KeywordsAndConstants.TOKEN_PREFIX + token,
                req.method,
                path,
                req.getHeader(KeywordsAndConstants.HEADER_TRACKING_ID) ?: ""
            )
            val authentication = authenticationManager.authenticate(auth)
            SecurityContextHolder.getContext().authentication = authentication
            chain.doFilter(req, res)
        } else {
            handlerExceptionResolver.resolveException(req, res, null, Exception("JWT token is required for this endpoint"))
        }
    } catch (e: Exception) {
        handlerExceptionResolver.resolveException(req, res, null, e)
    }
}

Explanation:

  • Public endpoints: swagger/docs/favicon; No-Auth endpoints: business endpoints whitelisted via NO_AUTH_APIS.

  • Missing/invalid token: routed to global handler via handlerExceptionResolver (no raw container error pages).

  • Successful authentication: SecurityContextHolder gets the authenticated token and the request proceeds to the controller.

  • Tier enforcement (AuthenticationManagerJWT):

private fun checkJwtAuthorizations(subject: String, token: JwtAuthenticationToken) {
    val apiTier = determineApiTier(token.path)
    when (subject) {
        KeywordsAndConstants.TOKEN_TIRE_FOUR -> if (apiTier in listOf(ApiTier.TIRE_THREE, ApiTier.TIRE_TWO, ApiTier.TIRE_ONE))
            throw ForbiddenExceptionThrowable(
                errorMessage = KeywordsAndConstants.SOFT_TOKEN_TIRE_FOUR_ERROR_GENERIC,
                code = KeywordsAndConstants.SOFT_TOKEN_TIRE_FOUR_ERROR_GENERIC_CODE
            )
        KeywordsAndConstants.TOKEN_TIRE_THREE -> if (apiTier in listOf(ApiTier.TIRE_TWO, ApiTier.TIRE_ONE))
            throw ForbiddenExceptionThrowable(
                errorMessage = KeywordsAndConstants.SOFT_TOKEN_TIRE_THREE_ERROR,
                code = KeywordsAndConstants.SOFT_TOKEN_TIRE_THREE_ERROR_CODE
            )
        KeywordsAndConstants.TOKEN_TIRE_TWO -> if (apiTier == ApiTier.TIRE_ONE)
            throw ForbiddenExceptionThrowable(
                errorMessage = KeywordsAndConstants.SOFT_TOKEN_TIRE_TWO_ERROR,
                code = KeywordsAndConstants.SOFT_TOKEN_TIRE_TWO_ERROR_CODE
            )
        KeywordsAndConstants.TOKEN_TIRE_ONE -> { /* full access */ }
    }
}

Explanation:

  • determineApiTier(path) maps the requested URL to an ApiTier using constants (APIS_TIER_*, NO_AUTH_APIS).

  • The token’s sub (subject) determines its tier (TOKEN_TIRE_ONE is highest). Lower-tier tokens are blocked from higher-tier APIs with specific, consistent error codes.

  • Open vs protected:

    • Open: swagger, docs, favicon via isPublicEndpoint().
    • No-auth business APIs: from KeywordsAndConstants.NO_AUTH_APIS via isNoAuthAPI().
    • Everything else requires a valid token and passes tier checks.

  • Extra hardening:

    • Generate and propagate a tracking ID when missing; expose it to clients for tracing.
    • Add client IP and an internal access-log ID to the request (not exposed to clients) using HeaderEnhancedHttpServletRequest.
    • Validate “refresh vs access” token usage; block reused/blocked/expired tokens; route all failures via the resolver to the global handler.

The filter uses handlerExceptionResolver.resolveException(...) to forward errors into the global handler. The mechanics of that pattern are covered in Error Handling in Spring Boot: Controllers vs Filters.