Established INTENT.md

2026-05-04 17:52:29 +02:00
parent 3a5d71869e
commit 33579fd235
3 changed files with 441 additions and 2 deletions
--- a/docs/flex-auth-authorization-registry-research.md
+++ 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`