Purpose
The User & Auth Service is the identity authority for MCSP. It issues and validates JWT access tokens, manages refresh token rotation, enforces RBAC role claims, and coordinates multi-factor authentication challenges. Every API request that reaches the application layer has already had its token signature verified at the API Gateway — the Auth Service is invoked for elevated operations such as session creation, token refresh, and privilege checks that require database-backed validation.
Zero-Trust boundary. Every inter-service call on MCSP requires a valid mTLS client certificate issued per service identity. No internal endpoint is reachable without mutual authentication — the service mesh (Istio) enforces this independently of application code.
Responsibilities
| Responsibility | Detail |
|---|
| JWT issuance | Issues short-lived access tokens (15-minute TTL) encoding role, sub (user ID), and minimal claims. Access tokens are signed with a rotating RS256 private key held in KMS. |
| Refresh token management | Rotating refresh tokens stored as HttpOnly, Secure, SameSite=Strict cookies. Each use of a refresh token rotates the token — reuse of a consumed refresh token triggers session revocation (token theft detection). |
| RBAC enforcement | Role claims in the JWT are the authoritative source for permission checks at the API Gateway. Service-level permission checks delegate to the Auth Service via gRPC for operations requiring database-backed role verification. |
| Multi-factor authentication (2FA) | TOTP-based 2FA available for all users; enforced for all admin and organisation admin accounts. Anomalous login geography triggers a 2FA challenge regardless of account settings. |
| OAuth2 / Social login | Supports OAuth2 authorization code flow for Google and Apple sign-in. External identity mapped to an internal MCSP user record on first login. |
| Session invalidation | Logout invalidates the active refresh token immediately. Session revocation by Platform Admin cascades to active sessions within 5 minutes via Redis TTL expiry. |
| Password security | Passwords stored as Argon2id hashes. Breached password check against HaveIBeenPwned API at registration and password change. Rate limiting at /login: lockout after 5 failed attempts, CAPTCHA after 3. |
API Surface
| Method | Endpoint | Auth | Description |
|---|
POST | /api/v1/auth/register | None | Create a new user account |
POST | /api/v1/auth/login | None | Authenticate and receive access + refresh tokens |
POST | /api/v1/auth/refresh | Refresh cookie | Exchange refresh token for a new access token |
POST | /api/v1/auth/logout | Bearer | Revoke current session |
POST | /api/v1/auth/2fa/setup | Bearer | Enrol TOTP 2FA |
POST | /api/v1/auth/2fa/verify | Bearer | Verify 2FA challenge |
GET | /api/v1/users/me | Bearer | Fetch authenticated user profile |
PATCH | /api/v1/users/me | Bearer | Update profile (name, avatar, language preference) |
DELETE | /api/v1/users/me | Bearer | Initiate account deletion (GDPR right to erasure) |
Data Owned
| Store | Schema |
|---|
| Postgres | users (id, email, password_hash, role, status, created_at), refresh_tokens (token_hash, user_id, expires_at, revoked), mfa_configs (user_id, totp_secret, enabled) |
| Redis | Session cache keyed by session:{userId} (15-minute sliding TTL); failed login attempt counters |
Kafka Topics
The Auth Service does not produce Kafka events. It is a synchronous service — its outputs are direct API responses and session state in Redis/Postgres.
Failure Behaviour
| Failure | Behaviour |
|---|
| Auth Service pod failure | API Gateway falls back to cached session validation from Redis for up to 5 minutes. Operations requiring database-backed validation (role elevation, session creation) fail with 503 until recovery. |
| Redis cache miss | Auth Service falls back to Postgres session lookup. Higher latency per request but correct behaviour. |
| KMS unreachable | Token issuance fails — new login requests return 503. Active sessions remain valid until existing JWT expiry. |
Related Pages
