Skip to content

Authentication Methods

This section classifies the project's authentication documentation by the five API authentication mechanisms: Basic Auth, Token Auth, JWT, OAuth, and Session Auth. Each entry states how the credential travels, the Spring Security API involved, the implementing code, and an honest status from the Coverage Registry. Check the registry before treating any documentation as runnable proof.

The five API authentication mechanisms and their status in this repository

Editable source: docs/diagrams/api-authentication-mechanisms.drawio

๐ŸŽฏ Classification Overview

Mechanism Credential on the wire Spring Security API Implementing code Status
Basic Auth Authorization: Basic base64(user:pass) httpBasic(...) Not wired to a filter chain yet Theory
Token Auth Authorization: Bearer <opaque> or X-API-Key oauth2ResourceServer().opaqueToken(), custom filter OpaqueTokenResourceServerConfig, ApiKeyAuthenticationFilter, SecureApiKeyService Verified
JWT Authorization: Bearer <signed-jwt> oauth2ResourceServer().jwt() ResourceServerSecurityConfig, JwtAuthenticationFilter (educational) Verified
OAuth Browser redirect + token endpoint exchange oauth2Login(), oauth2Client(), resource server OAuth2AuthConfig, ClientCredentialsConfig, TokenExchangeConfig, BffTokenConfig Mixed (see registry)
Session Auth Cookie: JSESSIONID=<id> formLogin(), sessionManagement(...) BrowserSecurityConfig, jdbc-only / ldap-only profile chains Verified

Identity stores such as JDBC and LDAP are not mechanisms in this taxonomy โ€” they are credential stores that sit behind Basic or Session Auth. See Credential Stores vs. Mechanisms.

This page is an advance organizer for the Learning Model: study each mechanism's theory page, prove it in its lab, then test discrimination between mechanisms in the senior quizzes. Status labels follow the registry's Planned โ†’ Theory โ†’ Implemented โ†’ Verified โ†’ Operational gates so you can calibrate confidence before relying on a mechanism.

๐Ÿ”‘ Basic Auth

The client sends username:password Base64-encoded on every request. Base64 is encoding, not encryption โ€” Basic Auth is only acceptable over TLS.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
  • Spring API: http.httpBasic(Customizer.withDefaults()) installs BasicAuthenticationFilter, which decodes the header and delegates to the configured AuthenticationManager.
  • When to use: simple machine-to-machine calls inside a trusted network, quick diagnostics, and teaching UserDetailsService/AuthenticationProvider mechanics.
  • When to avoid: browsers (no logout, credentials cached), untrusted networks, anything without TLS.
  • Status โ€” Theory. No httpBasic(...) chain is wired in this repository today. The jdbc-only and ldap-only profiles authenticate through form login (Session Auth), not Basic Auth. Documentation elsewhere that shows Basic Auth examples is illustrative.
  • Read more: Authentication Flow shows the filter sequence; Password Storage covers the server-side half of the credential check.

๐ŸŽŸ๏ธ Token Auth

The client presents an opaque token โ€” a random string that carries no claims โ€” and the server resolves it to an identity. Two flavors are implemented:

Opaque bearer tokens (introspection)

