diff --git a/SCOPE.md b/SCOPE.md index 7fe17ba..d0f61f3 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -23,7 +23,7 @@ NetKingdom is a self-optimizing security platform for Kubernetes-based IT infras - NetKingdom IAM Profile specification (versioned OIDC/PKCE contract) - SSO/MFA Platform: Keycloak with LDAP/Entra federation, enterprise identity (NK-WP-0001) - Local Identity: file-based user store + minimal OIDC server for bootstrap phase (NK-WP-0002) -- Security bootstrapping: credential management, SOPS/age integration, KeePassXC/Vault progression +- Security bootstrapping: credential management, SOPS/age integration, OpenBao runtime secret authority - Architectural decisions (DECISIONS.md): identity source, secrets, GitOps, bootstrap user store --- diff --git a/docs/platform-identity-security-architecture.md b/docs/platform-identity-security-architecture.md index 2f4a635..eb87953 100644 --- a/docs/platform-identity-security-architecture.md +++ b/docs/platform-identity-security-architecture.md @@ -66,8 +66,9 @@ Responsibilities: - canonical authorization through flex-auth - delegated authorization runtime through Topaz first, with other PDPs as adapters +- runtime secret authority through OpenBao - audit and explanation records -- platform service secrets and rotation +- platform service secrets, dynamic credentials, leases, and rotation Owned conceptually by `net-kingdom`; deployed through the Railiance stack. @@ -98,6 +99,7 @@ platform itself. | `key-cape` | lightweight IAM implementation of the NetKingdom IAM Profile | a general-purpose IAM platform or authorization engine | | Keycloak | expanded-mode IAM and optional Keycloak Authorization Services adapter | the canonical model for all platform authorization | | privacyIDEA | MFA/token authority, especially in lightweight/key-cape mode | a policy decision point for application resources | +| OpenBao | runtime platform secrets service, dynamic credential broker, lease/revocation point, and audit source for secret access | the bootstrap root of trust or an application-specific configuration store | | `flex-auth` | authorization control plane, CARING descriptors, policy packages, decision envelopes, audit/explain | an identity provider or backend-specific wrapper | | Topaz | first delegated authorization runtime/PDP for flex-auth | the platform control plane or identity provider | | Railiance repos | converged infrastructure, cluster, platform services, enablement, and app deployment | the source of security policy semantics | @@ -156,6 +158,45 @@ Protected services enforce decisions locally. flex-auth is the canonical policy and decision boundary; delegated PDPs are runtime implementations behind it. +## Secret And Credential Path + +```text +Bootstrap SOPS/age material + | + v +OpenBao platform secrets service + KV v2 platform configuration + dynamic database credentials + Kubernetes auth / workload identity + future object-storage credential brokering + audit devices and lease/revocation records + | + +-- direct OpenBao clients + +-- External Secrets Operator / synced Kubernetes Secrets + +-- CSI-mounted secrets where appropriate + | + v +Platform and tenant workloads +``` + +SOPS/age remains the bootstrap and Git-at-rest protection mechanism. It +can create the initial cluster secrets and emergency recovery bundles, but +it should not become the long-lived runtime authority for every workload +secret. + +OpenBao is the runtime platform secrets service once the control plane is +alive. It owns secret leases, revocation, audit, dynamic credentials, and +workload-facing secret delivery patterns. Workloads should receive scoped +secrets or short-lived credentials, not platform-root material. Tenant +administrators may manage tenant-scoped secrets through approved policy +paths; they must not gain access to OpenBao root tokens, unseal keys, +platform mounts, or global secret engine configuration. + +OpenBao does not replace identity or authorization. NetKingdom IAM +identifies actors and workloads; flex-auth decides whether a credential +or secret request is allowed; OpenBao stores, issues, audits, and revokes +the resulting secret material. + ## Recursive Trust Rule Normal tenant administration must never be sufficient to alter the @@ -173,6 +214,8 @@ Examples of platform-root actions: - changing global MFA requirements - activating authorization policy that governs platform administration - changing flex-auth/Topaz policy import pipelines +- changing OpenBao root tokens, unseal policy, platform mounts, or global + auth methods - changing audit retention or tamper-evidence settings ## Tenant Model @@ -202,14 +245,17 @@ Production setup should move through explicit trust states: 1. **Bare host trust** - provisioned and verified by Railiance infra. 2. **Cluster trust** - Kubernetes runtime exists and is verified. -3. **Secret trust** - age/SOPS and emergency bundles are established. +3. **Bootstrap secret trust** - age/SOPS and emergency bundles are + established. 4. **Bootstrap identity trust** - local/bootstrap identity can operate enough to install full identity services. -5. **Runtime identity trust** - key-cape or Keycloak becomes the normal +5. **Runtime secret trust** - OpenBao is deployed, initialized, unsealed, + audited, backed up, and ready to issue scoped secrets. +6. **Runtime identity trust** - key-cape or Keycloak becomes the normal IAM Profile issuer. -6. **Runtime authorization trust** - flex-auth and Topaz are initialized +7. **Runtime authorization trust** - flex-auth and Topaz are initialized with platform and tenant policies. -7. **Tenant onboarding trust** - Coulomb and later tenants register +8. **Tenant onboarding trust** - Coulomb and later tenants register resources and receive scoped authority. Each transition needs a verification check and a rollback/recovery path. @@ -226,7 +272,7 @@ railiance-cluster Kubernetes, ingress, cert-manager, network policy railiance-platform - PostgreSQL, object storage, secret management + OpenBao, PostgreSQL, object storage, platform service secret delivery key-cape or Keycloak privacyIDEA where used flex-auth @@ -262,8 +308,12 @@ than bypassing the Railiance stack boundaries. ## Open Questions - Where is the durable audit log stored for platform-root decisions? +- Where are OpenBao audit logs durably shipped, and how are they included + in tamper-evidence and restore drills? - Which actions require dual control or human confirmation? - How is break-glass use recorded when normal identity is unavailable? +- Which workloads consume OpenBao directly, via External Secrets Operator, + or via CSI-mounted secrets? - Which tenant metadata is required before a service can register resources with flex-auth? - When does the platform switch from key-cape lightweight mode to