How gustavoventieri/auth-api-sample works
Auth API Sample is a Spring Boot authentication and authorization API with a framework-independent core. Its main flow is account registration, email OTP verification, mandatory TOTP setup, then two-step sign-in and cookie-based JWT/refresh-token sessions. It also supports session renewal and revocation, recovery codes, administrative MFA reset, RBAC, and email notifications. The graph follows README-documented capabilities and relationships visible in the supplied source excerpts; unsampled adapter wiring is not asserted beyond those documented links.
Main entry points: MfaController.java MFA endpoints · AuthController.java Auth endpoints · VerifyEmailVerificationTokenService.java Email verification · SessionController.java Session endpoints
Components 23
HTTP and security
- Auth endpoints
framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/AuthController.java - MFA endpoints
framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/MfaController.java - Session endpoints
framework/src/main/java/com/auth/api/framework/auth/adapter/port/in/web/SessionController.java - Security and RBAC
framework/src/main/java/com/auth/api/framework/shared/config/security/SecurityConfig.java
Identity lifecycle
- Account signup
core/src/main/java/com/auth/api/core/auth/application/service/sign/SignUpService.java - Email verification
core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java - User state
core/src/main/java/com/auth/api/core/user/domain/UserDomain.java
MFA and sessions
- TOTP setup
core/src/main/java/com/auth/api/core/auth/application/service/mfa/SetupTotpService.java - Confirm TOTP
core/src/main/java/com/auth/api/core/auth/application/service/mfa/ConfirmTotpSetupService.java - MFA verification
core/src/main/java/com/auth/api/core/auth/application/service/mfa/VerifyTotpService.java - Recovery codes
core/src/main/java/com/auth/api/core/auth/application/service/mfa/VerifyRecoveryCodeService.java - Admin MFA reset
core/src/main/java/com/auth/api/core/auth/application/service/mfa/AdminResetMfaService.java - Sign in
core/src/main/java/com/auth/api/core/auth/application/service/sign/SignInService.java - Issue tokens
core/src/main/java/com/auth/api/core/auth/application/service/sign/IssueAuthTokensService.java - Rotate session
core/src/main/java/com/auth/api/core/auth/application/service/refreshToken/RenewRefreshTokenService.java - Sign out
core/src/main/java/com/auth/api/core/auth/application/service/sign/SignOutService.java
Infrastructure
- User persistence
framework/src/main/java/com/auth/api/framework/user/adapter/port/out/UserRepositoryAdapter.java - Session and MFA storage
framework/src/main/java/com/auth/api/framework/auth/adapter/port/out/persistence/RefreshTokenRepositoryAdapter.java - JWT utilities
framework/src/main/java/com/auth/api/framework/auth/utils/jwt/JwtAccessTokenGenerator.java - Email delivery and templates
framework/src/main/java/com/auth/api/framework/shared/email/EmailAdapter.java
Other components
- API client
- Email provider
- PostgreSQL
Connections 28
- API client → Auth endpoints: submits auth
- API client → MFA endpoints: submits MFA
- API client → Session endpoints: manages sessions
- Auth endpoints → Account signup: invokes signup
- Auth endpoints → Email verification: invokes verification
- Auth endpoints → Sign in: invokes sign-in
- MFA endpoints → TOTP setup: starts setup
- MFA endpoints → Confirm TOTP: confirms setup
- MFA endpoints → MFA verification: verifies code
- MFA endpoints → Recovery codes: checks recovery
- MFA endpoints → Admin MFA reset: requests reset
- Session endpoints → Rotate session: renews session
- Session endpoints → Sign out: revokes session
- Security and RBAC → Auth endpoints: protects routes
- Security and RBAC → MFA endpoints: authorizes roles
- Account signup → User persistence: persists account
- Email verification → User state: verifies user
core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java - Email verification → Email delivery and templates: sends notice
core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java - Email verification → TOTP setup: issues setup challenge
core/src/main/java/com/auth/api/core/auth/application/service/emailVerification/VerifyEmailVerificationTokenService.java - Confirm TOTP → Issue tokens: issues session
core/src/main/java/com/auth/api/core/auth/application/service/mfa/ConfirmTotpSetupService.java - Confirm TOTP → Email delivery and templates: sends notice
core/src/main/java/com/auth/api/core/auth/application/service/mfa/ConfirmTotpSetupService.java - Issue tokens → Session and MFA storage: stores token hash
core/src/main/java/com/auth/api/core/auth/application/service/sign/IssueAuthTokensService.java - Issue tokens → JWT utilities: generates access token
core/src/main/java/com/auth/api/core/auth/application/service/sign/IssueAuthTokensService.java - Rotate session → Session and MFA storage: reads and revokes
core/src/main/java/com/auth/api/core/auth/application/service/refreshToken/RenewRefreshTokenService.java - Rotate session → JWT utilities: generates access token
core/src/main/java/com/auth/api/core/auth/application/service/refreshToken/RenewRefreshTokenService.java - Session and MFA storage → PostgreSQL: persists sessions
- User persistence → PostgreSQL: persists users
- Email delivery and templates → Email provider: delivers messages