Authorization: Bearer 7f3a9c1e-...
  • Spring API: http.oauth2ResourceServer(rs -> rs.opaqueToken(...)) with an OpaqueTokenIntrospector.
  • Evidence: OpaqueTokenResourceServerConfig protects /op/**; introspection, expiry, and failure modes are proven by LAB-013 (OpaqueToken*LabTest). LAB-024 adds a resilient introspector with circuit-breaker behavior for IdP outages.
  • Trade-off: every request costs an introspection call (or cache hit), but revocation is immediate โ€” the opposite of JWT.
  • Theory: Opaque Token Introspection, Token Lifecycle, Resilience and Security Outages.

API keys

X-API-Key: ak_live_...
  • Spring API: a custom OncePerRequestFilter (ApiKeyAuthenticationFilter) before UsernamePasswordAuthenticationFilter; there is no standard http.apiKey() DSL.
  • Evidence: ApiKeyAuthConfig and ApiKeysAndQuotasLabTest prove hashed key lookup and per-key quotas in LAB-022; SecureApiKeyService and ApiKeyLifecycleLabTest prove rotation, audit, and high-sensitivity hashing in LAB-026.
  • Trade-off: no standard expiry or audience semantics โ€” the application must implement hashing, rotation, and scoping itself.
  • Theory: API Keys and Resource Quotas, API Key Lifecycle.

๐Ÿงพ JWT

The client presents a self-contained signed token whose claims the server verifies locally โ€” signature, issuer, audience, expiry โ€” with no per-request lookup.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
  • Spring API (recommended): http.oauth2ResourceServer(rs -> rs.jwt(Customizer.withDefaults())) โ€” never a hand-rolled bearer filter.
  • Evidence: ResourceServerSecurityConfig protects /rs/** and is proven by ResourceServerJwtLabTest in LAB-009 (signature, issuer, audience, expiry, authority checks). LAB-015 adds JWK rotation and multiple issuers; LAB-023 adds tenant-aware JwtDecoder resolution.
  • Educational filter: JwtAuthenticationFilter + JwtTokenUtil in common-auth still guards /api/** as a filter-mechanics example with a process-local symmetric key. It is labeled educational โ€” do not copy it into production.
  • Trade-off: scalable and offline-verifiable, but revocation requires short expiry plus refresh or introspection fallback.
  • Read more: JWT Tokens, JWT Resource Server, JWK Rotation.

๐ŸŒ OAuth

OAuth 2.0 is a delegation framework, not a credential format โ€” it defines how clients obtain tokens (usually JWT or opaque) from an authorization server without handling user passwords.

  • Spring APIs: http.oauth2Login(...) for browser login, oauth2Client(...) for machine clients, oauth2ResourceServer(...) for APIs accepting the issued tokens.
  • Evidence and labs:
  • Local IdP: LAB-010 (infrastructure/idp/* โ€” implemented, requires Docker)
  • Authorization Code + PKCE: LAB-011 (OAuth2AuthConfig, configuration unit-tested)
  • Refresh/revocation: LAB-012 (opt-in, requires Docker)
  • Client Credentials service identity: LAB-014 (ClientCredentialsConfig)
  • OIDC SSO: LAB-018 (CustomOidcUserService, OidcAuthoritiesMapper โ€” verified)
  • Token exchange / delegation: LAB-019 and LAB-025 (verified)
  • BFF token handling: LAB-020 (verified)
  • Status โ€” Mixed. OIDC SSO, token exchange, and BFF handling are Verified; the local IdP, PKCE, and token-lifecycle flows are Implemented but need Docker to execute end to end.
  • Read more: OAuth2 Authentication, Authorization Code with PKCE, Token Exchange, BFF Token Handling.

๐Ÿช Session Auth

The server stores authentication state and the client presents a session cookie. This is the browser-native mechanism and the only stateful one in the taxonomy.

Cookie: JSESSIONID=ABC123...
  • Spring API: http.formLogin(...) issues the session; sessionManagement(...) controls fixation, concurrency, and creation policy (IF_REQUIRED for browsers, STATELESS for APIs).
  • Evidence: BrowserSecurityConfig isolates a stateful chain on /browser/** with IF_REQUIRED sessions, CSRF protection, and hardened headers โ€” proven in LAB-006 (identifier rotation, logout invalidation), LAB-007, and LAB-008. The jdbc-only / ldap-only profile chains in MultiAuthSecurityConfig use the same mechanism.
  • Trade-off: server-side state enables instant logout and revocation, but requires CSRF protection and does not scale horizontally without session replication.
  • Theory: Browser Sessions, CSRF, CORS and Headers.

๐Ÿ—„๏ธ Credential Stores vs. Mechanisms

A common confusion: JDBC and LDAP describe where credentials are checked, not how they travel. They plug into Basic or Session Auth via an AuthenticationProvider/UserDetailsService; they can also feed the login step that issues a JWT or OAuth token.

Store Module Provides Used by Status
JDBC jdbc-auth Database-backed AuthenticationProvider Session Auth (jdbc-only profile) and JWT issuance (default profile login) Implemented โ€” needs dedicated integration tests
LDAP ldap-auth Directory-backed AuthenticationProvider + PersonContextMapper Session Auth (ldap-only profile) and JWT issuance (default profile login) Implemented โ€” embedded directory auto-starts; login live-verified

How the five mechanisms connect to credential stores

Editable source: docs/diagrams/mechanisms-vs-credential-stores.drawio

๐Ÿ” Comparison Matrix

Feature Basic Auth Token Auth JWT OAuth Session Auth
Credential on wire user:pass every request opaque key/token signed claims issued token session cookie
Server state Stateless Lookup per request Stateless Framework + tokens Stateful
Revocation Password change Immediate Expiry-bound Depends on token type Immediate (logout)
TLS required Absolutely Yes Yes Yes Yes (Secure cookie)
CSRF exposure No No No Login flow only Yes โ€” needs protection
Best fit Internal/simple APIs Partner APIs, quotas Scaled APIs Delegated access, SSO Browser apps
Repo status Theory Verified Verified Mixed Verified

๐ŸŽ“ Learning Path

Work the mechanisms in dependency order โ€” each links theory, lab, and quiz:

  1. Request Authorization and Secure Login โ€” the filter chain and provider contract every mechanism relies on.
  2. Session Auth โ€” LAB-006 โ†’ LAB-007 โ†’ LAB-008: stateful browser security done right.
  3. JWT โ€” LAB-009 โ†’ LAB-015: standard resource server, then rotation.
  4. OAuth โ€” LAB-010 โ†’ LAB-011 โ†’ LAB-018 โ†’ LAB-019 โ†’ LAB-020.
  5. Token Auth โ€” LAB-013 โ†’ LAB-022 โ†’ LAB-026.
  6. Basic Auth โ€” Theory only today; revisit once a dedicated chain exists (or treat as a contrast case in the Authentication Flow diagrams).
  7. Assess โ€” after the mechanisms above, complete the Spring Security internals and SSO and federation senior assessments. Aim to explain why a rejected option is unsafe, not just which option is correct.

๐Ÿ”จ Implementation Tips

Choosing the Right Mechanism

  • Public partner APIs: Token Auth (API keys) with hashing, quotas, and rotation โ€” see LAB-022/026.
  • Scaled internal APIs: JWT via the standard resource server โ€” never a custom bearer filter.
  • Third-party delegation or SSO: OAuth/OIDC โ€” see LAB-011 and LAB-018.
  • Browser-rendered apps: Session Auth with CSRF protection and hardened cookies.
  • Basic Auth: only as a teaching contrast or inside a fully trusted, TLS-only boundary.

Best Practices

  1. TLS everywhere โ€” every mechanism above sends a reusable credential; only JWT limits replay damage to its expiry window.
  2. Prefer standard support โ€” oauth2ResourceServer().jwt() and .opaqueToken() over custom filters (the custom JWT filter here is educational only).
  3. Bind validation to the audience โ€” check issuer, audience, expiry, and scopes, not just signature.
  4. Plan revocation โ€” opaque tokens and sessions revoke instantly; JWTs need short lifetimes or introspection fallback.
  5. Keep stores honest โ€” hash passwords (LAB-003) and API keys (LAB-026) at rest; never log credentials.

๐Ÿ”— Next Steps