Skip to main content

SCIM Provisioning Contracts

Status​

Contract Designed; Runtime Followed In OP-034R

  • Client response references: SCIM 2.0 is a Phase 1 requirement for user/group lifecycle provisioning, deprovisioning, tenant role mapping, and IdP integration.
  • ADR references: docs/adr/ADR-0011-scim-provisioning-contracts.md.
  • Task board references: OP-034.

Problem Statement​

OneProtect needed deterministic tenant access lifecycle controls before runtime SCIM work. OP-034R now implements the first runtime path while preserving this contract. Stale user/group state can leave tenant access active after a provider disables or deletes a user, so fail-closed behavior remains the key guardrail.

Architectural Intent​

SCIM connections are tenant-scoped. Provider users and groups are mapped into OneProtect users, groups, and roles through explicit role mappings. Privileged roles require explicit group mappings. Deprovisioning fails closed, removes effective tenant access, and creates audit evidence.

What Was Implemented​

  • ADR-0011 accepted the SCIM provisioning and role mapping model.
  • Architecture documentation defines connection, user, group, membership, role-mapping, deprovisioning, conflict, audit, and redaction behavior.
  • OpenAPI now marks SCIM admin/status/provisioning endpoints as implemented runtime.
  • AsyncAPI and JSON Schema define identity lifecycle events.
  • Contract validation covers the new event payloads.

Components Involved​

  • OpenAPI: specs/openapi.yaml
  • AsyncAPI: specs/asyncapi.yaml
  • Event schemas: specs/events/identity.*.v1.schema.json
  • Architecture docs: docs/architecture/scim-provisioning-contracts.md
  • ADRs: docs/adr/ADR-0011-scim-provisioning-contracts.md

APIs / Events / Schemas​

  • API: GET /api/v1/scim/connections
  • API: POST /api/v1/scim/connections
  • API: GET /api/v1/scim/connections/{connection_id}
  • API: PATCH /api/v1/scim/connections/{connection_id}
  • API: GET /api/v1/scim/connections/{connection_id}/role-mappings
  • API: PUT /api/v1/scim/connections/{connection_id}/role-mappings
  • API: GET /api/v1/scim/connections/{connection_id}/status
  • API: GET /api/v1/scim/provisioned-users
  • Event: identity.scim_connection.configured
  • Event: identity.scim_role_mapping.changed
  • Event: identity.user.provisioned
  • Event: identity.user.updated
  • Event: identity.user.deprovisioned
  • Event: identity.group.provisioned
  • Event: identity.group_membership.changed
  • Event: identity.provisioning.failed

Deployment Notes​

No deployment change. Provider adapters, standards-shaped /scim/v2 compatibility aliases, real secret provisioning, and runtime session/token revocation are future implementation work.

Security / Tenant Isolation​

Every SCIM connection, user, group, role mapping, event, and future persistence record is tenant-scoped. Bearer tokens and raw provider payloads are never returned, emitted, or exposed in auditor-safe views. Provider identifiers are not globally trusted without tenant and connection scope.

Validation Steps​

UI Validation​

The OP-034R runtime adds a read-only Settings page SCIM status panel. Writable SCIM administration remains API-only.

API Validation​

make validate-contracts

Smoke Validation​

make validate-contracts

Known Limitations​

  • Entra ID, Okta, and generic SCIM adapters are not implemented.
  • Standards-shaped /scim/v2 aliases are not implemented.
  • Session/token revocation runtime is not implemented.
  • Writable UI for SCIM administration is not implemented.
  • Auditor export/redaction policy is now contract-designed in ADR-0014; runtime export/redaction remains future work.

Follow-Up Work​

  • Build Entra ID and Okta compatibility adapters.
  • Wire fail-closed deprovisioning into session/token revocation.
  • Add standards-shaped SCIM compatibility aliases if IdP testing requires them.
  • Build writable tenant admin SCIM UI after operator workflows are scoped.

Acceptance Criteria Mapping​

Acceptance criterionEvidence
User/group provisioning contract is acceptedADR-0011, docs/architecture/scim-provisioning-contracts.md
Tenant role mapping is deterministicspecs/openapi.yaml, identity.scim_role_mapping.changed
Deprovisioning is fail-closed and auditedidentity.user.deprovisioned, identity.provisioning.failed
Entra ID/Okta compatibility expectations are documentedADR-0011 and architecture contract