flex-auth/workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md

id, type, title, domain, status, owner, topic_slug, planning_priority, planning_order, depends_on_workplans, related_workplans, created, updated, state_hub_workstream_id

id	type	title	domain	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	related_workplans	created	updated	state_hub_workstream_id
FLEX-WP-0004	workplan	Delegated PDP and Directory Adapters	netkingdom	active	flex-auth	flex-auth	P2	40	FLEX-WP-0002	FLEX-WP-0003	2026-05-04	2026-05-17	99a82976-d376-42b0-89cc-c44e01c0bec6

FLEX-WP-0004: Delegated PDP and Directory Adapters

Purpose

Let flex-auth coordinate established authorization and directory systems while remaining the stable control plane for protected systems.

The standalone core must work first. This workplan adds delegated backends and provider examples after flex-auth's own request, decision, registry, and audit vocabulary are stable.

Scope change (2026-05-15). Per ADR-003 and the pre-implementation assessment, the Topaz evaluation moved to FLEX-WP-0005 T04 so its output can shape the standalone core. This workplan now implements the Topaz adapter against that mapping; the standalone evaluator already speaks Rego, so adapter work focuses on directory delegation, wire protocol, and consistency metadata rather than re-deciding fit.

CARING note (2026-05-17). Delegated adapters must preserve the CARING decision envelope fields defined by the standalone core. Backend native semantics may differ, but protected systems should still see the same descriptor, exposure, restriction, conformance, and audit shape.

P4.1 - Implement Topaz adapter

id: FLEX-WP-0004-T001
status: done
priority: high
state_hub_task_id: "9046418c-2b78-42c6-8bfa-76d6ed0050dd"

Implement the Topaz adapter behind flex-auth's stable PDP and directory contracts. Consumes docs/topaz-mapping-spike.md produced in FLEX-WP-0005 T04.

Scope:

• Wire-protocol selection (gRPC vs HTTP vs embedded library) with rationale recorded.
• Directory delegation: flex-auth registry writes flow into Topaz directory objects/relations; reads can be served from either side with documented consistency semantics.
• Policy delegation: a flex-auth package (Rego-in-Markdown) is decomposed and pushed to Topaz unchanged; decisions returned carry the same envelope shape as standalone evaluation.
• Failure modes: Topaz unavailable, stale directory, partial result — each produces a decision envelope that the standalone code path could also have produced.
• CARING preservation: delegated decisions include the same CARING descriptor, restriction precedence, exposure mode, conformance findings, and exposure-event hooks as standalone decisions.

Output: adapter package under internal/adapters/topaz/, end-to-end integration test using the examples/topaz/ docker-compose from the spike, and an operations note covering startup, health checks, and fail-closed defaults.

P4.2 - Add relationship PDP adapter boundary

id: FLEX-WP-0004-T002
status: done
priority: high
state_hub_task_id: "b77a0b70-b492-46ba-badf-8c2eebe006aa"

Define and implement adapter contracts for OpenFGA and SpiceDB-style checks:

• tuple/resource mapping
• inherited access
• batch/list operations
• consistency metadata
• error and stale-data diagnostics
• preservation of CARING scope, plane, capability, exposure, and derived capability metadata across tuple-oriented backends

P4.3 - Add rule PDP adapter boundary

id: FLEX-WP-0004-T003
status: done
priority: high
state_hub_task_id: "4e4e5e45-c05a-4a31-8126-f0c7676b1e6c"

Define and implement adapter contracts for OPA/Rego and Cedar-style policies:

• principal/action/resource/context mapping
• policy package versioning
• test fixtures
• obligations and diagnostics
• CARING frontmatter and conformance findings when backend-native policy languages cannot represent every descriptor dimension directly

P4.4 - Add Keycloak Authorization Services adapter path

id: FLEX-WP-0004-T004
status: done
priority: medium
state_hub_task_id: "8d3bbc28-985b-4dd7-9fb8-f9a858eb5a6b"

Document and spike Keycloak Authorization Services integration for Keycloak-centric deployments without making Keycloak the only resource-policy source of truth.

P4.5 - Add Entra/Graph and SCIM group resolver adapters

id: FLEX-WP-0004-T005
status: done
priority: medium
state_hub_task_id: "4fc3fb91-8763-453e-8e54-36178cb11efd"

Implement directory group resolver patterns for:

• Microsoft Graph group overage
• SCIM provisioning
• LDAP/AD
• Keycloak admin API

Each resolver must expose freshness, source, and overage metadata. Resolvers must also identify which organization relation, subject type, group, or role claim was derived from the external directory so CARING descriptor provenance remains inspectable.

P4.6 - Add delegated-mode operations docs

id: FLEX-WP-0004-T006
status: todo
priority: medium
state_hub_task_id: "491260f9-b4d7-46fe-8220-d358597db33a"

Document deployment, failure modes, caching, fail-closed/fail-open policy, consistency, and audit behavior for delegated backends.

Exit Criteria

• flex-auth can delegate decisions to at least one external PDP in a controlled adapter shape.
• Directory group freshness and overage are explicit.
• Backend changes do not alter the protected-system-facing flex-auth API.
• Topaz/OpenFGA/OPA/Cedar/Keycloak/Entra tradeoffs are documented with practical guidance.
• Delegated backends preserve CARING descriptor and conformance metadata instead of leaking backend-native role semantics into protected systems.