Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 113 additions & 0 deletions docs/scim-provisioning.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# SCIM user and group provisioning

SCIM 2.0 provisions non-administrator gateway accounts and organisation teams. The
API is disabled by default. Unset, empty, `false`, `0`, `off` and `no` values for
`SCIM_ENABLED` return 404 for every `/scim/v2/*` route. An invalid value also disables
the API and emits one warning without the value. Existing account creation is unchanged.

## Configuration and authentication

Set `SCIM_ENABLED=true` only after applying the SCIM storage migration and configuring
the account and tenant authorities. `AUTH_STORAGE_BACKEND` and
`INTELLIGENCE_STORAGE_BACKEND` must both be `d1`, and
`CONFIG_REVISION_SYNC_ENABLED=true` must be enabled for the Worker and Container.
Security revisions expire within `CONFIG_SECURITY_TTL_SECONDS` (default and maximum:
five seconds); an unavailable or stale security copy denies generation.

Configure token references, never token values:

```json
{"tenants":{"org:example":{"token_ref":"SCIM_PROVISIONING_EXAMPLE"}}}
```

This is the value of `SCIM_TRUST_CONFIG_JSON`. The named environment variable or
Worker secret binding supplies the provisioning token privately. Supply each reference
to the Container through the deployment's reviewed secret-binding configuration.
An empty trust config uses `{}` and authorises nobody. Each tenant needs a distinct
token. Missing, unknown, ambiguous or invalid trust entries return a SCIM 401 error.
The server compares SHA-256 digests in constant time, fixes the organisation from the
matched reference, and ignores caller-supplied organisation headers. Provisioning
tokens and account credentials are never returned or logged.

Send the token in `Authorization: Bearer <provisioning-token>`. Browser sessions do
not authorise this API. It is exempt from dashboard CSRF checks and accepts
`application/scim+json` or `application/json` request bodies. Responses use
`application/scim+json` and `Cache-Control: no-store`.

## Endpoints and supported attributes

The discovery endpoints are `/scim/v2/ServiceProviderConfig`, `/scim/v2/Schemas`
and `/scim/v2/ResourceTypes`; schema and resource-type entries can also be read by ID.
`Users` and `Groups` support list, get, POST, PUT, PATCH and DELETE. PATCH uses the
SCIM PatchOp schema and `Operations` array. Unsupported schemas, attributes, paths,
operations and list parameters return a SCIM 400 error.

Users accept `userName`, `externalId`, `active`, `displayName`, `name` and `emails`.
Names support `formatted`, `familyName`, `givenName`, `middleName`, `honorificPrefix`
and `honorificSuffix`. Emails support `value`, `type`, `display` and `primary`, with
at most one primary entry. `userName` is immutable and globally unique among gateway
accounts. IDs and external identities remain stable across deactivation.
Administrator roles, permission escalation and environment-managed administrator
names cannot be provisioned. New accounts receive only the default `chat` and
`models` scopes. Their generated key is discarded; an authorised operator must issue
a new key through the existing key-rotation flow when key access is needed.

Groups accept `displayName`, `externalId` and `members` (`value`, optional `display`
and `$ref`). Member values are SCIM user IDs in the same organisation. Membership
must also pass the tenant authority. Teams and members cannot grant administrator
roles. Group writes require an atomic team authority; missing authorities return 503.

PATCH supports `add`, `replace` and `remove` for mutable user attributes and group
attributes. A missing path with an object value applies its named mutable attributes.
Adding a name merges its subattributes; adding emails appends entries; adding members
merges by member ID. Removing `active` deactivates the account. A member can be removed
with `members[value eq "<id>"]`. Other selectors and nested PATCH paths are unsupported.
PUT replaces the supported attributes; omitted user `active` defaults to true and
omitted group members defaults to an empty list.

For example, create a user using the User schema:

```json
{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"userName":"alice","externalId":"directory-subject-1","active":true}
```

POST returns 201 with `Location` and `ETag`. Repeating an external ID in the same
organisation and resource type returns its existing resource with 200, including
after deactivation. A conflicting username returns 409 `uniqueness`.

Each resource's `meta.version` is its weak ETag. Send the current ETag in `If-Match`
on PUT, PATCH or DELETE. A stale ETag returns 412; omitting the header still uses
an atomic stored-version check, so concurrent writers cannot silently overwrite.
`If-Match: *` requires the resource to exist.

## Limits, deactivation and retention

