Auth Service

The Auth Service is a FastAPI (Python) microservice that acts as the sole credential authority for the TradeX platform. It owns the signup → login → token lifecycle and is the single issuer of JWTs consumed by all downstream services.

Responsibilities

• Credential Authority: Owns email/phone + password registration and verification. Only service that stores hashed credentials.
• Token Issuer: Issues short-lived access tokens and long-lived refresh tokens (asymmetric signing). Publishes a JWKS endpoint for all services to verify tokens without calling Auth.
• Session Management: Tracks active refresh tokens per device, enforces session limits, and supports forced logout.
• MFA / OTP: TOTP-based second factor, OTP via SMS/email for passwordless flows.
• Key Management: Manages signing key pairs (rotation, JWKS publication).
• Event Producer: Emits auth.created, auth.login, auth.account.* events to Kafka for downstream consumption.
• Policy Enforcement: Account lockout after N failures, device limits, IP-based rate limiting.

Auth does not own user profile data, KYC, or preferences — those belong to the User Service.

Architecture

graph TB Client[Client App] -->|REST| Gateway[API Gateway] Gateway -->|JWT Verify via JWKS| Auth[Auth Service] Auth -->|Stores| PG[(PostgreSQL)] Auth -->|Session Cache| Redis[(Redis)] Auth -->|Events| Kafka[Kafka Bus] Kafka --> UserSvc[User Service] Kafka --> WalletSvc[Wallet Service] Auth -->|JWKS| AllServices[All Services]

Data Models (PostgreSQL)

auth_accounts

Field	Type	Description
id	UUID (PK)	Internal auth identity
email	CITEXT UNIQUE	Unique email (nullable if phone-only)
phone_e164	VARCHAR(20) UNIQUE	E.164 phone (nullable if email-only)
password_hash	TEXT	Hashed password (bcrypt / argon2id)
status	ENUM(active, suspended, deleted)	Account lifecycle state
failed_attempts	SMALLINT	Consecutive failed logins (reset on success)
locked_until	TIMESTAMPTZ	Lockout expiry (NULL = not locked)
email_verified	BOOLEAN	Email verification status
phone_verified	BOOLEAN	Phone verification status
created_at	TIMESTAMPTZ	Account creation time
updated_at	TIMESTAMPTZ	Last modification time
deleted_at	TIMESTAMPTZ	Soft-delete timestamp

auth_sessions

Field	Type	Description
id	UUID (PK)	Session identifier
account_id	UUID (FK)	References auth_accounts
refresh_token_hash	TEXT	SHA-256 hash of refresh token
device_fingerprint	TEXT	Device identifier string
ip_addr	INET	Login IP address
user_agent	TEXT	Browser/client user agent
expires_at	TIMESTAMPTZ	Refresh token expiry
revoked_at	TIMESTAMPTZ	NULL until explicitly revoked
created_at	TIMESTAMPTZ	Session creation time

jwt_blacklist

Field	Type	Description
jti	UUID (PK)	JWT ID of revoked token
account_id	UUID	Owner of revoked token
expires_at	TIMESTAMPTZ	Original token expiry (for TTL cleanup)
created_at	TIMESTAMPTZ	Revocation time

mfa_factors

Field	Type	Description
id	UUID (PK)	Factor identifier
account_id	UUID (FK)	References auth_accounts
factor_type	ENUM(totp, webauthn, sms, email)	MFA method
secret_enc	BYTEA	Encrypted TOTP secret or WebAuthn credential
is_primary	BOOLEAN	Whether this is the primary MFA factor
verified_at	TIMESTAMPTZ	When factor was verified
created_at	TIMESTAMPTZ	Creation time

signing_keys

Field	Type	Description
kid	TEXT (PK)	Key ID published in JWKS
algorithm	TEXT	RS256, ES256, or EdDSA
public_key_pem	TEXT	Public key (published via JWKS)
private_key_enc	BYTEA	Encrypted private key (KMS-wrapped)
status	ENUM(active, rotated, revoked)	Key lifecycle state
activated_at	TIMESTAMPTZ	When key became active
rotated_at	TIMESTAMPTZ	When key was rotated

auth_audit

Field	Type	Description
id	BIGSERIAL	Auto-incrementing audit ID
account_id	UUID	Account involved
action	TEXT	signup, login.success, login.fail, logout, mfa.enroll, etc.
ip_addr	INET	Client IP
user_agent	TEXT	Client user agent
metadata	JSONB	Extra context (device, geo, failure reason)
created_at	TIMESTAMPTZ	Event timestamp

