AI Rules for SSO Implementation

AI Reinvents SSO Instead of Supporting Standards

AI generates SSO with: a custom token-sharing mechanism between applications (not SAML, not OIDC — a proprietary protocol that no enterprise IdP supports), no identity provider integration (cannot connect to Okta, Azure AD, or Google Workspace), manual user creation (admin creates accounts one by one instead of auto-provisioning from the IdP), no session federation (logging into one app does not log into others), and no domain-based enforcement (users from @company.com can bypass SSO with email/password). Enterprise customers require SAML or OIDC — custom SSO is a non-starter.

Modern SSO is: standards-based (SAML 2.0 and OIDC — supported by every enterprise IdP), JIT-provisioned (user accounts created automatically on first SSO login from the IdP), session-federated (one login grants access to all connected applications), domain-enforced (users with @company.com email must use SSO, cannot bypass with password), and IdP-agnostic (works with Okta, Azure AD, Google Workspace, Ping, OneLogin). AI generates none of these.

These rules cover: SAML 2.0 service provider implementation, OIDC integration, just-in-time user provisioning, federated session management, domain-based SSO enforcement, and enterprise IdP onboarding.

Rule 1: SAML 2.0 Service Provider Implementation

The rule: 'Implement your application as a SAML 2.0 Service Provider (SP). The flow: (1) user visits your app, (2) app redirects to the customer IdP (Okta, Azure AD) with a SAML AuthnRequest, (3) user authenticates at the IdP, (4) IdP sends a SAML Response (signed XML assertion) back to your app via POST to your ACS (Assertion Consumer Service) URL, (5) your app validates the signature, extracts user attributes (email, name, groups), and creates a session. Libraries: saml2-js, passport-saml, or @boxyhq/saml-jackson (open-source SAML-as-a-service).'

For the SP metadata: 'Your application publishes SP metadata at a well-known URL (/.well-known/saml-metadata or /api/auth/saml/metadata): XML containing your Entity ID (unique identifier), ACS URL (where the IdP sends the response), and signing certificate (for request signing). The enterprise customer downloads your metadata and uploads it to their IdP. The IdP publishes its own metadata: SSO URL, signing certificate, and Entity ID. Both sides exchange metadata — this is the SSO handshake.'

AI generates: a custom token exchange between two applications that only works for one specific customer. The next enterprise customer uses a different IdP (Azure AD instead of Okta) — the custom implementation does not work. SAML is the standard: every enterprise IdP supports it. Implement SAML once, support every IdP. No per-customer custom integration.

• SAML 2.0 SP: AuthnRequest → IdP authentication → signed assertion → session
• SP metadata: Entity ID, ACS URL, signing certificate at a well-known endpoint
• Libraries: saml2-js, passport-saml, @boxyhq/saml-jackson (SAML-as-a-service)
• Validate signature on every assertion: reject unsigned or incorrectly signed responses
• One implementation supports every IdP: Okta, Azure AD, Google Workspace, Ping, OneLogin

Rule 2: OIDC Provider Support

The rule: 'Support OpenID Connect (OIDC) alongside SAML. OIDC is: OAuth 2.0 + identity layer (simpler than SAML, JSON-based instead of XML). The flow: (1) redirect to the customer IdP authorization endpoint, (2) user authenticates, (3) IdP redirects back with an authorization code, (4) your app exchanges the code for tokens (ID token + access token), (5) ID token contains user claims (email, name, groups). OIDC is easier to implement than SAML and preferred by modern IdPs (Azure AD, Auth0, Okta all support both).'

For discovery: 'OIDC IdPs publish configuration at /.well-known/openid-configuration: authorization endpoint, token endpoint, userinfo endpoint, JWKS URI (for token verification), and supported scopes. Your app reads this configuration dynamically — no hardcoded URLs. When a customer enters their IdP domain, your app fetches the OIDC configuration and configures itself automatically. This is OIDC Discovery (RFC 8414) — zero manual configuration per customer.'

AI generates: SAML only (complex, XML-based, harder to debug) or OIDC only (some enterprise IdPs only support SAML). Support both: SAML for enterprises that require it (banks, government, healthcare), OIDC for enterprises that prefer it (tech companies, startups). The customer chooses their preferred protocol during SSO setup. Your application handles both through a common session interface.

Rule 3: Just-In-Time User Provisioning

The rule: 'Create user accounts automatically on first SSO login. JIT provisioning: (1) user authenticates via SSO for the first time, (2) SAML assertion or OIDC ID token contains: email, name, and optionally groups/roles, (3) your app checks if a user with that email exists, (4) if not: create the user automatically with attributes from the assertion, (5) if exists: update the profile with the latest IdP data (name change, group membership change). No admin needs to pre-create accounts — they exist the moment the user first logs in.'