List responses use `startIndex` (one-based, default 1) and `count` (default 100,
maximum 100; zero returns no rows). The only filter expressions are
`userName eq "..."`, `externalId eq "..."` and `displayName eq "..."`. Other expressions
return 400 `invalidFilter`. Sorting, projections, bulk operations and password changes
are unsupported. Requests are limited to 128 KiB, 100 PATCH operations, 100 email
entries and 1,000 group members. Page positions are not snapshot cursors.

Setting `active=false` or deleting a user deactivates it. The account, external identity
and historical usage remain. The server rotates and discards its key, marks it revoked,
and advances the existing key-control and model-grant security revisions in the same
transaction. Dashboard sessions fail persisted revocation and key-prefix checks.
Reactivation clears the revocation marker without restoring the old key or sessions.
DELETE returns 204. Deleting a group removes its current memberships and deactivates
its mapped team while retaining the group identity and audit history.

SCIM storage contains directory identity attributes, external mappings, token digests,
membership state and content-free operation audits. It does not record prompts,
generated responses or provisioning bearer values. These records have no automatic
retention expiry; deactivation does not purge them. Operators must account for that
retention when enrolling a directory. SCIM has no provider calls, inference cost,
payment processing or automatic billing; D1 operations incur the deployment's normal
storage costs. Responses do not assert directory-provider certification.

