Security Architecture

Authentication answers "who are you?": it verifies the caller's identity, for example by checking a password, validating a JWT issued by an identity provider or verifying a client certificate. Authorisation answers "what may you do?": it decides whether that authenticated identity is allowed to perform a specific action on a specific resource, such as approving a refund over a certain amount. Authentication normally happens once per request or session at the boundary; authorisation can happen many times, at URL level and on individual methods. A system can authenticate perfectly and still be insecure if its authorisation rules are missing or wrong.

Spring Security's Authentication object represents a caller. It contains the principal, the identity, such as a UserDetails object, a Jwt or an OidcUser; the credentials, such as a password, which are usually erased after successful login so they do not linger in memory; the granted authorities, which are the roles and permissions used for authorisation decisions; optional details, such as the remote address and session ID; and a flag indicating whether it has been authenticated. After login it is stored in the SecurityContext, which is available to the rest of the request through SecurityContextHolder or method parameters.

The principal is the authenticated identity of the caller, the thing that was proven during authentication. Its type depends on how the user logged in: a UserDetails object for username and password login, a Jwt for a resource server receiving bearer tokens, an OidcUser for OpenID Connect login, or a custom type. Code can access it through Authentication.getPrincipal(), or more conveniently with @AuthenticationPrincipal in a controller method. The principal typically provides the user's identifier and attributes such as name or email, which are used for authorisation decisions, auditing and personalising responses.

Adding spring-boot-starter-security secures the application immediately. Boot configures a default security filter chain that requires authentication for every request, enables form login and HTTP Basic, and, if no other user source is configured, creates a single user named user with a random password printed in the log. It enables CSRF protection for state-changing requests, adds security headers such as X-Content-Type-Options and cache-control headers, and configures session management. These defaults are deliberately strict, so nothing is accidentally exposed, but almost every real application replaces them with its own SecurityFilterChain bean.

A 401 Unauthorized response means the request lacks valid authentication: there are no credentials, the token has expired or the signature is invalid. Despite its name, it is about authentication, and it should include a WWW-Authenticate header telling the client how to authenticate. A 403 Forbidden response means the caller is authenticated, but is not allowed to perform this action, for example a customer trying to access an admin endpoint. In Spring Security, the AuthenticationEntryPoint produces the 401 and the AccessDeniedHandler produces the 403. Using them correctly helps clients decide whether to log in again or give up.

AuthorizationManager is Spring Security's single abstraction for access decisions, introduced to replace the older AccessDecisionManager and voters. Given a supplier of the current Authentication and the object being secured, such as an HTTP request, a method invocation or a message, it returns an authorisation decision. The same model is used for URL rules configured with authorizeHttpRequests, for method security annotations such as @PreAuthorize, and for messaging security. Teams can write custom implementations, for example to check ownership of a resource or call an external policy engine, and reuse them consistently across all three levels.

Spring Security's filters run in the servlet filter chain before any controller code, for every request that reaches the application. Enforcing security there means it is applied centrally and consistently: developers cannot forget to add a check to a new endpoint, and requests that fail authentication are rejected before they touch application code. URL-based rules in the filter chain give a secure default, such as denying anything not explicitly allowed. Method-level annotations on services then add fine-grained authorisation. Checks scattered inside controller methods are easy to miss, hard to audit and do not protect non-HTTP entry points.

Split responsibilities by what each layer knows. Centralise authentication in an identity provider, using single sign-on with OpenID Connect for users and OAuth 2.0 client credentials or workload identity for services, so applications never handle passwords. Keep authorisation rules close to the domain services that own the data, because only they understand concepts such as account ownership or approval limits. Standardise security configuration through platform starters that set up token validation, headers and error responses consistently. Enforce coarse rules at the API gateway, audit authentication and authorisation decisions centrally, and review security architecture as part of every design review.