AuthKit-Pro architecture

Spring-owned and AuthKit-owned responsibilities

Authentication responsibility boundary
Spring owns	AuthKit-Pro owns
AuthenticationManager, DaoAuthenticationProvider, BCrypt	Local users, registration, and password lifecycle policy
Resource Server, JWT parsing and standard validation	JWT issuance and live account/session-state validation
OAuth2 Login, state, code exchange, OIDC verification	External identity mapping and explicit link/unlink policy
WebAuthn DSL and JDBC credential repositories	Passkey metadata and success-to-session bridge
One-Time Token login and JDBC token service	Eligibility, delivery, and success-to-session bridge
Authorization infrastructure, CSRF, transactions, mail transport	Endpoint ownership, account/session persistence, and notification policy

Login and JWT flow

The API does not keep an authenticated HTTP session and does not maintain an access-token denylist. Each authenticated request performs a live account/session state read after Spring validates the JWT.

Authentication flow

Password / WebAuthn / OAuth2-OIDC / OTT success
  → local account and policy checks
  → independent AuthSession
  → JWT access token with sid + rotating opaque refresh credential
  → stateless Bearer API request
  → Spring JWT validation
  → AuthKit live account/session-state validation

Security filter-chain boundaries

WebAuthn: optional native ceremonies, temporary HTTP-session challenges, cookie CSRF, and JWT for credential management.
OAuth/browser/OTT: Spring authorization state plus short-lived explicit-link intent; state-changing requests require CSRF.
/api/**: stateless Bearer JWT authentication; only the documented POST authentication/lifecycle allowlist is public; CSRF is disabled because cookies do not authenticate the API.
Fallback: optional local API tester, actuator health/info/discovery, and denial of other unmatched routes.

Refresh rotation and replay handling

A session is one refresh family. Rotation retains the consumed digest and writes the replacement under database locking. Reuse marks only that family compromised and revoked; unrelated sessions remain active.

Account lifecycle

Verification, reset, and email-change credentials share a minimal purpose-bound model. User-first locking serializes account and session mutations. Password reset/change, confirmed email replacement, and account disable revoke all sessions and outstanding lifecycle/OTT credentials.

External identity policy

External identity ownership uses verified OIDC issuer plus subject, or OAuth registration plus stable provider ID. Mutable login names, display names, and emails do not determine ownership. Uniqueness prevents one external identity from linking to two accounts.

One-Time Token and security events

Spring owns One-Time Token generation, persistence, expiry, single-use consumption, and authentication. AuthKit-Pro coordinates account eligibility and delivery, then creates an AuthKit session after success. Domain events store secret-free activity and trigger selected after-commit notifications.

Persistence and migrations

H2 provides the dependency-free local path; the schema stays MySQL-compatible.
Flyway is the schema authority and Hibernate uses validate.
Upgrade migration preserves users and valid Lite refresh credentials, but existing Lite access JWTs lack sid and must refresh or log in.
Back up a production database before migration and verify the deployment's exact MySQL version, timezone, and collation.

Explicit deferred boundaries

MFA, conditional MFA, JWT step-up, and TOTP
Persistent brute-force lockout and distributed rate limiting
Distributed authentication cancellation
Durable mail outbox and retry infrastructure
Application-specific domain authorization, tenancy, and deployment policy