Errors use `urn:ietf:params:scim:api:messages:2.0:Error` with string `status`, `scimType`
and a bounded detail. With SCIM enabled, missing tables, account columns, security
revision storage, atomic collaborators or durable storage return JSON 503 before
account changes. Storage outages never fall back to local account writes or retry
uncertain mutations. The Worker forwards the public path, body, bearer and `If-Match`
to the Container; the private SCIM domain only accepts its fixed internal POST target.
37 changes: 37 additions & 0 deletions intelligence-migrations/0036_scim_provisioning.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
-- Tenant-scoped external identities, retained account mappings and SCIM revisions.
CREATE TABLE IF NOT EXISTS scim_resources (
org_id TEXT NOT NULL,
kind TEXT NOT NULL CHECK(kind IN ('Users', 'Groups')),
id TEXT NOT NULL,
external_id TEXT,
user_name TEXT,
display_name TEXT,
deactivated INTEGER NOT NULL DEFAULT 0 CHECK(deactivated IN (0, 1)),
revision INTEGER NOT NULL CONSTRAINT scim_cas_confirmed CHECK(revision BETWEEN 1 AND 9007199254740991),
document TEXT NOT NULL,
PRIMARY KEY(org_id, kind, id),
UNIQUE(org_id, kind, external_id),
UNIQUE(org_id, kind, user_name)
);
CREATE UNIQUE INDEX IF NOT EXISTS idx_scim_account_identity ON scim_resources(user_name) WHERE kind='Users';
CREATE TABLE IF NOT EXISTS scim_group_members (
org_id TEXT NOT NULL,
group_id TEXT NOT NULL,
user_id TEXT NOT NULL,
PRIMARY KEY(org_id, group_id, user_id)
);
CREATE TABLE IF NOT EXISTS scim_token_digests (
org_id TEXT PRIMARY KEY,
digest_sha256 TEXT NOT NULL CHECK(length(digest_sha256)=64),
updated_at TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS scim_audit (
sequence INTEGER PRIMARY KEY AUTOINCREMENT,
org_id TEXT NOT NULL,
kind TEXT NOT NULL,
resource_id TEXT NOT NULL,
revision INTEGER NOT NULL,
operation TEXT NOT NULL,
at TEXT NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_scim_audit_scope ON scim_audit(org_id, sequence);
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"lint": "ruff check . --select E9,F63,F7,F82",
"typecheck": "mypy --ignore-missing-imports --follow-imports=skip --disable-error-code import-untyped --disable-error-code var-annotated --disable-error-code arg-type --disable-error-code assignment --disable-error-code operator app.py routes services providers streaming",
"test": "python -m pytest -q",
"test:worker": "node --test tests/test_cloudflare_worker.mjs tests/test_cascades_worker.mjs tests/test_cascades_dashboard.mjs tests/test_image_quality_worker.mjs tests/test_secret_scan_worker.mjs tests/test_secret_firewall_worker.mjs tests/test_secret_firewall_coverage_worker.mjs tests/test_roleplay_compaction_budget_worker.mjs tests/test_roleplay_compaction_model_worker.mjs tests/test_roleplay_stream_validation_worker.mjs tests/test_aihubmix_worker.mjs tests/test_gpt_image_moderation_worker.mjs tests/test_dashboard_scripts.mjs tests/test_operations_dashboard.mjs tests/test_opencode_reasoning_worker.mjs tests/test_opencode_thinking_worker.mjs tests/test_nanogpt_reasoning_worker.mjs tests/test_nanogpt_speed_routing_worker.mjs tests/test_sse_heartbeat_worker.mjs tests/test_roleplay_worker.mjs tests/test_roleplay_config_worker.mjs tests/test_roleplay_glm_failover_worker.mjs tests/test_roleplay_intelligence_worker.mjs tests/test_roleplay_memory_worker.mjs tests/test_roleplay_compatibility_worker.mjs tests/test_roleplay_history_reconciliation_worker.mjs tests/test_roleplay_output_contract_analysis.mjs tests/test_roleplay_output_contract_cleanup_worker.mjs tests/test_roleplay_output_contract_nonstream_worker.mjs tests/test_roleplay_output_contract_worker.mjs tests/test_roleplay_performance_worker.mjs tests/test_roleplay_quality_routing_worker.mjs tests/test_roleplay_reasoning_worker.mjs tests/test_roleplay_session_storage_worker.mjs tests/test_roleplay_transport_failure_worker.mjs tests/test_roleplay_unlimited_worker.mjs tests/test_roleplay_workbench_worker.mjs tests/test_roleplay_candidate_context_worker.mjs tests/test_roleplay_operator_worker.mjs tests/test_workbench_stream.mjs tests/test_intelligence_worker.mjs tests/test_intelligence_d1_worker.mjs tests/test_intelligence_auth_worker.mjs tests/test_intelligence_outbound_worker.mjs tests/test_intelligence_operator.mjs tests/test_control_users_worker.mjs tests/test_control_audit_worker.mjs tests/test_access_sso_worker.mjs tests/test_d1_schema_worker.mjs tests/test_shadow_eval_worker.mjs tests/test_auto_routes_worker.mjs tests/test_ai_outbound_worker.mjs tests/test_knowledge_*.mjs tests/test_control_state_worker.mjs tests/test_route_health_worker.mjs tests/test_gateway_mcp_worker.mjs tests/test_usage_ledger_worker.mjs tests/test_media_outbound_worker.mjs tests/test_media_files_worker.mjs tests/test_media_jobs_worker.mjs tests/test_tool_repair_worker.mjs tests/test_prometheus_worker.mjs tests/test_evaluation_noise_floor_worker.mjs tests/test_prompt_templates_worker.mjs tests/test_config_snapshots_worker.mjs tests/test_managed_idempotency_worker.mjs tests/test_wave3_hub_worker.mjs tests/test_wave3_transport_worker.mjs tests/test_admission_leases_worker.mjs tests/test_edge_request_metrics_worker.mjs tests/test_request_cancellation_worker.mjs tests/test_mcp_contract_drift_worker.mjs tests/test_zero_content_retention_worker.mjs tests/test_prompt_cache_cost_worker.mjs tests/test_config_revision_sync_worker.mjs tests/test_gateway_alerts_worker.mjs tests/test_session_tiers_worker.mjs tests/test_usage_reservations_worker.mjs tests/test_shared_generation_cache_worker.mjs tests/test_deferred_tools_worker.mjs tests/test_generation_deadline_worker.mjs tests/test_wave4_worker.mjs tests/test_responses_state_worker.mjs tests/test_gateway_batches_worker.mjs tests/test_semantic_generation_cache_worker.mjs tests/test_canary_traffic_worker.mjs tests/test_context_pages_worker.mjs tests/test_observability_exports_worker.mjs tests/test_prompt_injection_worker.mjs tests/test_pii_rehydration_worker.mjs tests/test_wave5_worker.mjs tests/test_usage_receipts_worker.mjs tests/test_learned_cooldown_worker.mjs tests/test_stream_cost_breaker_worker.mjs tests/test_realtime_worker.mjs tests/test_latency_slo_worker.mjs tests/test_context_canary_worker.mjs tests/test_enterprise_contracts_worker.mjs tests/test_wave6_worker.mjs tests/test_saml_federation_worker.mjs tests/test_tenant_governance_worker.mjs tests/test_tenant_hierarchy_worker.mjs",
"test:worker": "node --test tests/test_cloudflare_worker.mjs tests/test_cascades_worker.mjs tests/test_cascades_dashboard.mjs tests/test_image_quality_worker.mjs tests/test_secret_scan_worker.mjs tests/test_secret_firewall_worker.mjs tests/test_secret_firewall_coverage_worker.mjs tests/test_roleplay_compaction_budget_worker.mjs tests/test_roleplay_compaction_model_worker.mjs tests/test_roleplay_stream_validation_worker.mjs tests/test_aihubmix_worker.mjs tests/test_gpt_image_moderation_worker.mjs tests/test_dashboard_scripts.mjs tests/test_operations_dashboard.mjs tests/test_opencode_reasoning_worker.mjs tests/test_opencode_thinking_worker.mjs tests/test_nanogpt_reasoning_worker.mjs tests/test_nanogpt_speed_routing_worker.mjs tests/test_sse_heartbeat_worker.mjs tests/test_roleplay_worker.mjs tests/test_roleplay_config_worker.mjs tests/test_roleplay_glm_failover_worker.mjs tests/test_roleplay_intelligence_worker.mjs tests/test_roleplay_memory_worker.mjs tests/test_roleplay_compatibility_worker.mjs tests/test_roleplay_history_reconciliation_worker.mjs tests/test_roleplay_output_contract_analysis.mjs tests/test_roleplay_output_contract_cleanup_worker.mjs tests/test_roleplay_output_contract_nonstream_worker.mjs tests/test_roleplay_output_contract_worker.mjs tests/test_roleplay_performance_worker.mjs tests/test_roleplay_quality_routing_worker.mjs tests/test_roleplay_reasoning_worker.mjs tests/test_roleplay_session_storage_worker.mjs tests/test_roleplay_transport_failure_worker.mjs tests/test_roleplay_unlimited_worker.mjs tests/test_roleplay_workbench_worker.mjs tests/test_roleplay_candidate_context_worker.mjs tests/test_roleplay_operator_worker.mjs tests/test_workbench_stream.mjs tests/test_intelligence_worker.mjs tests/test_intelligence_d1_worker.mjs tests/test_intelligence_auth_worker.mjs tests/test_intelligence_outbound_worker.mjs tests/test_intelligence_operator.mjs tests/test_control_users_worker.mjs tests/test_control_audit_worker.mjs tests/test_access_sso_worker.mjs tests/test_d1_schema_worker.mjs tests/test_shadow_eval_worker.mjs tests/test_auto_routes_worker.mjs tests/test_ai_outbound_worker.mjs tests/test_knowledge_*.mjs tests/test_control_state_worker.mjs tests/test_route_health_worker.mjs tests/test_gateway_mcp_worker.mjs tests/test_usage_ledger_worker.mjs tests/test_media_outbound_worker.mjs tests/test_media_files_worker.mjs tests/test_media_jobs_worker.mjs tests/test_tool_repair_worker.mjs tests/test_prometheus_worker.mjs tests/test_evaluation_noise_floor_worker.mjs tests/test_prompt_templates_worker.mjs tests/test_config_snapshots_worker.mjs tests/test_managed_idempotency_worker.mjs tests/test_wave3_hub_worker.mjs tests/test_wave3_transport_worker.mjs tests/test_admission_leases_worker.mjs tests/test_edge_request_metrics_worker.mjs tests/test_request_cancellation_worker.mjs tests/test_mcp_contract_drift_worker.mjs tests/test_zero_content_retention_worker.mjs tests/test_prompt_cache_cost_worker.mjs tests/test_config_revision_sync_worker.mjs tests/test_gateway_alerts_worker.mjs tests/test_session_tiers_worker.mjs tests/test_usage_reservations_worker.mjs tests/test_shared_generation_cache_worker.mjs tests/test_deferred_tools_worker.mjs tests/test_generation_deadline_worker.mjs tests/test_wave4_worker.mjs tests/test_responses_state_worker.mjs tests/test_gateway_batches_worker.mjs tests/test_semantic_generation_cache_worker.mjs tests/test_canary_traffic_worker.mjs tests/test_context_pages_worker.mjs tests/test_observability_exports_worker.mjs tests/test_prompt_injection_worker.mjs tests/test_pii_rehydration_worker.mjs tests/test_wave5_worker.mjs tests/test_usage_receipts_worker.mjs tests/test_learned_cooldown_worker.mjs tests/test_stream_cost_breaker_worker.mjs tests/test_realtime_worker.mjs tests/test_latency_slo_worker.mjs tests/test_context_canary_worker.mjs tests/test_enterprise_contracts_worker.mjs tests/test_wave6_worker.mjs tests/test_scim_provisioning_worker.mjs tests/test_saml_federation_worker.mjs tests/test_tenant_governance_worker.mjs tests/test_tenant_hierarchy_worker.mjs",
"db:migrate": "python scripts/validate_sqlite_schema.py --apply",
"db:validate": "python scripts/validate_sqlite_schema.py",
"security:secrets": "python scripts/check_static_secrets.py",
Expand Down
Loading
Loading