ADR-0001. Single JWKS issuer as the platform trust root
| Field | Value |
|---|---|
| Status | Accepted |
| Date | 2026-01-08 |
| Deciders | identity-team, platform-architect |
| Supersedes | — |
Context
- BANA has 10+ backend services that all need to authenticate users.
- Each service needs to verify JWTs without phoning home on every request.
- Two patterns:
- Shared HMAC secret — every service has the same secret; symmetric.
- Asymmetric (JWKS) — one issuer signs, others verify with public keys.
Decision
@nx/identity is the only signing authority. It uses ES256 (ECDSA over P-256) and exposes public keys at GET /jw-certs (RFC 7517 JWKS format). All other services extend VerifierApplication from @nx/core which fetches /jw-certs at boot, caches by kid, and verifies signatures locally.
There is no secondary issuer, federation, or per-merchant key isolation today.
Consequences
| Pros | Cons |
|---|---|
| Sister services don't need a shared secret | Single point of trust — if signing key leaks, every JWT is forgeable |
| Asymmetric: leaks of public key are irrelevant | Key rotation is operationally tricky (need kid-aware sister cache) |
| Standard format (JWKS / JWS / JWT) — interoperable | Single key for all merchants — no tenant isolation |
| Sister services have no auth dependency on identity per-request | Identity is a platform-wide critical path (alert priority HIGH) |
Alternatives Considered
| Option | Pros | Cons | Why rejected |
|---|---|---|---|
| Shared HMAC secret | Simple | Any leaked secret compromises everything; rotation requires coordinated restart | Operational fragility |
| Per-merchant signing key | Tenant isolation | Massive complexity in sister verification logic; key explosion | Premature; multi-tenant key isolation in scope-excluded |
| Per-service signing | Decentralized | Cross-service trust collapses; every service needs to know every other's keys | Nope |
| External IdP (Auth0, Cognito) | Outsourced | Vendor lock-in; latency; cost | We need internal control of role/permission semantics |
References
@nx/coreIssuerApplicationandVerifierApplicationbase classesJWKSIssuerTokenService(used byAuthenticationService.generateToken)- RFC 7517 (JWKS), RFC 7519 (JWT), RFC 7515 (JWS)