Architecture¶
Components¶
flowchart TB
subgraph Git["Git (admin-controlled)"]
RSIP[ResourceSetInputProvider<br/>one per approved client]
end
subgraph K8s["Kubernetes cluster"]
direction TB
Flux[Flux ResourceSet<br/>as charter-provisioner] -->|renders| IC[IAMClient]
Flux -->|renders| Role[Role + RoleBinding<br/>owner may edit redirectURIs]
VAP[ValidatingAdmissionPolicy<br/>MutatingAdmissionPolicy] -.guards.-> IC
Team[Owning team] -->|patch redirectURIs| IC
Ctl[charter-iam controller] -->|watch, finalizer, status| IC
Ctl -->|server-side apply| Sec[Secret <name>-entra]
Ctl -->|server-side apply| PS[PushSecret <name>-entra]
ESO[External Secrets Operator] -->|reads| Sec
ESO -->|watches| PS
App[Team workload] -->|mounts| Sec
WI[Azure Workload Identity webhook] -.injects token.-> Ctl
end
subgraph Azure["Microsoft Entra ID"]
Entra[(App registration<br/>Service principal<br/>Owners, passwords)]
end
Bao[(OpenBao KV v2)]
SIEM[(SIEM / WORM storage)]
RSIP --> Flux
Ctl -->|Microsoft Graph v1.0| Entra
ESO -->|write| Bao
Ctl -->|audit JSON on stdout| SIEM
| Component | Responsibility |
|---|---|
IAMClient |
The request and the system of record for intent. |
| Flux ResourceSet | The admin provisioning path. Renders an IAMClient and a per-client owner Role from each approved input provider. |
| Admission policies | Only admins create, delete or change admin-only fields; owners only change redirectURIs; the author is stamped on every write. |
charter-iam |
Converges Entra to the IAMClient, delivers credentials, writes status and audit records. The only component that talks to Graph. |
Secret <name>-entra |
The delivered credentials. Always written. Owned by the IAMClient. |
PushSecret <name>-entra |
Optional. Tells External Secrets Operator to copy the Secret to OpenBao. |
| Entra ID | Holds the app registration, service principal, owners and passwords. |
Trust boundaries¶
- Admin to cluster. Only platform admins and the Flux provisioner can create clients or change admin-only fields. Enforced by admission and re-checked by the controller (approval gate).
- Owner to cluster. An owning team has RBAC on its own
IAMClientonly, and admission limits it toredirectURIswithin the allowed domains. - Controller to Entra. Workload identity, no stored secret. The
permission
Application.ReadWrite.OwnedByconfines the blast radius to registrations the controller created. - Controller to consumers. Credentials are only ever written to the client's own namespace (Secret) and to a path the controller derives (OpenBao). The team cannot choose where its secret goes.
See the threat model for the threats at each boundary.
Design decisions¶
- Fail closed. Approval is required unless
REQUIRE_APPROVAL=false; redirect domains and push stores must be allow-listed; loopback redirects are off by default; an empty allow-list refuses everything. - Idempotency through
uniqueName. Graph's upsert on an alternate key (PATCH /applications(uniqueName='...')withPrefer: create-if-missing) means a crash or a lost status never creates a duplicate app. - Status is not trusted for secrets. Which password is delivered is read from the Secret's annotations, which are written in the same request as the secret value, so the two cannot disagree after a crash.
- Retain by default on delete. Secrets are revoked and the registration is kept as evidence.
- Calls Graph directly. No dependency on Azure Service Operator or Crossplane. The Graph module could be replaced by one that writes their objects; the reconcile shape stays the same.
- Single writer. One replica, no leader election yet.
Code map¶
| Module | Contents |
|---|---|
src/main.rs |
Startup, crd subcommand |
src/crd.rs |
IAMClient types (the CRD is generated from these) |
src/controller.rs |
Reconcile and cleanup |
src/policy.rs |
Policy settings, approval gate, spec hashing |
src/graph.rs |
Minimal Microsoft Graph client and token acquisition |
src/push.rs |
PushSecret rendering and sync status |
src/audit.rs |
Audit records and Kubernetes Events |
More in code layout.