diff --git a/system-design/concepts/identity/identity-and-trust.md b/system-design/concepts/identity/identity-and-trust.md new file mode 100644 index 0000000..7369d74 --- /dev/null +++ b/system-design/concepts/identity/identity-and-trust.md @@ -0,0 +1,74 @@ +# Identity and Trust + +Margo components need a way to prove who they are to one another. A Workload Fleet Manager has to know that a request really comes from a device it manages; a device has to know it is talking to the WFM its operator intended, not an impostor. The **Margo Identity and Authorization Framework (MIAF)** provides that foundation: a common way for Margo components to hold verifiable identities and authenticate to each other. + +## Why identity lives at the Trust Domain level + +A single industrial deployment often mixes hardware and software from several vendors. One environment might run more than one Workload Fleet Manager, from different suppliers, each managing its own devices. If each WFM defined its own identities and distributed its own trust anchors, nothing would recognize anything issued elsewhere, and every pairing of components would need its own bespoke trust setup. + +MIAF avoids that by lifting identity to the level of a **Trust Domain**: a governed boundary within which identities are issued and mutually recognized. Every component in the domain validates identities against the same published trust material, so a device and a WFM from different vendors can recognize each other without a private arrangement between the two suppliers. + +MIAF builds on [SPIFFE](https://spiffe.io/), an open cloud-native identity standard, rather than inventing Margo-specific credentials. This keeps Margo aligned with widely implemented tooling. + +## The moving parts + +MIAF has four elements that work together: + +- **Trust Domain**: the security boundary. It defines the trust anchors, the identity namespace, and the policies for the components within it. +- **Margo Identity Service (MIS)**: the authority that issues identities and publishes trust material for the domain. It is a *role*, not a specific product; a certificate authority, a SPIFFE service such as SPIRE, or an operator's own provisioning workflow can all fill it. +- **Margo components**: the WFMs, device clients, and infrastructure services that hold an identity. Each acts as a holder when it authenticates and as a verifier when it checks a peer. +- **Trust Bundle**: the set of trust anchors the domain publishes. A verifier validates a peer's identity against it. + +An identity is expressed as a **SPIFFE ID**, a URI that names a component within its Trust Domain, and is carried by an **X.509-SVID**, an X.509 certificate with that SPIFFE ID embedded in it. Components authenticate to each other with mutual TLS, each presenting its SVID and validating the peer's against the Trust Bundle. Authorization then happens locally: each component decides what a verified identity is allowed to do. There is no central authorization server in the path. + +```mermaid +flowchart LR + Client["`**Margo Client Component** + (e.g., WFM Client, DFM Client, Telemetry Agent)`"] + Server["`**Margo Server Component** + (e.g., WFM, DFM, Observability Platform, Component Registry)`"] + MIS["`**Margo Identity Service (MIS)** + Issues SVIDs, publishes Trust Bundle & discovery`"] + TD["`**Trust Domain** + Defines trust anchors, policies, and namespace`"] + X509["`**X.509 SVID** + Certificate binding SPIFFE ID to key pair`"] + TB["`**Trust Bundle** + X.509 trust anchors`"] + + Client -->|"holds X.509 SVID"| X509 + MIS -->|"issues X.509 SVID"| X509 + Client -->|"authenticates using X.509 SVID (mTLS)"| Server + Server -->|"verifies SVID using Trust Bundle of"| TD + TD -->|"publishes"| TB + + classDef comp fill:#e8f1ff,stroke:#5b8def,stroke-width:1px,rx:8px,ry:8px,color:#0b3b8c; + classDef ident fill:#e8f7ee,stroke:#2ca36b,stroke-width:1px,rx:8px,ry:8px,color:#0f5132; + classDef trust fill:#f7f7f7,stroke:#bdbdbd,stroke-width:1px,rx:8px,ry:8px,color:#333; + + class Client,Server,MIS comp; + class X509 ident; + class TD,TB trust; +``` + +## Fitting the MIS to a deployment + +Because the MIS is a role rather than a product, an operator can fulfil it in whatever way suits their environment, for example: + +| Pattern | How it works | Where it fits | +| :--- | :---------- | :--------------- | +| **Self-signed root CA** | A certificate authority acts as its own root and issues identities directly. | Self-contained or air-gapped sites. | +| **Intermediate CA under enterprise PKI** | A certificate authority issues identities that chain up to an existing corporate root. | Enterprises with established PKI. | +| **SPIFFE-conformant identity service** | A service such as SPIRE issues identities, configured with Margo's conventions. | Cloud-native or service-mesh environments. | + +## Room to grow + +Because MIAF is a general framework built on the open SPIFFE standard, the same identity model is not limited to the device-to-WFM connection it secures today. The nearest step is Margo's own future interfaces authenticating the same way: basing a device's interaction with a [Device Fleet Manager](../../personas-and-definitions/technical-lexicon.md#device-fleet-manager) on MIAF is already envisioned, and it would work like the device-to-WFM connection does today, with each side presenting its SVID. + +The same foundation also reaches new kinds of participant. Giving a workload a verifiable identity is what SPIFFE was built for, and it extends to autonomous and agentic AI workloads that run at the edge and need to authenticate to services, or to each other. + +## Where to go next + +- The normative rules are in the [Margo Identity and Authorization Framework](../../specification/identity/identity-framework.md). +- How WFMs and device clients are named and recognized is in the [WFM Identity Profile](../../specification/identity/wfm-identity-profile.md). +- How a device client establishes trust in practice is described in [Device Client Onboarding](../workload-fleet-managers/device-client-onboarding.md). diff --git a/system-design/concepts/meta.json b/system-design/concepts/meta.json index efe4bc2..2c11113 100644 --- a/system-design/concepts/meta.json +++ b/system-design/concepts/meta.json @@ -1,4 +1,4 @@ { "title": "Concepts", - "pages": ["applications", "workload-fleet-managers", "edge-compute-devices", "gateways"] + "pages": ["applications", "workload-fleet-managers", "edge-compute-devices", "gateways", "identity"] } \ No newline at end of file diff --git a/system-design/concepts/workload-fleet-managers/device-capabilities.md b/system-design/concepts/workload-fleet-managers/device-capabilities.md index ea98b56..d84ba2a 100644 --- a/system-design/concepts/workload-fleet-managers/device-capabilities.md +++ b/system-design/concepts/workload-fleet-managers/device-capabilities.md @@ -6,7 +6,7 @@ The purpose of device capabilities reporting is to ensure the Workload Fleet Man ### Device Capability Reporting -The device owner reports their device's capabilities and characteristics, via the device API, when onboarding the device with the Workload Fleet Management solution. Additionally, during the lifecycle of the edge device, if there is a change that impacts the reported characteristics, the device updates the Workload Fleet Manager with the latest information via the [Device Capabilities API](../../specification/margo-management-interface/device-capabilities.md). +The device owner reports their device's capabilities and characteristics, via the device API, when the device's client first connects to the Workload Fleet Management solution. Additionally, during the lifecycle of the edge device, if there is a change that impacts the reported characteristics, the device updates the Workload Fleet Manager with the latest information via the [Device Capabilities API](../../specification/margo-management-interface/device-capabilities.md). The following information is exchanged: diff --git a/system-design/concepts/workload-fleet-managers/device-client-onboarding.md b/system-design/concepts/workload-fleet-managers/device-client-onboarding.md index 8354da6..b337518 100644 --- a/system-design/concepts/workload-fleet-managers/device-client-onboarding.md +++ b/system-design/concepts/workload-fleet-managers/device-client-onboarding.md @@ -1,43 +1,76 @@ # Device Client Onboarding -To enable workload management, the device's client first establishes trust and completes an onboarding process with the End Users' selected Workload Fleet Manager. This onboarding process enables late binding, which is a critical Margo non-functional requirement that enables a device to bind to any Margo-compatible Workload Fleet Manager. +To enable workload management, a device's client establishes trust and a managing relationship with the End User's selected Workload Fleet Manager. This supports late binding, a critical Margo non-functional requirement that lets a device bind to any Margo-compatible Workload Fleet Manager. -The onboarding process includes several core functions: +Onboarding covers three core functions: -- Establishing trust between the device and the WFM -- Registering the device client and assigning a unique identifier -- Reporting device capabilities to enable workload placement decisions +- establishing mutual trust between the device's client and the WFM; +- giving the WFM Client a verifiable identity the WFM recognizes; and +- reporting device capabilities so the WFM can make workload placement decisions. -## Trust Establishment +## Identity and trust -Initial trust is established between the device's Workload Fleet Management (WFM) Client and the WFM using server-side TLS. -Before the WFM Client can connect securely, it obtains the WFM's root CA certificate. This trust anchor can be: +Identity for the device's client comes from the [Margo Identity and Authorization Framework (MIAF)](../../specification/identity/identity-framework.md). Rather than a trust anchor and an identifier that live only at one WFM, MIAF issues identities at the level of a **Trust Domain**: a governed boundary within which identities are issued and mutually recognized across vendors. -- downloaded via the Certificate API, provided that an existing trusted channel is available, or -- delivered out-of-band (e.g., preloaded by the device owner or transferred via USB) +Each WFM Client holds an **X.509-SVID**: an X.509 certificate that carries a SPIFFE ID naming the client within the Trust Domain, under the WFM that issues it. The WFM holds its own SVID naming the WFM. An operator provisions both before the client first connects, following the [WFM Identity Profile](../../specification/identity/wfm-identity-profile.md). There is no in-band request in which a device submits a certificate and receives an assigned identifier; the identity is established out of band, through the operator's provisioning channel. -Importing the WFM's root CA certificate enables the WFM Client to authenticate the WFM during TLS connections. Mutual TLS (mTLS) is deliberately avoided, as some deployment environments include network components or intermediaries that may not support or forward client-certificate authentication. -Instead, transport security and server authentication are provided by server-side TLS, while client authentication and request integrity are performed at the application layer: the WFM Client uses its own X.509 certificate to create HTTP message signatures for each request. This approach maintains strong, certificate-based authenticity and integrity while accommodating a wide range of network architectures. +## Establishing trust +Trust between the WFM Client and the WFM is **mutual**, carried at the transport layer by mTLS. Each side presents its SVID and validates the other's against the Trust Domain's **Trust Bundle**, the set of trust anchors published for the domain. -## Certificates required +Before it can validate anything, the client needs the Trust Bundle. An operator can deliver it out of band through the provisioning channel, or the client can retrieve it over HTTPS. Because an HTTPS retrieval predates any MIAF-issued trust, the client authenticates that connection using an initial trust mechanism set up out of band: a configured set of trust anchors, or operator-provisioned certificate pins. Once the client holds the bundle, it is the authoritative source for validating identities within the Trust Domain. -Both the WFM server and the WFM Client use X.509 certificates, but for different purposes. The WFM's certificate authenticates the server during TLS sessions. Each device client possesses a unique X.509 certificate used to sign its HTTP requests, enabling the WFM to verify the origin and integrity of every message. These certificates provide complementary security properties: TLS ensures transport confidentiality and server authenticity, while application-layer signatures provide client authentication and payload integrity. Private keys remain securely stored on the device, and all signing operations occur locally, reducing exposure to key compromise. +When the client connects to the WFM: +- it validates the WFM's SVID against the Trust Bundle and confirms the WFM is the one named in its own SVID, so it does not connect to the wrong WFM; and +- the WFM validates the client's SVID against the Trust Bundle and confirms the client belongs to its own namespace. -## Unique Identifiers +Belonging to the namespace is not the same as permission to use the API. A valid SVID tells the WFM the client was issued for it, but the WFM serves a client only once its operator has added that client to an **accepted-client policy**. This policy is where the operator decides which clients a WFM manages, and removing a client from it is how the operator later ends the relationship. -The Workload Fleet Manager assigns a globally unique identifier to the device's management client during the onboarding process. This is needed to ensure unique interactions between each device with the Fleet Manager. +mTLS is used deliberately here: it authenticates both parties at the transport layer and removes the need for the WFM Client to sign each request at the application layer. In topologies where a TLS-offloading reverse proxy terminates the connection, the proxy validates the client's SVID and forwards the authenticated identity to the WFM backend over an operator-trusted boundary. -## Device Capability Reporting +## Capability reporting -After onboarding, the device client reports its capabilities to the WFM server using the device capability reporting API. +Once trust is established, the device's client reports its capabilities to the WFM using the [Device Capabilities API](../../specification/margo-management-interface/device-capabilities.md). This is the first exchange after the client connects, and it gives the WFM the information it needs to pair workloads with compatible devices. + +## The flow, end to end + +```mermaid +sequenceDiagram + autonumber + participant Operator + participant Client as WFM Client + participant MIS as Margo Identity Service + participant WFM + + Note over Operator,WFM: Provisioning (out of band) + Operator->>Client: Install SVID, initial trust anchors,
and endpoint URL + Operator->>WFM: Install WFM SVID,
add client to accepted-client policy + + Note over Client,MIS: Trust material retrieval + Client->>MIS: GET discovery document (optional) + MIS-->>Client: Trust Domain + Trust Bundle URI + Client->>MIS: GET Trust Bundle + MIS-->>Client: Trust anchors for the Trust Domain + + Note over Client,WFM: Mutual authentication (mTLS) + Client->>WFM: Connect, presenting client SVID + WFM-->>Client: Presents WFM SVID + Client->>Client: Validate WFM SVID, confirm WFM matches its own SVID + WFM->>WFM: Validate client SVID, check namespace and policy + + Note over Client,WFM: Management Interface exchanges + Client->>WFM: Report device capabilities + Client->>WFM: Poll desired state, report deployment status +``` ## Relevant Links Please follow the subsequent links to view more technical information on the concepts described above: -- [API Security Details](../../specification/margo-management-interface/api-requirements-and-security.md) -- [Certificate API](../../specification/margo-management-interface/certificate-api.md) -- [Device Onboarding API](../../specification/margo-management-interface/device-client-onboarding.md) -- [Device Capabilities](../../specification/margo-management-interface/device-capabilities.md) \ No newline at end of file +- [Margo Identity and Authorization Framework](../../specification/identity/identity-framework.md) +- [WFM Identity Profile](../../specification/identity/wfm-identity-profile.md) +- [Trust Bundle and Discovery Endpoints](../../specification/identity/trust-bundle-and-discovery.md) +- [Identity Lifecycle and Operator Playbooks](../../specification/identity/identity-lifecycle.md) +- [API Requirements and Security](../../specification/margo-management-interface/api-requirements-and-security.md) +- [Device Capabilities API](../../specification/margo-management-interface/device-capabilities.md) diff --git a/system-design/personas-and-definitions/technical-lexicon.md b/system-design/personas-and-definitions/technical-lexicon.md index 313c9b7..0b3ea6c 100644 --- a/system-design/personas-and-definitions/technical-lexicon.md +++ b/system-design/personas-and-definitions/technical-lexicon.md @@ -101,4 +101,40 @@ When an application gets deployed through a [Workload Fleet Manager](#workload-f The Component Registry can be implemented, e.g., as an OCI Registry. #### Container Image Registry -A Container Image Registry hosts container images. [Components](#component) which are provided as Helm Charts or Compose Archives link to such container images. \ No newline at end of file +A Container Image Registry hosts container images. [Components](#component) which are provided as Helm Charts or Compose Archives link to such container images. + +## Identity Terms + +The following terms belong to the [Margo Identity and Authorization Framework](../specification/identity/identity-framework.md) (MIAF), Margo's common foundation for identity, authentication, and authorization. MIAF builds on the open [SPIFFE](https://spiffe.io/) standard. + +#### Trust Domain + +A governed security boundary within which identities are issued and mutually recognized. A Trust Domain defines its trust anchors, the namespace for identities, and the policies that govern them. Identities from different vendors are recognized across the domain because they validate against the same published trust material. + +#### SPIFFE ID + +A URI of the form `spiffe:///` that names an identity within a [Trust Domain](#trust-domain). Margo identities issued under a MIAF profile use a path beginning with `/margo/`. + +#### SVID + +A SPIFFE Verifiable Identity Document: the verifiable credential representing an identity within a [Trust Domain](#trust-domain). Margo uses the X.509-SVID form, an X.509 certificate carrying a [SPIFFE ID](#spiffe-id) in its URI SAN, which components present when they authenticate over mutual TLS. + +#### Trust Bundle + +The set of X.509 trust anchors a [Trust Domain](#trust-domain) publishes so that verifiers can validate [SVIDs](#svid) issued within the domain. Distributed as a SPIFFE bundle (a JWK Set). + +#### Margo Identity Service + +The identity-authority role within a [Trust Domain](#trust-domain), abbreviated MIS. The MIS issues [SVIDs](#svid) and publishes the [Trust Bundle](#trust-bundle) and discovery document. It is defined by these responsibilities, not by a specific product: a certificate authority, a SPIFFE service such as SPIRE, or an operator's own provisioning workflow can fulfil it. + +#### Principal + +A non-human Margo component that holds, or is being provisioned with, an identity in a [Trust Domain](#trust-domain). [Edge Compute Devices](#edge-compute-device), [Workload Fleet Managers](#workload-fleet-manager), and WFM Clients are all principals. + +#### WFM Identity + +The identity of a [Workload Fleet Manager](#workload-fleet-manager) within its [Trust Domain](#trust-domain), of the form `spiffe:///margo/wfm/`. It anchors the namespace under which that WFM's client identities are issued. See the [WFM Identity Profile](../specification/identity/wfm-identity-profile.md). + +#### WFM Client Identity + +The identity of a WFM Client relationship within a [Trust Domain](#trust-domain), of the form `spiffe:///margo/wfm//client/`, named under the [WFM](#wfm-identity) that issues it. See the [WFM Identity Profile](../specification/identity/wfm-identity-profile.md).