For group and role mapping: 'Enterprise IdPs send group membership in the assertion: groups: ["Engineering", "Team-Leads", "SSO-Admin"]. Map IdP groups to your application roles: const roleMap = { "SSO-Admin": "admin", "Team-Leads": "editor", "*": "viewer" }. On each login: update the user role based on their current IdP groups. This means: the enterprise IT admin manages roles in their IdP (Okta, Azure AD), and your application reflects those roles automatically. No separate role management in your app.'

AI generates: an admin panel where the IT admin must manually create 500 user accounts before SSO works. One new hire: admin creates account in the IdP AND manually in your app. Employee leaves: admin removes from IdP but forgets your app (orphaned account with access). JIT provisioning: IdP is the source of truth. New hire logs in — account created. Employee removed from IdP — cannot log in (no valid SSO session). Zero manual user management in your application.

• Auto-create on first SSO login: email, name, groups from assertion/token
• Auto-update on subsequent logins: name changes, group membership changes reflected
• IdP group-to-role mapping: Engineering → viewer, Team-Leads → editor, SSO-Admin → admin
• IdP is source of truth: no separate user management in your application
• Deprovisioning: user removed from IdP cannot log in — no orphaned accounts

Rule 4: Domain-Based SSO Enforcement

The rule: 'When an organization configures SSO, enforce it for all users with that email domain. If ACME Corp configures SSO with their Okta: all users with @acme.com emails must authenticate via Okta SSO. They cannot bypass SSO by using email/password login. Implementation: on login, check the email domain against the SSO configuration table: SELECT * FROM sso_configs WHERE domain = email_domain. If found: redirect to the configured IdP. If not found: allow email/password login.'

For the enforcement flow: '(1) User enters email on the login page. (2) App checks if the email domain has SSO configured. (3) If SSO: hide the password field, show "Continue with SSO" button, redirect to IdP. (4) If no SSO: show normal email/password form. This is the same pattern as Microsoft and Google login: enter your email first, the system determines the authentication method. The user does not choose between SSO and password — the system enforces the correct method based on their organization configuration.'

AI generates: SSO as an optional login method alongside email/password. Users with @acme.com can still log in with a password, bypassing all IdP security policies (MFA, conditional access, session timeout). The enterprise IT admin configures SSO for security — allowing password bypass defeats the purpose. Domain enforcement: SSO is mandatory for configured domains, no bypass possible.

Rule 5: Enterprise IdP Onboarding Flow

The rule: 'Provide a self-service SSO configuration page for enterprise admins: (1) select protocol (SAML or OIDC), (2) for SAML: upload IdP metadata XML or enter SSO URL + certificate manually, (3) for OIDC: enter the IdP discovery URL or client ID + secret + endpoints, (4) configure domain enforcement (which email domains use this SSO), (5) test the connection (admin logs in via SSO to verify it works), (6) enable for the organization. The entire setup should take under 15 minutes without involving your support team.'

For the test connection step: 'Before enabling SSO for the entire organization, the admin tests the connection: click "Test SSO", redirect to the IdP, authenticate, return to the app. If successful: show green checkmark, "SSO connection verified." If failed: show the specific error (certificate mismatch, wrong ACS URL, missing attributes) with troubleshooting steps. Never enable SSO without a successful test — a misconfigured SSO locks out the entire organization.'

AI generates: SSO configuration that requires emailing metadata files to your support team, a multi-day setup process, and no test before activation. The enterprise admin waits 3 days for support to configure SSO, then discovers it does not work (wrong certificate). Self-service setup: the admin configures and tests in 15 minutes, enables when verified. Zero support tickets, zero waiting, zero misconfiguration risk.

Complete SSO Implementation Rules Template

Consolidated rules for SSO implementation.

• SAML 2.0 SP: signed assertions, metadata exchange, works with every enterprise IdP
• OIDC support alongside SAML: customer chooses protocol, your app handles both
• OIDC Discovery: auto-configure from /.well-known/openid-configuration — zero manual URLs
• JIT provisioning: auto-create users on first SSO login from assertion attributes
• Group-to-role mapping: IdP groups → app roles, updated on every login
• Domain enforcement: @acme.com must use SSO, no password bypass
• Self-service setup: upload metadata, test connection, enable — under 15 minutes
• Never enable SSO without a successful test: misconfiguration locks out the entire org