Enterprise SSO with SAML and OIDC

Pathrule4 Rules • 2 Memories • 1 Skill

Enterprise SSO connects each customer tenant to an external identity provider whose issuer, keys, metadata, claims, certificates, domains, provisioning, and deprovisioning lifecycle can change independently. This pattern constrains tenant discovery, protocol validation, account linking, and session issuance; it records JIT and provisioning ownership and supplies a metadata and certificate rotation workflow. It deepens generic authentication by focusing on multi-tenant enterprise federation, SAML assertions, OIDC issuers, IdP-initiated entry, and lifecycle coordination with SCIM.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

rotate-enterprise-sso-metadata

src/

auth/

sso/

Bind every federation response to tenant and login transaction

Link enterprise identities through verified stable keys

Issue local sessions only after local authorization

JIT provisioning creates minimum local state

provisioning/

Make provisioning and deprovisioning idempotent and monotonic

Federation metadata is versioned security configuration

Rules

Bind every federation response to tenant and login transaction/src/auth/ssohighstrictResolve the approved connection first, then validate issuer, audience, destination, signature, nonce or request correlation, time, and replay for that tenant.

1	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.
2
3	- Resolve connection through a trusted tenant choice, verified domain policy, or opaque login transaction, never from untrusted response claims alone.
4	- For OIDC, validate issuer, audience, signature, time, nonce, state, and authorization-code flow through the configured provider metadata.
5	- For SAML, validate signature placement, issuer, audience, recipient or destination, time conditions, request correlation where used, and assertion replay.
6	- Reject responses that match more than one tenant or connection and log stable connection and transaction identities without retaining raw sensitive assertions.
7
8	See /tests/sso for the adjacent decision or procedure that completes this constraint.

Link enterprise identities through verified stable keys/src/auth/ssohighstrictUse tenant connection plus immutable provider subject, and require authenticated proof before attaching SSO to an existing local account.

1	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.
2
3	- Store enterprise identity by tenant or connection and stable provider subject, preserving issuer and protocol identity.
4	- Use email for display or discovery only when its verification and tenant-domain policy are explicit.
5	- Require an authenticated existing session, administrative action, or other strong proof before linking an SSO identity to an existing non-federated account.
6	- Handle provider subject or tenant changes as controlled migration, never as a silent fallback to matching the latest email.
7
8	See /src/provisioning for the adjacent decision or procedure that completes this constraint.

Issue local sessions only after local authorization/src/auth/ssohighstrictTranslate a valid external identity into current tenant membership, status, policy, and role checks before creating the application session.

1	Federation authentication proves the IdP's statement. The application still owns tenant access, suspension, product entitlements, local policy, and resource authorization.
2
3	- Resolve the local user and tenant membership after protocol validation and reject suspended, deleted, unassigned, or policy-blocked access.
4	- Map external groups or roles through a tenant-owned allowlist and default to minimum access; do not accept arbitrary claim values as application permissions.
5	- Keep the local session bounded and revocable and decide how IdP session, reauthentication, and logout affect it.
6	- Re-evaluate sensitive authorization against current local state rather than assuming claims captured at login remain valid indefinitely.
7
8	See /src/provisioning for the adjacent decision or procedure that completes this constraint.

Make provisioning and deprovisioning idempotent and monotonic/src/provisioninghighstrictApply SCIM or administrative changes by stable external identity and prevent stale events from restoring removed access.

1	Provisioning systems retry and can deliver updates around manual changes. A delete, disable, group removal, or later stale update must not produce contradictory access.
2
3	- Use provider resource identity and tenant connection as the idempotent key for users and groups.
4	- Track version or modification time where trustworthy and reject stale updates that would move deprovisioned state backward.
5	- On disable or removal, revoke sessions and access through a durable local transition and preserve audit evidence.
6	- Define precedence between SCIM, JIT, administrator edits, and group mapping so one path cannot silently undo another's security decision.
7
8	See /src/auth/sso for the adjacent decision or procedure that completes this constraint.

Memories

JIT provisioning creates minimum local state/src/auth/ssoCreate a user only from an approved connection and verified claims, then assign no more access than tenant policy grants.

1	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.
2
3	- Enable JIT per tenant and connection and require the claims the tenant policy needs for identity and membership.
4	- Create the local user and stable external identity link atomically so login retry cannot create duplicates.
5	- Assign baseline access through explicit domain or group mapping and send uncertain cases to administrator approval.
6	- Reconcile later SCIM or administrative provisioning with the same stable identity instead of creating a second account.
7
8	See /src/provisioning for the rule or workflow that puts this decision into practice.

Federation metadata is versioned security configuration/src/provisioningTrack issuer, endpoints, keys, certificates, entity IDs, client settings, domains, and claim mapping with owner and rotation state.

1	IdP keys and certificates rotate while endpoints, entity identifiers, and claims can also change. Ad hoc console edits leave no review or overlap plan.
2
3	- Store connection configuration encrypted and tenant-scoped with audit history and a safe test mode.
4	- Support overlapping signing keys or certificates during rotation where the protocol and provider permit it.
5	- Validate fetched metadata origin and changes before adoption; do not let an attacker-controlled URL rewrite trust automatically.
6	- Monitor login failures and credential expiry by connection and notify the tenant owner before the existing trust material stops working.
7
8	See /tests/sso for the rule or workflow that puts this decision into practice.

Skills

rotate-enterprise-sso-metadata/rootStage, test, activate, observe, and retire SAML or OIDC trust material without locking out a tenant.

1	---
2	name: rotate-enterprise-sso-metadata
3	description: Rotate an enterprise IdP certificate, signing key, client credential, endpoint, issuer, or metadata document.
4	---
5
6	# Rotate Enterprise Sso Metadata
7
8	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.
9
10	1. Inventory tenant connection, protocol, issuer or entity ID, endpoints, audiences, keys, certificates, client secrets, claim maps, domains, and owner.
11	2. Validate new metadata through a trusted channel and stage overlapping verification material while keeping the active path available.
12	3. Run service-provider and identity-provider initiated flows where supported, including valid, old-key, new-key, wrong-audience, expired, replayed, and deprovisioned users.
13	4. Activate for a bounded tenant cohort and monitor protocol validation categories, login success, account linking, session issuance, and support signals.
14	5. Retire old trust only after provider confirmation and observed new-key traffic, then update expiry monitoring and the tenant-facing recovery record.
15
16	## Exit criteria
17
18	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.

Why this pattern

AI agents often select a tenant from an unverified email domain, accept an assertion for the wrong audience, link accounts by mutable email alone, or keep access after the IdP deprovisions a user.

Built for SaaS identity teams supporting customer-managed SAML or OpenID Connect providers.

Keeps your assistant from:

Routing a user to an attacker-controlled tenant connection
Accepting a token or assertion issued for another application
Taking over an existing account through unsafe email linking
Leaving enterprise access active after deprovisioning

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25