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