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	todo	flex-auth	flex-auth	P2	40	FLEX-WP-0002	FLEX-WP-0003	2026-05-04	2026-05-15	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.

P4.1 - Implement Topaz adapter

id: FLEX-WP-0004-T001
status: todo
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.

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: todo
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

P4.3 - Add rule PDP adapter boundary

id: FLEX-WP-0004-T003
status: todo
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

P4.4 - Add Keycloak Authorization Services adapter path

id: FLEX-WP-0004-T004
status: todo
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: todo
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.

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.