markitect-tool/workplans/MKTT-WP-0014-enterprise-iam-access-control-integration.md

---
id: MKTT-WP-0014
type: workplan
title: "Enterprise IAM Access-Control Integration"
domain: markitect
status: done
owner: markitect-tool
topic_slug: markitect
planning_priority: complete
planning_order: 82
depends_on_workplans:
  - MKTT-WP-0009
related_workplans:
  - MKTT-WP-0006
  - MKTT-WP-0007
  - MKTT-WP-0008
  - MKTT-WP-0011
  - MKTT-WP-0013
created: "2026-05-04"
updated: "2026-05-04"
state_hub_workstream_id: "86c22ccc-5f5a-4650-8495-76fe6c08e411"
---

# MKTT-WP-0014: Enterprise IAM Access-Control Integration

## Purpose

Turn the local access-control gateway into an enterprise-ready integration
surface without making Markitect an identity provider or hard-coding one
directory vendor.

Markitect should act as the policy enforcement point for Markdown knowledge
results. NetKingdom/key-cape-compatible SSO should supply identity claims.
External policy engines and enterprise directories should attach through
provider-neutral adapters.

## Implementation Summary

Implemented the Markitect-side enterprise integration layer without importing
central authorization administration into this repo:

- `NetKingdomIdentityClaimsAdapter` for deterministic IAM-profile claim
  validation and `EnterpriseIdentity` normalization.
- `EnterprisePolicyMap` and `LocalEnterprisePolicyMapper` for mapping groups,
  roles, and scopes into `PolicySubject` labels, trust zones, and actions.
- `StaticDirectoryGroupResolver` for local group freshness/overage fixtures.
- `FlexAuthResourceManifest` for Markitect resource registration manifests.
- `LocalDecisionLogStore` for JSONL development/test decision logs.
- `mkt policy subject` and `mkt policy resource-manifest`.
- Examples for claims, policy maps, flex-auth resource manifests, external PDP
  request shapes, and policy-aware workflows.
- Documentation updates for access-control, enterprise IAM, and workflow
  permission declarations.

## Background

`MKTT-WP-0009` implemented local labels, trust zones, path rules, query/search
filtering, explainable decisions, and relationship/rule policy adapter
boundaries. The enterprise follow-up research showed a clear canonical shape:

- OIDC/SAML for authentication and signed identity assertions.
- SCIM/LDAP/Graph/Keycloak admin APIs for directory and group information.
- PEP/PDP/PIP/PAP separation for authorization architecture.
- RBAC/ABAC/ReBAC policy models through mappable policy decision points.
- NetKingdom IAM profile as the local identity contract, with key-cape as the
  preferred lightweight/bootstrap path.

Initial provider-neutral interfaces now exist in
`markitect_tool.policy.adapters`:

- `EnterpriseIdentity`
- `IdentityClaimsAdapter`
- `DirectoryGroupResolver`
- `EnterprisePolicyMapper`
- `DecisionLogStore`

Documentation:

- `docs/enterprise-access-control-integration.md`
- sibling `flex-auth/docs/flex-auth-authorization-registry-research.md`

## Decision

Implement concrete enterprise integration as an optional extension track. Core
Markitect should keep accepting normalized `PolicySubject` and `PolicyObject`
models, while enterprise adapters handle token verification, group freshness,
claim mapping, durable decision logs, and external PDP calls.

Boundary refinement: central enterprise authorization administration should
live in a separate `flex-auth` repo/service under the NetKingdom authorization
umbrella. Markitect-side WP-0014 work should implement the narrow integration
contract: resource registration, policy requests, decision envelopes, local
fixtures, diagnostics, and adapters. It should not grow into the central
resource registry, policy administration UI/API, enterprise directory sync, or
global audit store.

Do not map raw AD/LDAP/Entra group names directly to Markitect privileges.
Always map:

```text
directory groups -> canonical roles/scopes/trust labels -> PolicySubject
```

## P14.1 - Define flex-auth resource and policy contract

```task
id: MKTT-WP-0014-T001
status: done
priority: high
state_hub_task_id: "1894c50f-95c3-4e1a-bd4f-388f7624ebd7"
```

Define the Markitect-facing contract for flex-auth integration:

- resource registration manifests
- action vocabulary
- label and trust-zone metadata
- policy request and decision envelopes
- subject mapping expectations
- local fixtures for development

Do not define the central enterprise rule administration schema inside
Markitect. That belongs in flex-auth.

Output: schema, examples, diagnostics, and tests.

## P14.2 - Implement NetKingdom/key-cape identity claims adapter

```task
id: MKTT-WP-0014-T002
status: done
priority: high
state_hub_task_id: "8a177375-09b3-4898-a053-7601f82fcb29"
```

Implement an optional `IdentityClaimsAdapter` for
NetKingdom/key-cape-compatible claims.

It must validate:

- issuer
- audience
- expiry and issued-at
- signature verification provenance for trusted claims or explicit local JWT
  fixtures; live JWKS verification remains provider-adapter/flex-auth scope
