From 33579fd2359dcf47bf78c55ceb0d484331cff840 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 4 May 2026 17:52:29 +0200 Subject: [PATCH] Established INTENT.md --- INTENT.md | 175 ++++++++++++ README.md | 8 +- ...ex-auth-authorization-registry-research.md | 260 ++++++++++++++++++ 3 files changed, 441 insertions(+), 2 deletions(-) create mode 100644 INTENT.md create mode 100644 docs/flex-auth-authorization-registry-research.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..37eb03d --- /dev/null +++ b/INTENT.md @@ -0,0 +1,175 @@ +# Flex-Auth Intent + +Date: 2026-05-04 + +## Intent + +Flex-auth is a policy-as-code authorization registry and control plane for +organizations that want to grow from simple access rules into enterprise-grade +authorization without giving up clear ownership, local development ergonomics, +or inspectable policy decisions. + +It belongs in the NetKingdom tooling landscape as the authorization counterpart +to key-cape/NetKingdom identity: + +```text +key-cape / NetKingdom SSO + -> verified OIDC/SAML identity claims + -> flex-auth policy-as-code and authorization registry + -> protected systems and knowledge tools +``` + +Flex-auth should run usefully on its own, but it should also delegate to or +coordinate with established authorization engines such as Topaz, OpenFGA, +SpiceDB, OPA, Cedar, Keycloak Authorization Services, and enterprise directory +systems. + +## Why This Exists + +Most organizations start with coarse roles, groups, and application-specific +conditionals. Over time they need richer policy: + +- resource hierarchies and inherited access +- project/team/tenant boundaries +- relationship-based authorization +- attribute and context based rules +- emergency/break-glass controls +- policy tests and reviewable changes +- durable decision logs and explainability +- integration with SSO, MFA, service accounts, and directory groups + +Flex-auth should give those organizations a path that starts small and grows +cleanly instead of forcing an early leap into a large IAM platform or letting +authorization logic sprawl across applications. + +## Responsibility Boundary + +### key-cape / NetKingdom Owns Identity + +- OIDC discovery and token issuance. +- Human login, MFA, PKCE, service accounts, token lifecycle. +- Canonical IAM profile and required claims. +- Coarse app roles/scopes and assurance claims. + +### flex-auth Owns Authorization + +- Protected-system registration. +- Resource namespaces and resource hierarchy. +- Canonical action vocabulary. +- Policy-as-code packages, tests, versions, and rollout. +- Mapping enterprise groups, app roles, scopes, tenants, and assurance claims + into resource-specific authorization. +- Relationship facts and inherited access. +- PDP adapter coordination. +- Decision logging, explanations, and audit export. + +### Protected Systems Own Enforcement + +Applications such as Markitect remain policy enforcement points. They extract +resource metadata, call flex-auth for decisions, enforce allow/deny/redact +results, and emit local diagnostics. They do not own central enterprise policy +administration. + +## Design Principles + +- Policy is code: versioned, reviewed, tested, and explainable. +- Identity is not authorization: SSO claims are inputs, not final decisions. +- Start standalone, scale outward: a local flex-auth deployment should be + useful before Topaz/OpenFGA/OPA integrations are available. +- Backend-neutral core: flex-auth has its own resource, action, request, + decision, and audit vocabulary. +- Pluggable PDPs: relationship, rule, and directory engines are adapters, not + hard dependencies. +- Fail visibly: denied, redacted, stale, partial, and uncertain decisions must + produce useful diagnostics. +- Grow into enterprise: the same model should support local dev, small teams, + NetKingdom-managed deployments, and larger Keycloak/Entra environments. + +## First-Class Concepts + +- Subject: human, service account, group, team, tenant, emergency principal. +- Resource: protected object registered by a system. +- Namespace: resource type and ownership boundary. +- Action: operation requested on a resource. +- Context: request, environment, assurance, workflow, or runtime attributes. +- Policy package: versioned policy-as-code bundle with tests and metadata. +- Relationship fact: subject-resource or resource-resource relation. +- Decision: allow, deny, redact, audit-only, or not-applicable with reason. +- Audit event: durable decision record with policy version and provenance. + +## Initial API Shape + +```text +register_system(system_manifest) +register_resource(resource_manifest) +sync_relationships(relationship_manifest) + +check(subject, action, resource, context) -> decision +batch_check(subject, action, resources, context) -> decisions +list_allowed(subject, action, resource_type, filters, context) -> resources +explain(decision_id) -> explanation + +publish_policy_package(package) +test_policy_package(package, fixtures) +activate_policy_version(policy_id, version) +record_decision(decision) +``` + +## Standalone Mode + +Standalone flex-auth should provide: + +- local resource registry +- local subject/group/team registry +- local relationship facts +- policy package validation +- deterministic check and batch-check APIs +- local decision log +- CLI and service mode +- test fixtures for Keycloak/key-cape-like claims + +Standalone mode should be enough for development, smaller deployments, and +integration tests. + +## Delegated Mode + +Delegated mode should let flex-auth coordinate established systems: + +- Topaz for a local directory plus OPA/Rego policy evaluation. +- OpenFGA or SpiceDB for graph-heavy relationship authorization. +- OPA or Cedar for attribute/rule policies. +- Keycloak Authorization Services for Keycloak-centric deployments. +- Microsoft Graph or SCIM/LDAP/Keycloak APIs for directory group resolution. + +Flex-auth remains the stable control plane even when the PDP backend changes. + +## First Consumer: Markitect + +Markitect is the first concrete consumer: + +- Markitect registers knowledge bases, repositories, documents, sections, + context packages, workflow artifacts, and exports. +- Markitect sends policy checks before returning query/search/context results. +- Markitect can redact or drop results based on decisions. +- flex-auth owns central policy administration and durable audit. + +This first consumer should shape flex-auth around real Markdown knowledge +pipelines without making the policy service Markitect-specific. + +## Non-Goals + +- Flex-auth is not an identity provider. +- Flex-auth is not a replacement for key-cape or NetKingdom SSO. +- Flex-auth is not a mandatory dependency for every local development use case. +- Flex-auth should not force one PDP backend. +- Flex-auth should not hide policy complexity behind opaque admin toggles. + +## Early Work + +1. Define the resource/action/decision model. +2. Define policy package structure and test fixtures. +3. Implement standalone registry and check API. +4. Add Markitect resource manifest and policy adapter. +5. Evaluate Topaz as the first delegated backend. +6. Add OpenFGA/SpiceDB and OPA adapter spikes. +7. Add Keycloak/key-cape and Entra integration examples. diff --git a/README.md b/README.md index fcd7b8f..44b3dcb 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ -# repo-seed +# flex-auth -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +Policy-as-code authorization registry and control plane for NetKingdom-aligned +systems. + +Start with [INTENT.md](INTENT.md) for the project boundary and direction. +Research notes live in [docs/](docs/). diff --git a/docs/flex-auth-authorization-registry-research.md b/docs/flex-auth-authorization-registry-research.md new file mode 100644 index 0000000..f430f80 --- /dev/null +++ b/docs/flex-auth-authorization-registry-research.md @@ -0,0 +1,260 @@ +# Flex-Auth Authorization Registry Research + +Date: 2026-05-04 + +## Purpose + +This note evaluates `flex-auth` as a separate authorization registry and +policy service for NetKingdom/key-cape environments, with Markitect as one +registered resource consumer. + +The recommendation is to build `flex-auth` as an authorization control plane +and registry, not as a new identity provider and not as logic embedded inside +Markitect. + +```text +key-cape / NetKingdom SSO + -> verified OIDC/SAML identity claims + -> flex-auth resource, relationship, policy, and audit registry + -> optional PDP backends + -> Markitect policy gateway as PEP +``` + +## Boundary Recommendation + +### key-cape / NetKingdom owns + +- OIDC discovery and token issuance. +- Human login, MFA, PKCE, service accounts, token lifecycle. +- Canonical IAM profile and required claims. +- Coarse app roles/scopes such as `hub:read`, `hub:write`, `admin`, + `service`, and `emergency`. + +### flex-auth owns + +- Registered protected systems and resource namespaces. +- Resource models such as knowledge base, repository, document, section, + context package, workflow artifact, export, and backend index. +- Canonical action vocabulary such as `read`, `query`, `search`, `package`, + `activate_context`, `export`, and `admin`. +- Mapping of enterprise groups, app roles, scopes, tenants, and assurance + claims onto resource-specific authorization. +- Relationship tuples and inherited access rules. +- Policy versions, rollout, validation, and test fixtures. +- Policy decision audit records and explanation metadata. +- Provider adapters for OpenFGA/SpiceDB, OPA/Rego, Cedar, Keycloak + Authorization Services, and Entra/Graph group resolution. + +### Markitect owns + +- Extracting policy-relevant metadata from Markdown and backends. +- Registering Markitect knowledge resources with flex-auth. +- Enforcing policy decisions at query, search, workflow, context package, + assisted prompt, render, and export boundaries. +- Local development label policy. +- Diagnostics and provenance envelopes around denied/redacted results. + +Markitect should not own central policy administration, enterprise group +mapping, directory synchronization, or global decision-log storage. + +## Product And Component Survey + +| Component | Fit | Lesson for flex-auth | +| --- | --- | --- | +| Keycloak Authorization Services | Keycloak can act as PAP/PDP/PEP ecosystem with resources, scopes, policies, permissions, UMA/RPT, and policy enforcers. | Useful adapter and fallback for Keycloak-centric deployments, but avoid making Keycloak resource modeling the only source of truth for Markitect knowledge objects. | +| Microsoft Entra ID | Strong enterprise identity, app roles, scopes, groups, Conditional Access, Graph. Entra explicitly leaves final resource authorization to APIs. | Use Entra for identity/coarse claims; flex-auth should own fine-grained resource decisions and Graph-backed group freshness. | +| OpenFGA | Relationship tuple and authorization-model service for ReBAC, with check/list APIs. | Strong backend candidate for document/folder/project/team inheritance and resource sharing. | +| SpiceDB | Zanzibar-style graph authorization with explicit consistency controls and ZedTokens. | Best fit when permission freshness and large-scale graph checks become critical. | +| Ory Keto | Zanzibar-inspired permission server using namespace/object/relation/subject tuples. | Good conceptual fit, but OpenFGA/SpiceDB currently look stronger as primary ReBAC candidates. | +| Permify | ReBAC service with schema, relationships, attributes, and developer-friendly modeling. | Good modeling inspiration, especially schema ergonomics and local testing. | +| Topaz | Open-source authorization service combining OPA/Rego with a directory inspired by Zanzibar. | Strong MVP candidate because it combines policy-as-code, local directory, users/groups/resources/relations, and local deployment. | +| OPA + OPAL | OPA evaluates Rego over structured data; OPAL synchronizes policy and data to OPA/Cedar agents. | Good fit for distributed policy/data propagation and rule evaluation, less complete alone as a resource registry. | +| Cedar | Policy language around principal/action/resource/context, with schemas and analyzable policies. | Good candidate for typed business-resource policies and future policy validation. | +| Cerbos | Application authorization PDP with resource policies, principals, derived roles, and conditions. | Good product-shape reference for check APIs, resource policies, and query planning. | +| Casbin | Lightweight multi-language authorization library with many models and storage adapters. | Useful embedded/library option, but less attractive as central enterprise registry. | +| Oso | Application authorization library/policy language with roles, permissions, and relations. | Good for app-local policy modeling, less natural as the shared NetKingdom authorization service. | + +## Canonical Keycloak Setup + +In a Keycloak environment, the canonical options are: + +1. Use Keycloak as SSO only. + - Keycloak issues OIDC tokens with roles, scopes, groups, and assurance + claims. + - flex-auth verifies tokens and makes resource decisions. + - Markitect calls flex-auth before returning knowledge. + +2. Use Keycloak Authorization Services for small or Keycloak-centric systems. + - Mark applications as resource servers. + - Register resources and scopes. + - Configure permissions and policies. + - Enforce through Keycloak policy enforcers or authorization APIs. + +3. Use Keycloak Authorization Services as one flex-auth PDP adapter. + - flex-auth remains the canonical registry. + - Keycloak AuthZ can be used where it is already operationally preferred. + +Recommendation: use option 1 as the default architecture and option 3 as an +adapter path. Option 2 is acceptable for small deployments but risks coupling +identity administration and domain-resource authorization too tightly. + +## Canonical Entra Setup + +In an Entra environment, the canonical pattern is: + +1. Entra issues access tokens. +2. APIs validate issuer, audience, signature, expiry, scopes, and roles. +3. APIs still perform final resource authorization. +4. Groups can appear as token claims, but large group membership causes + overage and must be resolved through Microsoft Graph. + +For flex-auth: + +- Use app roles for coarse application membership and elevated coarse roles. +- Use scopes for API capability grants. +- Use `oid` and `sub` as identity anchors. +- Use Microsoft Graph only through a group resolver with explicit freshness + metadata. +- Keep resource-specific policy in flex-auth, not in Entra group names. + +## Pros Of This Architecture + +- Markitect stays focused on Markdown knowledge pipelines. +- Identity and authorization are decoupled cleanly. +- Multiple consumers can share one authorization registry. +- Enterprise groups are normalized before they become application privilege. +- ReBAC, ABAC, RBAC, and rule policies can coexist behind stable APIs. +- Decision logs become central and reusable for audits. +- Context packages and agent memory can be gated consistently. +- Keycloak and Entra deployments get a canonical path without vendor lock-in. + +## Cons And How To Flip Them + +| Risk | Mitigation | +| --- | --- | +| Another service increases operational complexity. | Make flex-auth optional at first; keep Markitect local label policy for development; provide docker-compose/k3s manifests. | +| Central PDP latency can hurt query/search paths. | Support batch checks, list/filter APIs, local sidecar authorizers, short-lived caches, and consistency tokens. | +| Central authorization can become a single point of failure. | Use fail-closed for sensitive data, fail-open only for explicitly public labels, and support local cached decisions with expiry. | +| Policies can become hard to understand. | Require typed resource schemas, policy tests, examples, explain APIs, and reviewable policy-as-code changes. | +| Directory groups are stale or too large for tokens. | Prefer app roles/scopes for coarse grants; use group resolver adapters with freshness and overage metadata. | +| Vendor lock-in to one PDP model. | Define flex-auth's canonical request/decision/resource registry APIs before binding to OpenFGA, SpiceDB, Topaz, OPA, Cedar, or Keycloak AuthZ. | +| Resource registration can drift from source systems. | Let resource owners register manifests from their own repos and report sync/provenance state back to flex-auth. | +| Audit logging can become noisy and expensive. | Store compact decision envelopes by default; sample allows; always store denies, redactions, exports, and emergency actions. | + +## Recommended flex-auth Shape + +The first useful version of flex-auth should be a registry and adapter layer: + +```text +Resource Registry + knowledge-base / repo / document / section / context-package / workflow + +Subject Registry + OIDC subject / service account / group / team / role / tenant + +Policy Registry + action vocabulary / trust zones / labels / role mappings / assurance rules + +Relationship Store + subject --relation--> resource + resource --parent--> resource + group --member--> subject + +Decision API + check(subject, action, resource, context) -> allow/deny/redact + reason + batch_check(...) + list_allowed(subject, action, resource_type, context) + explain(decision_id) + +Audit Log + durable decisions, policy version, token hash, subject, action, resource +``` + +Recommended MVP backend: evaluate Topaz first because it already combines a +local directory, OPA/Rego policy evaluation, relation modeling, and local +deployment. Keep the flex-auth API backend-neutral so OpenFGA or SpiceDB can +take over graph-heavy workloads and Cedar can become a typed-policy option. + +## Markitect Integration Contract + +Markitect should integrate with flex-auth through a narrow adapter: + +```text +register_resource(resource_manifest) +check(subject, action, resource, context) +batch_check(subject, action, resources, context) +list_allowed(subject, action, resource_type, filters, context) +explain(decision_id) +record_decision(decision) +``` + +For Markitect resources, the canonical resource hierarchy should start as: + +```text +knowledge_base + -> repository + -> path/document + -> heading/section/span + -> context_package + -> workflow_artifact/export +``` + +Markitect frontmatter remains useful: + +```yaml +--- +policy: + labels: [internal] + trust_zone: internal + owner: team:platform-architecture + resource_id: document:architecture/adr-001 +--- +``` + +flex-auth should turn these into registered resource metadata and relationship +facts, not require Markitect to administer enterprise rules. + +## Follow-Up Work + +1. Register the `flex-auth` repo under the NetKingdom domain. +2. Define a flex-auth resource/action/decision API. +3. Pick the MVP backend path: Topaz first, or OpenFGA plus OPA. +4. Add a Markitect `FlexAuthPolicyAdapter` in `MKTT-WP-0014`. +5. Define a resource manifest that Markitect knowledge bases can publish. +6. Add examples for Keycloak/key-cape and Entra deployments. + +## Sources + +- Keycloak Authorization Services: + https://www.keycloak.org/docs/latest/authorization_services/index.html +- Keycloak policy enforcer: + https://www.keycloak.org/securing-apps/policy-enforcer +- Microsoft Entra authorization in resources: + https://learn.microsoft.com/en-us/entra/architecture/authorize-applications-resources-workloads +- Microsoft Entra group claims and app roles: + https://learn.microsoft.com/en-us/security/zero-trust/develop/configure-tokens-group-claims-app-roles +- OpenFGA concepts: + https://openfga.dev/docs/concepts +- SpiceDB schema and consistency: + https://authzed.com/docs/spicedb/concepts/schema + https://authzed.com/docs/spicedb/concepts/consistency +- Ory Keto: + https://github.com/ory/keto +- Permify modeling: + https://docs.permify.co/getting-started/modeling +- Topaz directory: + https://www.topaz.sh/docs/directory +- OPAL: + https://docs.opal.ac/ +- OPA policy language: + https://www.openpolicyagent.org/docs/policy-language +- Cedar: + https://docs.cedarpolicy.com/ +- Cerbos resource policies: + https://docs.cerbos.dev/cerbos/latest/policies/resource_policies.html +- Apache Casbin: + https://casbin.apache.org/ +- Oso: + https://docs.oso.dev/node/getting-started.html +- Local canon: + `/home/worsch/the-custodian/canon/standards/iam-profile_v0.1.md`