# Keycloak Authorization Services Adapter Path

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

## Role

The Keycloak path is for deployments that already use Keycloak as the
identity provider and want to evaluate some authorization decisions
through Keycloak Authorization Services. flex-auth still remains the
source of truth for protected-system resources, CARING descriptors, and
decision envelopes.

## Mapping

flex-auth maps a check to Keycloak's UMA permission shape:

| flex-auth | Keycloak |
| --- | --- |
| protected system | resource server / audience |
| resource id | resource id |
| action | scope |
| subject | requesting party |
| context and CARING descriptor | claim token |

The adapter builds a permission as `resource_id#scope`, for example
`document:internal-note#read`.

## Resource Registration

`ResourceRegistrationsFromManifest` converts a
`ResourceManifest` into Keycloak resource registrations:

- resource id and type are preserved;
- manifest actions become scopes;
- path becomes the URI;
- labels, trust zone, owner, parent, system, and type are stored as
  resource attributes.

Keycloak can mirror these resources, but flex-auth keeps the original
manifest as the canonical record.

## Decision Wrapping

Keycloak allow/deny results are wrapped into the standard
`DecisionEnvelope`:

- `provenance.evaluator=keycloak-authz`
- `provenance.mode=delegated`
- Keycloak RPT token id and permission appear in diagnostics
- CARING descriptor and conformance findings are preserved

Backend-native Keycloak policy names do not replace CARING canonical
roles in protected-system responses.

## Failure Behavior

The adapter fails closed for:

- Keycloak unavailable: `keycloak_unavailable`
- stale policy state: `keycloak_policy_stale`
- partial result: `keycloak_partial_result`
- untranslatable request: `keycloak_request_incomplete`

Each failure returns a deny envelope with `diagnostics.keycloak_failure`
and a CARING conformance finding.

## Boundaries

This path intentionally does not make Keycloak the only policy source of
truth. flex-auth continues to own:

- resource manifests from protected systems;
- CARING descriptors and conformance findings;
- audit and explanation envelope shape;
- adapter-neutral request/decision APIs.

Keycloak is a delegated evaluator and resource mirror for Keycloak-heavy
installations, not the canonical model for the whole product.