generated from coulomb/repo-seed
79 lines
2.3 KiB
Markdown
79 lines
2.3 KiB
Markdown
# 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.
|