Redis Keys

Key Pattern	Purpose	TTL
auth:otp:{account_id}:{channel}	Pending OTP code	5 min
auth:lockout:{account_id}	Account lockout marker	Configurable (e.g., 15 min)
auth:rate:{ip}	IP-based rate limiter	Sliding window
auth:session:count:{account_id}	Active session count	Synced with DB

APIs

Public (No Auth Required)

Method	Endpoint	Description
POST	/v1/auth/signup	Register with email/phone + password
POST	/v1/auth/login	Authenticate and receive token pair
POST	/v1/auth/verify-email	Verify email with OTP/link token
POST	/v1/auth/verify-phone	Verify phone with OTP
POST	/v1/auth/forgot-password	Initiate password reset
POST	/v1/auth/reset-password	Complete password reset with token
POST	/v1/auth/refresh	Exchange refresh token for new access token
GET	/.well-known/jwks.json	JWKS endpoint for token verification

Authenticated (JWT Required)

Method	Endpoint	Description
GET	/v1/auth/sessions	List active sessions
DELETE	/v1/auth/sessions/{id}	Revoke specific session
POST	/v1/auth/logout	Revoke current session
POST	/v1/auth/logout-all	Revoke all sessions
POST	/v1/auth/change-password	Change password (requires current password)
POST	/v1/auth/mfa/enroll	Begin MFA enrollment
POST	/v1/auth/mfa/verify	Complete MFA enrollment with code
DELETE	/v1/auth/mfa	Remove MFA factor

Internal / Admin (mTLS or Internal JWT)

Method	Endpoint	Description
GET	/internal/auth/accounts/{id}	Get account details
POST	/internal/auth/accounts/{id}/suspend	Suspend account
POST	/internal/auth/accounts/{id}/reactivate	Reactivate account
POST	/internal/auth/keys/rotate	Rotate signing keys
GET	/internal/auth/keys	List all signing keys

JWT Token Structure

Access Token Claims

{
  "sub": "auth_account_id (UUID)",
  "aud": "tradex",
  "iss": "auth.tradex",
  "iat": 1700000000,
  "exp": 1700001800,
  "jti": "unique-token-id",
  "email": "user@example.com",
  "email_verified": true,
  "mfa_verified": true
}

• Lifetime: 15–30 minutes (configurable)
• Signing: Asymmetric (RS256 / ES256 / EdDSA via signing_keys)
• Verification: Any service can verify via JWKS endpoint — no network call to Auth needed

Refresh Token

• Lifetime: 7–30 days (configurable)
• Storage: SHA-256 hash stored in auth_sessions
• Rotation: Each refresh issues a new refresh token and invalidates the old one
• Binding: Bound to device fingerprint — reuse from different device triggers revocation of all sessions

Messaging (Kafka Topics)

Topic	Key Fields	When	Consumers
auth.created.v1	auth_id, email, phone	On signup	User Service
auth.login.v1	auth_id, ip, device	On successful login	User Service, Analytics
auth.account.activated.v1	auth_id	On email/phone verification	User Service
auth.account.deactivated.v1	auth_id, reason	On suspension	User Service, Wallet, Risk
auth.account.deleted.v1	auth_id	On soft delete	User Service, Wallet

Lifecycle Flows

Signup Flow

1. Client → POST /v1/auth/signup { email, password }
2. Validate email format, password strength (min 8 chars, complexity rules)
3. Hash password with bcrypt (or argon2id)
4. Insert into auth_accounts (status = active, email_verified = false)
5. Generate OTP → store in Redis auth:otp:{id}:email (TTL 5 min)
6. Send verification email via Notification Service
7. Emit auth.created.v1 to Kafka
8. Return { auth_id, message: "Verification email sent" }

Login Flow

1. Client → POST /v1/auth/login { email, password, device_fingerprint }
2. Lookup account by email → check status = active and not locked
3. Verify password hash
4. If failed: increment failed_attempts, lock if threshold exceeded
5. If MFA enrolled: return { mfa_required: true, mfa_token } → client submits TOTP code
6. Generate access + refresh token pair (sign with active signing_keys entry)
7. Create auth_sessions row (hash refresh token)
8. Enforce device limit: if too many sessions, revoke oldest
9. Emit auth.login.v1
10. Return { access_token, refresh_token, expires_in }

Token Refresh Flow

1. Client → POST /v1/auth/refresh { refresh_token }
2. Hash token → lookup in auth_sessions
3. Validate: not revoked, not expired, device fingerprint matches
4. Issue new access token + new refresh token (rotate)
5. Update auth_sessions with new refresh token hash
6. Return { access_token, refresh_token, expires_in }

