Auth Service

Authentication and identity management gateway. Handles login, registration, token management (JWT), session management (Redis), and identity provider integration (Firebase, ZITADEL).

• Tech: NestJS 11, Redis (ioredis), Firebase Admin SDK
• Port: 4000
• Auth: JWT (RS256), Public
• Database: None (uses Redis for sessions, delegates user storage to user-service)

Endpoints

Method	Path	Auth	Description
POST	/api/v1/iam/exchange	Public	Login -- authenticate with provider, issue JWT tokens
POST	/api/v1/iam/register	Public	Register -- create account with provider + user-service
POST	/api/v1/iam/token/refresh	Public	Refresh tokens using refresh token cookie
POST	/api/v1/iam/logout	JWT	Logout -- invalidate tokens, clear sessions, clear cookies
POST	/api/v1/iam/zitadel/exchange	Public	ZITADEL token exchange
GET	/api/v1/auth-provider/types	Public	Get available auth provider types
GET	/api/v1/health	Public	Health check
GET	/metrics	--	Prometheus metrics

POST /api/v1/iam/exchange (Login)

1. Client sends credentials (email + password, or provider token)
2. Auth service validates against the identity provider (Firebase or ZITADEL)
3. Fetches user record from user-service (GET /user/by-email)
4. Issues JWT access token (RS256) and refresh token
5. Sets HTTP-only cookies (accessToken, refreshToken)
6. Returns user data in response body (tokens are in cookies only)

POST /api/v1/iam/register

1. Creates the user in the identity provider (Firebase)
2. Creates the user record in user-service (POST /user)
3. Issues JWT tokens
4. Sets cookies

If the identity provider step succeeds but user-service creation fails, the provider account is rolled back (deleted).

POST /api/v1/iam/token/refresh

Reads the refresh token from the refreshToken cookie. Validates it, generates a new token pair, and sets new cookies.

POST /api/v1/iam/zitadel/exchange

Handles ZITADEL OAuth flow:

1. Validates ZITADEL access token and ID token via introspection
2. Looks up user in user-service by ZITADEL ID
3. If not found, creates the user
4. Creates a Redis session
5. Issues Jeen JWT tokens
6. Returns { user, sessionSecret } in response body

Identity Providers

Provider	Integration	Auth Method
Firebase	Firebase Admin SDK	Email/password, token verification
ZITADEL	HTTP REST (token introspection, JWKS)	OAuth2 tokens

Session Management

Redis-based sessions for ZITADEL users:

• Key pattern: zitadel/{provider}/{orgId}/{userId}
• Sessions can be created, read, extended, and deleted
• Used for token validation and session tracking

Token Details

• Access token: JWT signed with RS256 (private key). Contains user ID, email, organization ID, roles.
• Refresh token: Stored in-memory token store (planned migration to Redis). Used to issue new token pairs.
• Both tokens set as HTTP-only cookies (accessToken, refreshToken) for browser clients.
• A legacy JWT cookie is also set (contains the access token, for backwards compatibility).
• On logout, four cookies are cleared: accessToken, refreshToken, JWT, idToken.

Inter-Service Communication

Target	Protocol	Purpose
user-service	HTTP	GET /user/by-email, POST /user, GET /user/zitadel/:id, POST /user/zitadel
Firebase	SDK	User authentication and registration
ZITADEL	HTTP	Token introspection, JWKS key fetching
Redis	Direct	Session storage