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.
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.
- Spring API:
http.httpBasic(Customizer.withDefaults())installsBasicAuthenticationFilter, which decodes the header and delegates to the configuredAuthenticationManager. - When to use: simple machine-to-machine calls inside a trusted network, quick diagnostics, and teaching
UserDetailsService/AuthenticationProvidermechanics. - When to avoid: browsers (no logout, credentials cached), untrusted networks, anything without TLS.
- Status โ Theory. No
httpBasic(...)chain is wired in this repository today. Thejdbc-onlyandldap-onlyprofiles 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)¶
- Spring API:
http.oauth2ResourceServer(rs -> rs.opaqueToken(...))with anOpaqueTokenIntrospector. - Evidence:
OpaqueTokenResourceServerConfigprotects/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¶
- Spring API: a custom
OncePerRequestFilter(ApiKeyAuthenticationFilter) beforeUsernamePasswordAuthenticationFilter; there is no standardhttp.apiKey()DSL. - Evidence:
ApiKeyAuthConfigandApiKeysAndQuotasLabTestprove hashed key lookup and per-key quotas in LAB-022;SecureApiKeyServiceandApiKeyLifecycleLabTestprove 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.
- Spring API (recommended):
http.oauth2ResourceServer(rs -> rs.jwt(Customizer.withDefaults()))โ never a hand-rolled bearer filter. - Evidence:
ResourceServerSecurityConfigprotects/rs/**and is proven byResourceServerJwtLabTestin LAB-009 (signature, issuer, audience, expiry, authority checks). LAB-015 adds JWK rotation and multiple issuers; LAB-023 adds tenant-awareJwtDecoderresolution. - Educational filter:
JwtAuthenticationFilter+JwtTokenUtilincommon-authstill 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.
- Spring API:
http.formLogin(...)issues the session;sessionManagement(...)controls fixation, concurrency, and creation policy (IF_REQUIREDfor browsers,STATELESSfor APIs). - Evidence:
BrowserSecurityConfigisolates a stateful chain on/browser/**withIF_REQUIREDsessions, CSRF protection, and hardened headers โ proven in LAB-006 (identifier rotation, logout invalidation), LAB-007, and LAB-008. Thejdbc-only/ldap-onlyprofile chains inMultiAuthSecurityConfiguse 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 |
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:
- Request Authorization and Secure Login โ the filter chain and provider contract every mechanism relies on.
- Session Auth โ LAB-006 โ LAB-007 โ LAB-008: stateful browser security done right.
- JWT โ LAB-009 โ LAB-015: standard resource server, then rotation.
- OAuth โ LAB-010 โ LAB-011 โ LAB-018 โ LAB-019 โ LAB-020.
- Token Auth โ LAB-013 โ LAB-022 โ LAB-026.
- Basic Auth โ Theory only today; revisit once a dedicated chain exists (or treat as a contrast case in the Authentication Flow diagrams).
- 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¶
- TLS everywhere โ every mechanism above sends a reusable credential; only JWT limits replay damage to its expiry window.
- Prefer standard support โ
oauth2ResourceServer().jwt()and.opaqueToken()over custom filters (the custom JWT filter here is educational only). - Bind validation to the audience โ check issuer, audience, expiry, and scopes, not just signature.
- Plan revocation โ opaque tokens and sessions revoke instantly; JWTs need short lifetimes or introspection fallback.
- Keep stores honest โ hash passwords (LAB-003) and API keys (LAB-026) at rest; never log credentials.
๐ Next Steps¶
- Security Configuration โ How mechanisms compose into filter chains
- Authentication Flow โ Sequence diagrams for each mechanism
- SSO with OIDC and SAML โ Federation beyond a single application
- Coverage Registry โ Honest status for every mechanism
- Lab Roadmap โ Ordered executable proof for each capability