flex-auth/docs/directory-group-resolver-adapters.md

Directory Group Resolver Adapters

Status: implemented for FLEX-WP-0004 P4.5.

Role

Directory resolvers enrich flex-auth subjects with group and role evidence from external identity systems. They do not decide access by themselves. They feed the standalone, relationship, rule, Topaz, or Keycloak decision paths with fresh subject metadata and provenance.

Resolver Sources

Implemented resolver boundaries:

• Microsoft Graph group overage (GraphResolver)
• SCIM provisioning (SCIMResolver)
• LDAP/Active Directory (LDAPResolver)
• Keycloak admin API (KeycloakResolver)

Each resolver returns ResolveResult with normalized groups, roles, freshness, overage, and metadata.

Freshness

Every result carries:

• source
• retrieval time
• max age
• expiry time
• stale flag

Decision adapters can use this metadata to deny stale directory evidence or to include freshness diagnostics in the decision envelope.

Overage

Graph tokens can omit groups and instead emit overage indicators such as _claim_names.groups or hasgroups=true. The Graph resolver records that condition in OverageMetadata so downstream policy can distinguish "no groups" from "groups omitted, lookup required".

CARING Provenance

Each GroupGrant and RoleGrant identifies:

• source provider
• originating claim name
• organization relation
• subject type
• optional CARING descriptor

This makes it possible to explain that a canonical role or group came from Graph, SCIM, LDAP/AD, or Keycloak rather than from an opaque token claim. The source remains inspectable in CARING conformance reviews.

Subject Enrichment

MergeResults deduplicates groups and roles across providers while preserving freshness, overage, and descriptors. ApplyToSubject returns a subject with resolved groups/roles and directory metadata attached.

The enriched subject can then flow through any flex-auth decision path without changing protected-system request or decision contracts.