Logout Flow

1. Client → POST /v1/auth/logout (with access token)
2. Revoke the session (set revoked_at)
3. Add access token jti to jwt_blacklist (TTL = remaining access token lifetime)
4. Return 204 No Content

Concurrency Rules

• Account creation: UNIQUE constraint on email and phone_e164 prevents duplicates
• Session limits: Per-account session count enforced via Redis counter + DB check
• Token refresh: SELECT ... FOR UPDATE on session row prevents concurrent refresh races
• Password changes: Require current password verification — invalidates all other sessions
• Key rotation: New key activated → old key marked rotated → old key still valid for verification (grace period) → eventually revoked

Validation Logic

• Email: RFC 5322 format, normalized lowercase
• Phone: E.164 format validation
• Password: Minimum 8 characters, at least 1 uppercase, 1 lowercase, 1 digit
• OTP: 6-digit numeric, expires after 5 minutes, max 3 attempts
• Rate limits: 5 login attempts per minute per IP; 10 OTP requests per hour per account
• Lockout: Account locked after 5 consecutive failed attempts (configurable, 15-minute default)

Observability

Metrics (Prometheus)

• auth_signup_total{status} — Signup attempts (success/failure)
• auth_login_total{status,method} — Login attempts by method
• auth_token_refresh_total{status} — Token refresh operations
• auth_mfa_verify_total{status} — MFA verification attempts
• auth_account_locked_total — Account lockout events
• auth_session_active_gauge — Active sessions count

Tracing (OpenTelemetry)

Spans: auth.signup, auth.login, auth.verify_password, auth.generate_tokens, auth.refresh, auth.mfa.verify

Logging

Structured JSON with fields: account_id, action, ip, user_agent, status, trace_id. PII (email, phone) is masked in logs.

Security

• Password Hashing: bcrypt with work factor 12 (target: argon2id with memory=64MB, iterations=3, parallelism=4)
• Token Signing: Asymmetric keys (RS256 currently; target: EdDSA/ES256). Private keys encrypted at rest with KMS.
• JWKS Publication: /.well-known/jwks.json — eliminates need for shared secrets across services
• Refresh Token Binding: Tied to device fingerprint; cross-device reuse triggers full session revocation
• Anti-Replay: OTP nonces tracked in Redis; refresh tokens rotated on each use
• Transport: TLS 1.2+ required for all endpoints
• Internal Auth: mTLS for service-to-service calls; internal JWT with aud=admin scope for admin endpoints

Failure & Recovery

Scenario	Handling
Redis outage	Degrade gracefully: OTP delivery paused, rate limiting disabled (fail-open with stricter server-side checks)
DB outage	Return 503; no auth operations possible. Circuit breaker prevents cascading
Kafka publish failure	Transactional outbox pattern: write event to local outbox table, relay worker publishes to Kafka
Key rotation failure	Keep current key active; alert ops; retry
Notification service down	OTP stored in Redis awaiting delivery; retry with exponential backoff

SLOs

Metric	Target
Login latency (p95)	< 200 ms
Token refresh latency (p95)	< 100 ms
Signup success rate	≥ 99.5%
JWKS endpoint availability	≥ 99.99%
Event delivery to Kafka	≥ 99.9% (with outbox)

Configuration

Key Environment Variables

Variable	Description	Default
POSTGRES_URL	PostgreSQL connection string	Required
REDIS_URL	Redis connection string	Required
KAFKA_BROKERS	Comma-separated Kafka brokers	Required
JWKS_ALGORITHM	JWT signing algorithm	RS256
ACCESS_TOKEN_EXPIRE_MINUTES	Access token TTL	30
REFRESH_TOKEN_EXPIRE_DAYS	Refresh token TTL	7
MAX_SESSIONS_PER_ACCOUNT	Device session limit	5
LOCKOUT_THRESHOLD	Failed attempts before lockout	5
LOCKOUT_DURATION_MINUTES	Lockout duration	15
OTP_TTL_SECONDS	OTP expiration	300

Technology Stack

• Language: Python 3.10+
• Framework: FastAPI + Uvicorn
• ORM: SQLAlchemy + Alembic migrations
• Password Hashing: passlib with bcrypt
• JWT: python-jose / PyJWT
• Kafka: confluent-kafka-python with Avro serialization
• Package Manager: uv

Related Documentation

• Auth API Reference
• Authentication Guide
• User Service
• Kafka Events