Auth: hbf-core
How this service handles authentication. Full flows:
docs/architecture/auth-flows.md
Tokens This Service Accepts
| Token type | Where validated | Guard / middleware |
|---|---|---|
User JWT (login type) | TokenAuthenticationFilter (OncePerRequestFilter). HS256 signature check, issuer = hbf-auth, expiry check, type must be login. | Spring Security filter chain |
API Token (api_token type) | Same filter. Separate signing secret (APP_SECURITY_API_DEPLOYMENT_TOKEN_SECRET). Type must be api_token. | Spring Security filter chain |
Refresh Token (refresh_token type) | Accepted only at POST /login/refresh. Validated by the login controller, not the general filter. | Login controller logic |
Public endpoints (no token required):
/, /public/**, /login/**, /swagger-ui/**, /v3/api-docs/**, /actuator/health/**, /robots.txt
Tokens This Service Sends
| Calling | Token used | How attached |
|---|---|---|
| hbf-notifications (NotificationServiceClient) | Service-to-service bearer token from helvia.notification-service.token env var | Authorization: Bearer <token> header |
Tokens This Service Issues
| Token | Lifetime | Purpose |
|---|---|---|
| User JWT | 24 hours | General authenticated access |
| Refresh Token | 7 days | Obtain a new User JWT without re-authenticating |
| API Token | No expiry | Machine-to-machine / deployment access |
| Email Verification Token | 3 hours | Confirm user email address |
| Forgot Password Token | 15 minutes | Password reset link |
| User Invitation Token | 7 days | Invite a user to an organization |
Login endpoints that issue tokens:
POST /login(email + password credentials)POST /login/googlePOST /login/microsoftPOST /login/teamsPOST /login/integration(OIDC / custom)POST /login/refresh(exchanges refresh token for new JWT)
Roles / Scopes Enforced
Two-tier RBAC with @PreAuthorize annotations delegating to SecurityServiceImpl methods.
Organization roles:
| Role | Description |
|---|---|
HBF_ORG_ADMIN | Full org management |
HBF_ORG_EDITOR | Edit org resources |
HBF_ORG_VIEWER | Read-only org access |
HBF_ORG_LIVE_AGENT | Live agent capabilities |
HBF_ORG_LIVECHAT_ADMIN | Livechat administration |
HRWIZ_EMPLOYEE | HR Wizard employee role |
Tenant roles:
| Role | Description |
|---|---|
HBF_TENANT_ADMIN | Full tenant management |
HBF_TENANT_EDITOR | Edit tenant resources |
HBF_TENANT_VIEWER | Read-only tenant access |
HBF_TENANT_LIVECHAT_ADMIN | Tenant-level livechat administration |
Super-admin: The isModerator flag bypasses standard role checks.
Auth Notes
- Account lockout activates after 10 consecutive failed login attempts.
- Sessions are fully stateless. No server-side session storage.
- CSRF protection is disabled (stateless JWT-based auth).
- API tokens use a separate signing secret (
APP_SECURITY_API_DEPLOYMENT_TOKEN_SECRET), distinct from the user JWT secret. - Post-authentication callbacks exist but are disabled by default.
- All JWTs are signed with HS256 using a Base64-encoded secret.