## Decision **OAuth2 Client-Credentials + signed JWT (OPG.04 Sec. 9) is the E/WBI auth mechanism. mTLS is deferred.** Rationale: mTLS (as specified in ADR-0016) depends on Nginx terminating mTLS and forwarding the client certificate to FM — that infrastructure does not exist yet. OAuth2 is already scaffolded in FM and is what OPG.04 Sec. 9 actually mandates. So: - **Now:** implement OAuth2 between FMs — tracked in #18. - **Later:** once TLS termination / Nginx exists, mTLS can be layered on top for defense-in-depth (sender-bound tokens via RFC 8705), giving the fully-layered model below. ## Why the two are not mutually exclusive They operate at different layers and answer different questions: | | mTLS | OAuth2 + signed JWT | |--|------|---------------------| | Layer | TLS handshake (transport) | HTTP `Authorization` header (application) | | Proves | which operator opened the connection | what this specific request is allowed to do (scopes) | | Unit | the connection | the individual request | | Credential lifetime | certificate (months/years) | token (minutes) | A request can pass through both checkpoints: mTLS authenticates the partner at the connection, OAuth2 scopes authorize each call. RFC 8705 (OAuth 2.0 Mutual-TLS) binds the two — tokens tied to the client certificate. ```mermaid sequenceDiagram participant A as Originating OP participant AS as Partner OP Authz Server participant RS as Partner OP E/WBI Note over A,RS: Layer 1 - transport (deferred, needs Nginx/TLS termination) A->>RS: TLS 1.3 handshake (+ client certificate once mTLS added) RS->>RS: verify partner certificate vs registered profile Note over A,RS: Layer 2 - application (implemented first, OPG.04 Sec. 9) A->>AS: POST /token (client_credentials) AS-->>A: signed JWT (scopes, expiry) A->>RS: E/WBI request + Bearer JWT RS->>RS: validate JWT signature, scopes, expiry RS-->>A: 200 OK / 401 ``` ## What the specs say GSMA **OPG.04 v6.0 Sec. 9**: > "Transport Level Security (TLS) shall be used ... The access to the E/WBI APIs shall be authorized by means of OAuth2 protocol (RFC 6749), **based on local configuration**, using the 'Client Credentials' authorization grant. **If OAuth2 is used**, a client ... shall obtain a 'token' from the authorization server." - Sec. 9.1 authorization service; Sec. 9.2 roles (Partner OP = OAuth2 Authorization + Resource server; Originating OP = client); Sec. 9.3 access tokens **shall be signed JWT** (JWS, RFC 7515); Sec. 9.5 callbacks also Client-Credentials. - Sec. 9.4 = TLS 1.3 server-side certs from trusted CAs. **Mutual TLS is not required by Sec. 9** — but nothing forbids it either. The OOP architecture (**ADR-0016 / REQ-FED-01**) currently specifies mTLS client-certificate thumbprint validation and keeps JWT only for internal admin routes — i.e. it substitutes connection-level identity for the request-level OAuth2 authorization Sec. 9 mandates. ## Consequence: ADR-0016 amendment MR Choosing OAuth2-first makes ADR-0016 / REQ-FED-01 (mTLS as the E/WBI auth mechanism) no longer the primary path. Amendment MR to `oop/architecture`: - New ADR: E/WBI auth = OAuth2 Client-Credentials + signed JWT (Sec. 9); mTLS reclassified as future defense-in-depth once TLS termination exists. - ADR-0016 **Decision**: "Nginx terminates TLS/mTLS ... FM validates the certificate thumbprint" → Nginx terminates TLS; auth via OAuth2/JWT middleware. "Outbound EWBI mTLS uses httpx with per-partner client certificates" → outbound uses httpx with a Bearer JWT. - REQ-FED-01: rewrite from "enforce mutual TLS ... validating client certificate thumbprints" to "authorize E/WBI via OAuth2 Client-Credentials + signed JWT (Sec. 9); TLS 1.3 transport". - Ripple edits in `fm/requirements-and-design.md` (the mTLS references in the endpoint-auth, error-table, and inbound/outbound flow steps) and `platform/architecture.md` (FM deep-dive, the "EWBI (HTTPS + mTLS)" connection row). `partner_ops.cert_thumbprint` column becomes unused until mTLS is layered. ## Current gap (independent of all the above) `src/api/authorization.py::check_oAuth2ClientCredentials()` returns a hardcoded identity and validates nothing — any/no token passes (see #5). Closed by #18. Related: #18, #7, #5.