# Pathrule Pattern: Enterprise SSO with SAML and OIDC (1.0.0) # ::pathrule:package:enterprise-sso-saml-oidc ### [RULE] Bind every federation response to tenant and login transaction (path: /src/auth/sso) A structurally valid response is not valid for every tenant or application. Federation security comes from binding it to the exact connection and login initiated by this client. - Resolve connection through a trusted tenant choice, verified domain policy, or opaque login transaction, never from untrusted response claims alone. - For OIDC, validate issuer, audience, signature, time, nonce, state, and authorization-code flow through the configured provider metadata. - For SAML, validate signature placement, issuer, audience, recipient or destination, time conditions, request correlation where used, and assertion replay. - Reject responses that match more than one tenant or connection and log stable connection and transaction identities without retaining raw sensitive assertions. See /tests/sso for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Link enterprise identities through verified stable keys (path: /src/auth/sso) Email addresses can change, be reassigned, collide across tenants, or arrive unverified. Automatic linking by email can hand an existing account to a different external identity. - Store enterprise identity by tenant or connection and stable provider subject, preserving issuer and protocol identity. - Use email for display or discovery only when its verification and tenant-domain policy are explicit. - Require an authenticated existing session, administrative action, or other strong proof before linking an SSO identity to an existing non-federated account. - Handle provider subject or tenant changes as controlled migration, never as a silent fallback to matching the latest email. See /src/provisioning for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Issue local sessions only after local authorization (path: /src/auth/sso) Federation authentication proves the IdP's statement. The application still owns tenant access, suspension, product entitlements, local policy, and resource authorization. - Resolve the local user and tenant membership after protocol validation and reject suspended, deleted, unassigned, or policy-blocked access. - Map external groups or roles through a tenant-owned allowlist and default to minimum access; do not accept arbitrary claim values as application permissions. - Keep the local session bounded and revocable and decide how IdP session, reauthentication, and logout affect it. - Re-evaluate sensitive authorization against current local state rather than assuming claims captured at login remain valid indefinitely. See /src/provisioning for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Make provisioning and deprovisioning idempotent and monotonic (path: /src/provisioning) Provisioning systems retry and can deliver updates around manual changes. A delete, disable, group removal, or later stale update must not produce contradictory access. - Use provider resource identity and tenant connection as the idempotent key for users and groups. - Track version or modification time where trustworthy and reject stale updates that would move deprovisioned state backward. - On disable or removal, revoke sessions and access through a durable local transition and preserve audit evidence. - Define precedence between SCIM, JIT, administrator edits, and group mapping so one path cannot silently undo another's security decision. See /src/auth/sso for the adjacent decision or procedure that completes this constraint. --- ### [MEMORY] JIT provisioning creates minimum local state (path: /src/auth/sso) Just-in-time creation is convenient but can turn any successfully authenticated external identity into a tenant member if connection and group policy are broad. - Enable JIT per tenant and connection and require the claims the tenant policy needs for identity and membership. - Create the local user and stable external identity link atomically so login retry cannot create duplicates. - Assign baseline access through explicit domain or group mapping and send uncertain cases to administrator approval. - Reconcile later SCIM or administrative provisioning with the same stable identity instead of creating a second account. See /src/provisioning for the rule or workflow that puts this decision into practice. --- ### [MEMORY] Federation metadata is versioned security configuration (path: /src/provisioning) IdP keys and certificates rotate while endpoints, entity identifiers, and claims can also change. Ad hoc console edits leave no review or overlap plan. - Store connection configuration encrypted and tenant-scoped with audit history and a safe test mode. - Support overlapping signing keys or certificates during rotation where the protocol and provider permit it. - Validate fetched metadata origin and changes before adoption; do not let an attacker-controlled URL rewrite trust automatically. - Monitor login failures and credential expiry by connection and notify the tenant owner before the existing trust material stops working. See /tests/sso for the rule or workflow that puts this decision into practice. --- ### [SKILL] rotate-enterprise-sso-metadata (path: /) --- name: rotate-enterprise-sso-metadata description: Rotate an enterprise IdP certificate, signing key, client credential, endpoint, issuer, or metadata document. --- # Rotate Enterprise Sso Metadata Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result. 1. Inventory tenant connection, protocol, issuer or entity ID, endpoints, audiences, keys, certificates, client secrets, claim maps, domains, and owner. 2. Validate new metadata through a trusted channel and stage overlapping verification material while keeping the active path available. 3. Run service-provider and identity-provider initiated flows where supported, including valid, old-key, new-key, wrong-audience, expired, replayed, and deprovisioned users. 4. Activate for a bounded tenant cohort and monitor protocol validation categories, login success, account linking, session issuance, and support signals. 5. Retire old trust only after provider confirmation and observed new-key traffic, then update expiry monitoring and the tenant-facing recovery record. ## Exit criteria The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.