coulomb/flex-auth
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Established INTENT.md

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-04 17:52:29 +02:00
parent 3a5d71869e
commit 33579fd235
3 changed files with 441 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
INTENT.md Normal file
View File

@@ -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.

8
README.md
View File

@@ -1,3 +1,7 @@
# repo-seed
# flex-auth
A git repository template to bootstrap coulomb projects from.
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/).

260
docs/flex-auth-authorization-registry-research.md Normal file
View File

@@ -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`