Integration
1. Sister Services
| Sister | Direction | Surface | Auth | Failure Mode | Idempotency |
|---|---|---|---|---|---|
All VerifierApplication (sale, inventory, commerce, finance, payment, signal, etc.) | → (sister pulls) | HTTP GET /jw-certs | none (public JWKS) | retry; cache previous JWKS until reachable | JWKS rotation aware via kid |
| All sisters | → (sister calls) | HTTP — PolicyDefinitionService lookup endpoints | JWT | sister caches in Redis | per (role, action, subject) |
@nx/sale (Customer queries) | → (sale reads) | HTTP — CustomerController CRUD via cross-package repository | JWT or BASIC | retry | merchant-scoped |
@nx/signal | → | WebSocket emission via ApplicationWebSocketComponent | — | best-effort | broadcast |
Identity does not directly call sister services. The pull-based JWKS model is the trust foundation.
2. External Systems
| System | Direction | Surface | Auth | Failure Mode |
|---|---|---|---|---|
| SMTP (Gmail / merchant SMTP) | → | NodemailerComponent | SMTP credentials from env | retry via internal queue executor |
| VN Pay SMS | → | MQSMSComponent | provider config from Configuration table | per-merchant config; queue retries |
| Redis | ↔ | OTP state, BullMQ (mail/SMS queue), auth cache | password from env | service starts without it (auth cache disabled); OTP requires Redis |
3. Critical Cross-Service Flows
3.1 Sister boot — JWKS bootstrap
Sister caches indefinitely; refreshes only when a JWT carries an unknown
kid.
3.2 Authenticated request flow (sister side)
3.3 Permission check (cross-service)
In current BANA setup, the
PolicyDefinitiontable is shared (single DB), so sisters typically read directly viaPolicyDefinitionRepositoryrather than HTTP-calling identity. Identity owns the write path for policy mutations.
3.4 Sign-up → default role assignment
4. Contract Stability
| Surface | Stability | Versioning |
|---|---|---|
GET /jw-certs | stable | RFC 7517 JWKS format |
JWT payload { userId, roles, organizers, merchants } | stable | additive only |
HTTP /v1/api/identity/* | stable | URL prefix /v1/ |
Configuration table (mail/SMS/OTP) | stable | additive (new codes) |
PolicyDefinition table | stable | additive |
5. Crosscutting concerns
| Concern | Handling |
|---|---|
| Trust | All sister services trust the /jw-certs issuer; key rotation handled by kid |
| Single key vs per-merchant | Single signing key today; multi-tenant key isolation is out of scope (see purpose & scope) |
| Service-to-service | BASIC auth strategy supported for cross-package calls |
| Snapshot fields | JWT payload roles/orgs/merchants are a snapshot at issue time — clients should refresh on permission changes |