AuthKit architecture

Meaningful project structure

src/main/java/com/auth/
├── config/       security and validated configuration
├── controllers/  HTTP endpoints
├── dtos/         request and response contracts
├── entities/     JPA entities
├── exceptions/   centralized API errors
├── repositories/ persistence interfaces
├── security/     authentication and token lifecycle
└── services/     user-facing operations

src/main/resources/
├── db/migration/ Flyway schema migrations
└── static/api-test/ browser API console

Authentication

AuthenticationManager and DaoAuthenticationProvider verify BCrypt passwords. Spring Security's OAuth2 Resource Server validates HS256 JWT signatures plus expiry, issuer, and audience claims. AuthKit does not implement a custom JWT parsing filter.

• Access tokens are short-lived and stateless.
• Refresh tokens are opaque random values; only SHA-256 hashes are stored.
• A pessimistic database lock serializes refresh rotation and rejects replay.
• One active refresh-token session is maintained per user.

Security and passkeys

Three ordered filter chains separate WebAuthn ceremony state, stateless /api/** JWT security, and the public test/actuator fallback. The WebAuthn chain uses Spring Security JDBC credential repositories and its native ownership-checked deletion filter.

Persistence and migrations

• V1__init_schema.sql creates application tables and baseline roles.
• V2__add_webauthn.sql creates Spring Security's JDBC WebAuthn tables.
• Flyway owns schema creation; Hibernate uses validate.
• H2 runs in MySQL compatibility mode; DB_URL, DB_USERNAME, and DB_PASSWORD switch to external MySQL.

Configuration

JWT settings bind under auth.jwt. Passkey settings bind under authkit.passkey. Demo data is controlled by authkit.demo-data.enabled.

Testing

MockMvc integration tests cover registration, password login, JWT validation, refresh rotation and replay, concurrent refresh, logout, disabled users, RBAC, CORS, CSRF, actuator security, WebAuthn option/failure paths, and default H2 configuration. Successful WebAuthn ceremonies still require a real browser authenticator.