generated from coulomb/repo-seed
352 lines
13 KiB
Markdown
352 lines
13 KiB
Markdown
# flex-auth Product Requirements Document
|
|
|
|
Date: 2026-05-04
|
|
Status: Draft for alignment
|
|
|
|
## 1. Definition
|
|
|
|
flex-auth is a policy-as-code authorization registry and control plane for
|
|
organizations that need to grow from simple application roles into
|
|
enterprise-grade, inspectable authorization.
|
|
|
|
The product is expected to define and operate the authorization layer between
|
|
verified identity claims and protected systems. It should let resource owners
|
|
register protected systems and resources, publish reviewable policy packages,
|
|
evaluate authorization requests, explain decisions, and preserve decision
|
|
records for diagnostics and audit.
|
|
|
|
This PRD defines what flex-auth must achieve within this repository's current
|
|
boundary. It intentionally avoids prescribing internal architecture or
|
|
implementation details beyond the product-level constraints already established
|
|
by the repo.
|
|
|
|
## 2. Context
|
|
|
|
NetKingdom-aligned systems separate identity from authorization:
|
|
|
|
```text
|
|
key-cape / NetKingdom SSO
|
|
-> verified OIDC/SAML identity claims
|
|
-> flex-auth policy-as-code and authorization registry
|
|
-> protected systems and knowledge tools
|
|
```
|
|
|
|
Identity providers issue tokens, manage login, and provide coarse claims.
|
|
Protected systems enforce allow, deny, redact, and audit outcomes at their own
|
|
runtime boundaries. flex-auth exists between those responsibilities as the
|
|
stable authorization product surface.
|
|
|
|
The first concrete consumer is Markitect, which needs central authorization for
|
|
knowledge bases, repositories, documents, sections, context packages, workflow
|
|
artifacts, and exports. The product must use that consumer to validate real
|
|
resource and decision needs without becoming Markitect-specific.
|
|
|
|
## 3. Product Intent
|
|
|
|
flex-auth should provide a path that starts small and grows cleanly:
|
|
|
|
- Local developers and small teams can run flex-auth in standalone mode.
|
|
- Policy authors can version, review, validate, test, publish, and activate
|
|
policy packages.
|
|
- Protected systems can register resources and ask stable authorization
|
|
questions.
|
|
- Operators can inspect and export decision records with enough provenance to
|
|
diagnose policy behavior.
|
|
- Enterprise deployments can later delegate relationship, rule, or directory
|
|
concerns to established backends without changing protected-system contracts.
|
|
|
|
The product outcome is not merely a collection of adapters. The core value is a
|
|
canonical, backend-neutral authorization model that keeps ownership clear as
|
|
policy complexity grows.
|
|
|
|
## 4. Users and Stakeholders
|
|
|
|
### Primary Users
|
|
|
|
- Protected-system developers integrating authorization checks.
|
|
- Policy authors defining resource-specific access behavior.
|
|
- Platform engineers operating local or shared flex-auth instances.
|
|
- Product and architecture owners aligning identity, authorization, and
|
|
protected-system boundaries.
|
|
|
|
### Secondary Users
|
|
|
|
- Security reviewers inspecting policy behavior and audit records.
|
|
- Support or operations staff diagnosing denied, redacted, stale, partial, or
|
|
uncertain decisions.
|
|
- Future backend integrators connecting Topaz, OpenFGA, SpiceDB, OPA, Cedar,
|
|
Keycloak Authorization Services, Entra, Graph, SCIM, LDAP, or related
|
|
systems.
|
|
|
|
## 5. In Scope
|
|
|
|
### Standalone Authorization Core
|
|
|
|
- Protected-system manifests.
|
|
- Resource manifests and resource hierarchies.
|
|
- Subject, group, team, tenant, role, service-account, and emergency-principal
|
|
representations needed for authorization.
|
|
- Relationship fact manifests.
|
|
- Canonical action vocabularies.
|
|
- Check request and decision envelope definitions.
|
|
- Deterministic `check` and `batch_check` behavior.
|
|
- `list_allowed` for discoverable allowed resources.
|
|
- `explain` for decision diagnostics.
|
|
- Local registry storage suitable for development, tests, and small
|
|
deployments.
|
|
|
|
### Policy-as-Code Lifecycle
|
|
|
|
- Policy package metadata, validation, fixtures, tests, versions, and
|
|
activation state.
|
|
- Local policy package testing before activation.
|
|
- Policy decision outputs that include effect, reason, matched policy version,
|
|
matched rule, obligations, diagnostics, and provenance.
|
|
|
|
### Audit and Diagnostics
|
|
|
|
- Local decision records.
|
|
- Durable recording for denies, redactions, exports, and emergency actions.
|
|
- Compact decision envelopes suitable for later audit export.
|
|
- Clear diagnostics for stale, partial, uncertain, denied, and redacted
|
|
results.
|
|
|
|
### Developer and Operator Experience
|
|
|
|
- CLI workflows for validating manifests, loading registry data, testing
|
|
policies, checking one request, batch checking, and explaining a decision.
|
|
- A service entry point after library and CLI behavior are stable enough.
|
|
- Examples and tests for local users, groups, teams, project resources,
|
|
inherited relationships, and policy fixtures.
|
|
|
|
### First Consumer: Markitect
|
|
|
|
- Markitect resource namespace and hierarchy.
|
|
- Import of Markitect resource manifests into the flex-auth registry.
|
|
- Markitect action vocabulary: `read`, `query`, `search`, `package`,
|
|
`activate_context`, `export`, `workflow_run`, and `admin`.
|
|
- Markitect-compatible decision fixtures and contract tests.
|
|
- Integration documentation for publish, check, enforce, record, and explain
|
|
flows.
|
|
|
|
### Future Delegated Mode
|
|
|
|
- Adapter boundaries for relationship PDPs such as OpenFGA and SpiceDB.
|
|
- Adapter boundaries for rule PDPs such as OPA/Rego and Cedar.
|
|
- Topaz evaluation as the first delegated-backend candidate.
|
|
- Keycloak Authorization Services adapter path for Keycloak-centric
|
|
deployments.
|
|
- Directory and group resolver patterns for Entra/Graph, SCIM, LDAP, and
|
|
Keycloak APIs.
|
|
- Operations documentation for caching, consistency, failure modes, and
|
|
fail-open/fail-closed behavior.
|
|
|
|
## 6. Out of Scope
|
|
|
|
- Acting as an identity provider.
|
|
- Replacing key-cape, NetKingdom SSO, Keycloak, Entra, or other identity
|
|
providers.
|
|
- Owning login, MFA, PKCE, token issuance, token lifecycle, OIDC discovery, or
|
|
canonical IAM profile behavior.
|
|
- Making protected systems passive; they remain responsible for enforcement.
|
|
- Embedding Markitect-specific policy administration into flex-auth's generic
|
|
model.
|
|
- Treating identity-provider roles, scopes, or groups as final
|
|
resource-specific authorization by themselves.
|
|
- Forcing all deployments to use Topaz, OpenFGA, SpiceDB, OPA, Cedar,
|
|
Keycloak Authorization Services, Entra, or any other single backend.
|
|
- Providing backlog, sprint, or task execution details beyond the existing
|
|
workplans.
|
|
- Defining detailed technical architecture, database schema internals, service
|
|
framework choices, or deployment manifests in this PRD.
|
|
|
|
## 7. Functional Requirements
|
|
|
|
### FR1. Protected-System Registration
|
|
|
|
flex-auth must let a protected system declare its identity, ownership, resource
|
|
namespaces, action vocabulary, and integration metadata in a registered
|
|
manifest.
|
|
|
|
### FR2. Resource Registration
|
|
|
|
flex-auth must accept resource manifests that describe resource identity,
|
|
namespace, hierarchy, owner metadata, policy labels, trust zones, and relevant
|
|
provenance.
|
|
|
|
### FR3. Subject and Relationship Registration
|
|
|
|
flex-auth must represent authorization-relevant subjects and relationships,
|
|
including humans, service accounts, groups, teams, tenants, roles, emergency
|
|
principals, subject-resource relations, and resource-resource relations.
|
|
|
|
### FR4. Policy Package Validation
|
|
|
|
flex-auth must load policy packages with metadata, fixtures, test cases,
|
|
version information, and activation metadata, and must reject invalid packages
|
|
with useful diagnostics.
|
|
|
|
### FR5. Policy Package Testing
|
|
|
|
flex-auth must support policy fixtures and test cases so policy authors can
|
|
verify expected decisions before activation.
|
|
|
|
### FR6. Authorization Checks
|
|
|
|
flex-auth must provide `check(subject, action, resource, context)` returning a
|
|
decision envelope with effect, reason, policy version, matched rule,
|
|
obligations, diagnostics, and provenance.
|
|
|
|
### FR7. Batch Authorization Checks
|
|
|
|
flex-auth must provide `batch_check(subject, action, resources, context)` for
|
|
query/search workflows where multiple resources must be evaluated together.
|
|
|
|
### FR8. Allowed Resource Listing
|
|
|
|
flex-auth must provide `list_allowed(subject, action, resource_type, filters,
|
|
context)` for workflows that need to discover resources a subject can access.
|
|
|
|
### FR9. Decision Explanation
|
|
|
|
flex-auth must provide `explain(decision_id)` so developers, policy authors,
|
|
and operators can understand why a decision was produced.
|
|
|
|
### FR10. Decision Recording
|
|
|
|
flex-auth must record decisions with compact, durable metadata, always
|
|
including denies, redactions, exports, and emergency actions.
|
|
|
|
### FR11. Markitect Compatibility
|
|
|
|
flex-auth must represent Markitect resource manifests, resource hierarchy,
|
|
action vocabulary, and decision shapes without making Markitect the only
|
|
consumer model.
|
|
|
|
### FR12. Delegated Backend Readiness
|
|
|
|
flex-auth must preserve a stable protected-system-facing contract when
|
|
authorization evaluation is later delegated to external PDP or directory
|
|
systems.
|
|
|
|
## 8. Non-Functional Requirements
|
|
|
|
### NFR1. Implementation Independence
|
|
|
|
Product contracts must be expressed in backend-neutral vocabulary. External PDP
|
|
engines are adapters, not product definitions.
|
|
|
|
### NFR2. Explainability
|
|
|
|
Denied, redacted, stale, partial, uncertain, audit-only, and not-applicable
|
|
decisions must produce useful diagnostics.
|
|
|
|
### NFR3. Local Usefulness
|
|
|
|
Standalone mode must be useful for development, smaller deployments, and
|
|
integration tests before delegated integrations are available.
|
|
|
|
### NFR4. Reviewability
|
|
|
|
Policies must be versioned, testable, and suitable for code review.
|
|
|
|
### NFR5. Auditability
|
|
|
|
Decision records must include policy version and enough provenance to support
|
|
diagnostics and audit export.
|
|
|
|
### NFR6. Backend Portability
|
|
|
|
The product must not require protected systems to change contracts when a PDP
|
|
backend changes.
|
|
|
|
### NFR7. Operational Clarity
|
|
|
|
Failure modes, caching behavior, consistency, stale directory data, group
|
|
overage, and fail-open/fail-closed behavior must be explicit.
|
|
|
|
### NFR8. Ownership Clarity
|
|
|
|
flex-auth must preserve clear boundaries between identity ownership,
|
|
authorization ownership, and protected-system enforcement ownership.
|
|
|
|
## 9. Assumptions and Dependencies
|
|
|
|
- Identity claims come from key-cape, NetKingdom SSO, Keycloak, Entra, or
|
|
compatible identity systems.
|
|
- Protected systems are able to extract resource metadata and enforce
|
|
decisions locally.
|
|
- Markitect remains the first concrete consumer for shaping realistic resource
|
|
and workflow needs.
|
|
- Delegated backends should be introduced only after standalone request,
|
|
decision, registry, and audit vocabulary are stable.
|
|
- Directory group membership can be stale, incomplete, or oversized for tokens;
|
|
freshness and source metadata are therefore product requirements.
|
|
- This repo currently contains planning and documentation artifacts, not an
|
|
implemented service.
|
|
|
|
## 10. Success Criteria
|
|
|
|
### MVP Success
|
|
|
|
- flex-auth can run standalone for local development.
|
|
- Protected systems, resources, subjects, relationships, and policy packages
|
|
can be validated and loaded.
|
|
- `check`, `batch_check`, `list_allowed`, and `explain` are available.
|
|
- Decision envelopes are stable and include actionable diagnostics.
|
|
- Local decision logs record required high-value events.
|
|
- CLI workflows cover validation, loading, policy testing, checking, batch
|
|
checking, and explaining.
|
|
- Tests and examples cover representative local users, groups, teams,
|
|
resources, inheritance, and policy fixtures.
|
|
|
|
### First Consumer Success
|
|
|
|
- Markitect resource manifests can be imported.
|
|
- Markitect action vocabulary is represented.
|
|
- Markitect-compatible decisions are produced for allow, deny, redact, and
|
|
audit-denied cases.
|
|
- Markitect integration docs cover publish, check, enforce, record, and explain
|
|
flows.
|
|
- The integration remains generic enough for another protected system to reuse
|
|
the same flex-auth model.
|
|
|
|
### Expansion Success
|
|
|
|
- Topaz has a clear MVP recommendation or rejection.
|
|
- Relationship PDP and rule PDP adapter contracts are documented and tested at
|
|
their boundaries.
|
|
- Keycloak Authorization Services, Entra/Graph, SCIM, LDAP, and Keycloak API
|
|
resolver paths are documented with explicit freshness and failure behavior.
|
|
- Protected-system APIs remain stable as delegated mode is introduced.
|
|
|
|
## 11. Product Constraints
|
|
|
|
- flex-auth must not collapse identity and authorization into one concern.
|
|
- flex-auth must not let the first Markitect integration narrow the generic
|
|
protected-system model.
|
|
- flex-auth must keep policy behavior inspectable rather than relying on opaque
|
|
administrative toggles.
|
|
- flex-auth must treat roles, scopes, groups, tenants, claims, relationships,
|
|
and context as authorization inputs, not as automatic final decisions.
|
|
- flex-auth must be useful before enterprise infrastructure is available.
|
|
- flex-auth must make uncertainty visible instead of silently hiding stale or
|
|
partial authorization data.
|
|
|
|
## 12. Traceability
|
|
|
|
This PRD is grounded in the current repository material:
|
|
|
|
- `INTENT.md`
|
|
- `docs/flex-auth-authorization-registry-research.md`
|
|
- `docs/workplan-planning-map.md`
|
|
- `workplans/FLEX-WP-0001-repo-intent-and-architecture-baseline.md`
|
|
- `workplans/FLEX-WP-0002-standalone-policy-as-code-core.md`
|
|
- `workplans/FLEX-WP-0003-markitect-consumer-integration.md`
|
|
- `workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md`
|
|
- `.custodian-brief.md`
|
|
|
|
Downstream technical specifications, ADRs, schemas, backlog items, tests, and
|
|
implementation tasks should derive from this document without treating it as a
|
|
technical design.
|