Commit 3a04fcbb authored by Sergio Gimenez's avatar Sergio Gimenez Committed by Dimitrios Gogos
Browse files

docs: align FM overview-and-architecture to ADR-0038 

EWBI termination and partner-authentication positions move from mTLS to OAuth2
Client-Credentials + JWT via the centralized Keycloak federation realm.
Assumptions updated: F2 demoted (mTLS deferred, not required today); F5 adds the
Sec. 9 OAuth2 contract and partner Authorization Server; F6 elevated to cover
the federation realm — now high risk since it is the primary EWBI mechanism,
not just admin routes.
parent d73f401c

fm/overview-and-architecture.md

+5 −5
Changes for fm/overview-and-architecture.md: 5 added lines, 5 removed lines.
Original line number Diff line number Diff line
@@ -84,8 +84,8 @@ There are two success definitions: 


| Area | Current architecture position |

|---|---|

| **EWBI termination** | Terminate inbound EWBI HTTPS+mTLS requests routed via Nginx under `/ewbi/*`. |

| **Partner authentication** | mTLS with pre-exchanged certificates. Validate client certificate thumbprint against registered partner profiles. |

| **EWBI termination** | Terminate inbound EWBI HTTPS requests routed via Nginx under `/ewbi/*`. Client mTLS is a future defense-in-depth layer (ADR-0038), not required today. |

| **Partner authentication** | OAuth2 Client-Credentials + signed JWT, issued/validated via the platform's centralized Keycloak (`federation` realm). Each partner has its own Keycloak client; FM validates the `fed-mgmt` scope on inbound and obtains a token before calling out (ADR-0038). |

| **Federation agreement enforcement** | Check that the requesting partner has a valid agreement before routing any request. |

| **Outbound federation routing** | Resolve target partner from user identifiers (MSISDN — Mobile Station International Subscriber Directory Number — prefix, IP CIDR — Classless Inter-Domain Routing block) via routing table. Forward requests over EWBI to partner OPs. |

| **Inbound request dispatch** | Publish `command.srm.service.{deploy,scale,terminate}` and `command.srm.network.capability.{activate,update,deactivate}` to DataBus with `source=federation` and `federation_partner_ref` (ADR-0001). |
@@ -295,11 +295,11 @@ Per the component boundary matrix: 
| ID | Assumption | Risk if Wrong | Mitigation |

|---|---|---|---|

| F1 | Commercial federation agreements exist before a partner OP is technically onboarded. | FM processes requests from unauthorized partners. High risk. | FM validates agreement status on every inbound request. Onboarding is gated by agreement creation. |

| F2 | A mutually trusted Certificate Authority (CA) exists, or public keys are pre-exchanged between federated OPs for mTLS. | mTLS fails; no federation possible. High risk. | Document certificate exchange process. Support both CA-signed and pre-exchanged certificate models. |

| F2 | *(Deferred, ADR-0038)* A mutually trusted Certificate Authority (CA) exists, or public keys are pre-exchanged between federated OPs, for the future mTLS defense-in-depth layer. Not required for EWBI authorization today — see F6. | mTLS fails; no defense-in-depth once added. Low risk while deferred. | Document certificate exchange process for when mTLS is layered in. Support both CA-signed and pre-exchanged certificate models. |

| F3 | SRM exposes stable internal HTTP endpoints (`/internal/capacity-check`, `/internal/zones`, `/internal/network-queries/location`, `/internal/network-queries/device-status`) that FM can call. | FM cannot validate capacity, sync catalogues, or fulfill synchronous federated queries. Medium risk. | Shared internal API contract via oop-commons. |

| F4 | DataBus is available with `OOP_TASKS` and `OOP_EVENTS` streams configured. | Federation dispatch blocked. High risk. | Streams created at startup. FM persists transaction state in PostgreSQL as fallback for tracking. |

| F5 | EWBI APIs follow OPG.04 v6.0 standards. Partner OPs implement compatible EWBI endpoints. | Interoperability failures with partners. High risk. | Contract tests against OPG.04 OpenAPI specs. Mock partner OP for testing. |

| F6 | Keycloak is available for internal operator authentication (admin routes). | FM admin API unprotected. Low risk. | Admin routes are internal; network-level controls as backup. |

| F5 | EWBI APIs follow OPG.04 v6.0 standards, including the Sec. 9 OAuth2 Client-Credentials contract. Partner OPs implement compatible EWBI endpoints and run their own OAuth2 Authorization Server per Sec. 9.2. | Interoperability failures with partners. High risk. | Contract tests against OPG.04 OpenAPI specs. Mock partner OP for testing. |

| F6 | The platform's centralized Keycloak is available, with a `federation` realm for EWBI partner OAuth2 Client-Credentials (ADR-0038) in addition to the `oop` realm for internal operator authentication (admin routes). | FM admin API unprotected; EWBI requests cannot be authorized at all (no fallback — this is now the primary mechanism, not just admin). High risk for the federation realm, low for admin. | Keycloak is core platform infrastructure (shared with OEG); network-level controls as backup for admin routes only. |



---