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
64 changes: 64 additions & 0 deletions docs/saml-federation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# SAML federation through a trusted broker

The gateway accepts a signed identity token from an operator-run SAML broker. The broker validates the IdP response, XML signatures, destination, audience, timing and SAML request correlation. The gateway does not download IdP metadata, parse XML or implement native SAML validation. `/auth/saml/acs` and `/auth/saml/metadata` return JSON HTTP 503 `saml_native_unavailable` when federation is enabled. They do not publish an ACS descriptor.

Federation is off by default. `SAML_ENABLED=false` or an empty value makes every `/auth/saml/*` and subject-link endpoint return HTTP 404 before session, CSRF or storage work. Existing gateway requests keep their behavior. Malformed configuration disables federation and emits one warning without configuration values.

## Configuration

Use an HTTPS broker URL without credentials or a fragment. Its query may contain broker-specific settings, but cannot contain `nonce`, `state` or `recipient`. Configure a fixed HTTPS callback URL ending in `/auth/saml/callback`, without a query or fragment. It is never derived from caller headers or a redirect parameter.

```text
SAML_ENABLED=true
SAML_BROKER_URL=https://broker.example/login
SAML_CALLBACK_URL=https://gateway.example/auth/saml/callback
```

`SAML_TRUST_CONFIG_JSON` defaults to `{}`. An enabled deployment must supply exactly these fields:

```json
{
"issuer": "https://broker.example/issuer",
"audience": "gateway.example",
"keys": [
{"kid": "broker-2026", "alg": "EdDSA", "public_key_pem": "<public Ed25519 PEM>"}
],
"max_age_seconds": 300
}
```

Each key pins one unique `kid` and exact algorithm: `RS256` with an RSA public key of at least 2048 bits, or `EdDSA` with an Ed25519 public key. There may be at most 16 keys. No private key belongs in gateway configuration. Symmetric algorithms, unsigned tokens, mismatched key types and remotely supplied key URLs are rejected. Rotate keys by temporarily pinning both public keys, then remove the old key after all assertions issued under it expire. `max_age_seconds` must be an integer from 1 to 300. The callback URL may instead be supplied as the Flask application's `SAML_CALLBACK_URL` configuration.

## Login and callback

`GET /auth/saml/login` stores SHA-256 digests of a random nonce, random request state and recipient with a five-minute expiry, then redirects HTTP 302 only to the configured broker. It also binds the state digest to the browser's signed dashboard session. A new login replaces that browser's active state. Caller `next` parameters are ignored.

The broker returns one compact JWS in `token` and the request state in `state`, using `GET /auth/saml/callback` or a URL-encoded POST. Use exactly one of each field. A token must include `iss`, `aud`, `sub`, integer `iat` and `exp`, `nonce`, `state` and `recipient`. `aud` is one exact string. `state` is the original request ID; `nonce` and recipient must match the original login. A token's lifetime cannot exceed `max_age_seconds`; a fixed five-second clock skew is allowed by signature verification. Durable requests still expire at five minutes without extending their claim lifetime.

The callback must retain the original browser session cookie. A top-level GET is compatible with a SameSite=Lax dashboard cookie; a cross-site POST requires an operator-reviewed secure cookie policy or a same-site broker. State binding replaces CSRF form-token validation only on the broker callback. GET tokens can appear in browser history and intermediary access logs: configure the broker and gateway edge to suppress or redact callback query strings. The gateway adds `Cache-Control: no-store` and `Referrer-Policy: no-referrer` and never stores assertion contents.

The nonce is claimed atomically once. A replay or expired durable request returns HTTP 400 `saml_assertion_replayed`. Invalid signature, issuer, audience, key, algorithm, recipient or browser binding returns HTTP 400 `saml_assertion_invalid`. Unknown or duplicate callback fields return HTTP 400 `saml_request_invalid`.

After verification, an active `(issuer, subject)` link must name an existing, unrevoked, unexpired gateway account. No link returns HTTP 403 `saml_subject_unlinked`; the gateway never creates accounts from broker attributes. Assertion roles, administrator flags and organisation names grant nothing. The stored link supplies organisation, team and grants revision; the injected `IdentityAuthority` must return that exact `TenantContext`. Its `IdentityAssertion` uses digests for identifiers so arbitrary broker subjects fit the enterprise opaque-ID contract. Account names outside that contract use `account:<SHA-256>` as principal ID, while session issuance still receives the actual account name.