- authorized party/client id where required
- MFA/assurance claims for privileged actions

Output: adapter, fixtures, negative tests, and clear diagnostics.

## P14.3 - Implement enterprise subject mapper

```task
id: MKTT-WP-0014-T003
status: done
priority: high
state_hub_task_id: "6861d4bc-1bb8-440d-bb9e-33e20c7feb55"
```

Implement `EnterprisePolicyMapper` over the policy map schema. It should map
verified identity claims and resolved groups into gateway-ready
`PolicySubject` objects.

Output: mapper/adapter examples and tests for roles, scopes, groups, trust
zones, tenancy, and emergency access. Central group-to-resource policy
administration remains flex-auth scope.

## P14.4 - Add directory group resolution boundary

```task
id: MKTT-WP-0014-T004
status: done
priority: medium
state_hub_task_id: "56d6bad6-d706-47b3-b321-1f0e870ecc0d"
```

Implement a provider-neutral group-resolution layer for claims that are stale,
partial, or too large for tokens. Start with a fake/test resolver and specify
adapter hooks for SCIM, Microsoft Graph, LDAP, and Keycloak.

Output: resolver contract, freshness metadata, overage handling, and tests.

## P14.5 - Add decision log sink and flex-auth audit adapter

```task
id: MKTT-WP-0014-T005
status: done
priority: high
state_hub_task_id: "f212662c-4ffc-4cac-ace2-a43777f4960c"
```

Implement the Markitect-side `DecisionLogStore` sink for policy decisions from
query, search, context packages, workflows, exports, and assisted prompt
assembly. The durable enterprise audit store should live in flex-auth; local
Markitect storage should remain a development/testing fallback.

Decision logs should record subject id, token hash, action, object id, policy
version, decision effect, reason, redaction status, and provenance.

Output: storage adapter, CLI inspection path, and tests.

## P14.6 - Add external PDP examples

```task
id: MKTT-WP-0014-T006
status: done
priority: medium
state_hub_task_id: "573a198f-df0b-470a-b11c-9ac839c0845e"
```

Provide reference adapters or documented examples for:

- OpenFGA/SpiceDB-style relationship checks through
  `RelationshipPolicyAdapter`
- OPA/Rego or Cedar-style rule checks through `RulePolicyAdapter`

Output: examples, adapter stubs, and policy request/decision fixtures. Full
external PDP administration belongs in flex-auth.

## P14.7 - Integrate policy identity into workflows and context packages

```task
id: MKTT-WP-0014-T007
status: done
priority: high
state_hub_task_id: "c4650304-0e2b-49c5-8569-e69907c08ccc"
```

Make workflow and future context-package execution accept explicit enterprise
identity and policy mapping configuration.

Required concepts:

- `subject_from_token`
- `policy_map`
- `required_assurance`
- `emergency_justification`
- decision-log sink

Output: workflow/context integration design, examples, and tests.

## P14.8 - Validate against NetKingdom IAM profile

```task
id: MKTT-WP-0014-T008
status: done
priority: medium
state_hub_task_id: "0486e0c2-2cb9-4902-9a09-9ec729e9e79f"
```

Build conformance tests against the local IAM profile:

- required claims
- human Authorization Code + PKCE expectations
- service account claims
- local development issuer rejection in production mode
- emergency access audit requirements

Output: test fixtures and conformance checklist.

## Exit Criteria

- A NetKingdom/key-cape-compatible OIDC identity can be validated and mapped to
  a `PolicySubject`.
- Enterprise groups, roles, scopes, trust zones, and labels are mapped through
  a versioned policy map rather than raw directory names.
- Query, search, workflow, and context-package boundaries can enforce policy
  and emit durable decision logs.
- Directory group overage and freshness are represented explicitly.
- OpenFGA/SpiceDB and OPA/Cedar-style PDP integrations can attach without
  replacing Markitect's local policy gateway.
- The implementation remains optional and does not add enterprise IAM
  dependencies to core Markdown parsing or deterministic processing.

## Notes

This workplan should be picked up before using Markitect context caches for
production agent memory in enterprise settings. It does not need to block local
research on `MKTT-WP-0008`, but it should gate production deployment of
reactivatable cross-document context packages.

Follow-up implementation now belongs primarily in the sibling `flex-auth`
repo:

- `FLEX-WP-0002` implements the standalone policy-as-code core, resource
  registry, check APIs, explanations, and local decision logs.
- `FLEX-WP-0003` implements the flex-auth service-side Markitect consumer
  integration.
- `FLEX-WP-0004` implements delegated PDP and directory adapters.

Markitect should add a live `FlexAuthPolicyAdapter` only after flex-auth has a
stable check/batch_check/resource-registration API. Until then, Markitect's
side is intentionally limited to local deterministic fixtures, resource
manifests, request/decision contracts, CLI inspection, workflow declarations,
and enforcement boundaries.