The service requires a named dashboard session issuer that accepts `(account, TenantContext)` and returns `True` only after issuing the existing dashboard session. The default returns HTTP 503 `saml_session_unavailable`: API-key authentication has no separate session-creation function. The issuer must revalidate account permissions and populate the same session fields as dashboard login, using stored grants. The service uses the stored-link authority by default; an organisation authority can be injected to revalidate current membership. An unavailable authority returns HTTP 503 `saml_identity_unavailable`, and a scope mismatch returns HTTP 403 `saml_identity_denied`.

## Administrator subject links

These routes require an administrator dashboard session. PUT and DELETE also require the existing dashboard CSRF token.

- `GET /admin/saml/links?offset=0` lists up to 100 links, including inactive links; use `offset` to paginate.
- `GET /admin/saml/links/<id>` reads one link.
- `PUT /admin/saml/links` creates or updates the stable subject link.
- `PUT /admin/saml/links/<id>` edits the same issuer/subject binding. It cannot rebind that identifier to a different subject.
- `DELETE /admin/saml/links/<id>` deactivates the link and retains its row and audit history.

PUT accepts `issuer`, `subject`, `account`, and optional `org_id`, `team_id`, `grants_revision`. `issuer` must equal the configured issuer. A team requires an organisation. Tenant IDs use the enterprise opaque-ID format. Omitting scope fields selects the linked account's legacy scope. Account existence is checked by the service and again against durable dashboard accounts in the private handler. Link identifiers are stable 32-character hex digests. Only issuer and subject digests are persisted, so operators must retain their own subject-to-account mapping outside the gateway.

## Storage, audit and operational bounds

Apply `0035_saml_federation.sql` to D1 before enabling federation. It adds `saml_requests`, `saml_subject_links` and `saml_audit` and preserves existing accounts. The private handler is `handleSamlIdentityRequest` at `http://intelligence.internal/v1/managed-state/saml`. Its dispatcher and private client endpoint must be registered, and `register_saml_federation_routes(app, csrf)` must be mounted. The core login guard must include `SAML_PUBLIC_ENDPOINTS` in its public endpoint allowlist. The link routes retain their administrator guard. Until storage wiring is available, login fails closed.

Every private operation validates the required tables and columns before changing state. Missing storage or a missing migration returns JSON HTTP 503 `saml_storage_unavailable` without admitting login. There is no local-memory identity fallback or automatic replay of uncertain writes. Login audit records contain an issuer digest, linked account if known, outcome and time. `authorized` means signature, link and authority checks passed before session issuance; a later session failure adds its failure outcome. Link changes also record the operator's digest. Neither audit nor nonce rows contain tokens, raw subjects, nonce or request state.

Assertions are limited to 16 KiB; private RPC bodies to 8 KiB; trust configuration to 64 KiB; subjects to 1,024 characters. Expiry prevents reuse but does not delete request rows. No automatic audit or link pruning is performed: retention and database capacity are operator responsibilities. Retain inactive links and their audit history. D1 operations and external broker hosting may incur their normal charges; this feature makes no model-provider calls and defines no additional billing rate. Live IdP compatibility, deployment and native XML validation require separate operational verification.
36 changes: 36 additions & 0 deletions intelligence-migrations/0035_saml_federation.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
CREATE TABLE IF NOT EXISTS saml_requests (
state_digest TEXT PRIMARY KEY,
nonce_digest TEXT NOT NULL,
recipient_digest TEXT NOT NULL,
created_at INTEGER NOT NULL,
expires_at INTEGER NOT NULL,
claimed_at INTEGER,
CHECK(expires_at > created_at AND expires_at <= created_at + 300)
);
CREATE INDEX IF NOT EXISTS idx_saml_requests_expiry ON saml_requests(expires_at);

CREATE TABLE IF NOT EXISTS saml_subject_links (
id TEXT PRIMARY KEY,
issuer_digest TEXT NOT NULL,
subject_digest TEXT NOT NULL,
account TEXT NOT NULL REFERENCES control_users(username),
org_id TEXT,
team_id TEXT,
grants_revision INTEGER NOT NULL DEFAULT 0 CHECK(grants_revision >= 0),
active INTEGER NOT NULL DEFAULT 1 CHECK(active IN (0, 1)),
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL,
CHECK(team_id IS NULL OR org_id IS NOT NULL),
UNIQUE(issuer_digest, subject_digest)
);
CREATE INDEX IF NOT EXISTS idx_saml_subject_links_account ON saml_subject_links(account, active);

CREATE TABLE IF NOT EXISTS saml_audit (
id TEXT PRIMARY KEY,
issuer_digest TEXT NOT NULL,
account TEXT,
actor_digest TEXT,
outcome TEXT NOT NULL,
occurred_at INTEGER NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_saml_audit_time ON saml_audit(occurred_at);
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_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_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