Single sign on is one of those features that does not matter at all until it becomes a dealbreaker. You are selling to a 500 person company, the deal is moving forward, and then their IT team asks: "Do you support SSO with our identity provider?" If the answer is no, the deal stalls or dies. We have seen this happen repeatedly. Enterprise buyers do not treat SSO as a nice to have. It is a security requirement, a compliance checkbox, and a condition of procurement.
This post covers the architecture behind SSO implementation, the protocols you need to understand, the integration patterns that work in production, and the mistakes we have watched teams make when adding SSO to an existing product.
Why Enterprise Customers Require SSO
The reasoning is straightforward. Large organizations manage hundreds or thousands of user accounts across dozens of tools. Without SSO, every application is a separate set of credentials to manage. That means separate password policies, separate access revocation when someone leaves, and separate audit trails. For an IT administrator managing 2,000 employees, this is unworkable.
SSO solves three problems at once. First, it centralizes authentication so IT can enforce password policies, MFA requirements, and conditional access rules from a single place. Second, it enables instant deprovisioning. When an employee leaves, disabling their identity provider account locks them out of every connected application. Third, it provides a unified audit trail showing who accessed what and when.
From a product perspective, supporting SSO moves your application from "team tool" to "enterprise ready." It is often the single largest unlock for upmarket sales. We have worked on projects where adding SSO support doubled the average contract value because it opened the door to organizations that previously could not purchase.
SAML vs OIDC: Choosing the Right Protocol
Two protocols dominate the SSO landscape: SAML 2.0 and OpenID Connect (OIDC). Both accomplish the same goal, but they work differently and serve different audiences.
SAML 2.0 is the older protocol. It is XML based, verbose, and deeply entrenched in enterprise IT. If your customers use Okta, Azure AD, OneLogin, or PingFederate, they almost certainly support SAML. The protocol exchanges XML assertions between the identity provider (IdP) and your application (the service provider). It is battle tested, widely supported, and frustrating to debug because of the XML parsing, certificate management, and redirect flows involved.
OIDC is built on top of OAuth 2.0 and uses JSON instead of XML. It is simpler to implement, easier to debug, and increasingly supported by enterprise identity providers. Most modern IdPs support both SAML and OIDC, though some legacy enterprise environments still only offer SAML.
Our recommendation: support both. Start with OIDC because it is faster to implement and easier to maintain, then add SAML for customers whose IdPs require it. In practice, about 70% of the enterprise SSO requests we encounter can be handled with OIDC. The remaining 30% need SAML. If you are building a SaaS product targeting enterprise, plan for both from the beginning.
Architecture Decisions That Matter
The way you integrate SSO into your authentication system has long term consequences. Here are the decisions that matter most.
Tenant level configuration. SSO is configured per organization, not per user. Your system needs a way for each tenant to provide their IdP metadata (entity ID, SSO URL, certificate for SAML, or client ID, secret, and discovery URL for OIDC). This means your multi tenant architecture needs a settings layer that stores IdP configuration per organization.
Just in time provisioning vs directory sync. When a user authenticates via SSO for the first time, do you create their account automatically (JIT provisioning) or require a pre existing account? JIT provisioning is simpler and what most teams start with. Directory sync (via SCIM) is more robust because it lets the IdP push user creates, updates, and deletes to your application proactively. Enterprise customers with strict offboarding requirements will eventually ask for SCIM.
Enforced vs optional SSO. Some organizations want SSO to be the only way their users can log in. Others want it as an option alongside email and password. Your system should support both modes per tenant. Enforced SSO means you need to detect the user's organization before showing a login form, typically by asking for their email domain first.
Session management. SSO introduces complexity around session lifetimes. Your application session, the IdP session, and any intermediate sessions all have different expiration policies. Decide early whether your application will respect the IdP's session lifetime or manage its own. Most teams manage their own sessions and re authenticate against the IdP when the local session expires.
For authentication architecture in general, including how JWT sessions and OAuth flows interact with SSO, we covered the foundations in our authentication architecture guide.
The Implementation Path
Here is the sequence we follow on projects we have shipped.
Step 1: Abstract your auth layer. If your application has authentication logic scattered across multiple files, consolidate it behind a single auth service. This service should handle login, logout, session creation, and user lookup regardless of the authentication method. SSO becomes another authentication method that plugs into this service.
Step 2: Build the tenant configuration UI. Create an admin interface where organization admins can input their IdP details. For SAML, this means uploading IdP metadata XML or entering the entity ID, SSO URL, and certificate manually. For OIDC, this means entering the discovery URL (or issuer), client ID, and client secret. Validate the configuration before saving it.
Step 3: Implement the SSO flow. For SAML, this involves generating AuthnRequests, redirecting to the IdP, consuming the SAML Response, validating the XML signature, and extracting the user attributes. For OIDC, it involves redirecting to the authorization endpoint, handling the callback, exchanging the code for tokens, and validating the ID token. Libraries like passport-saml (Node.js) or python-saml handle the heavy lifting, but you still need to understand the flow to debug issues.
Step 4: Handle user mapping. The IdP returns an identifier for the user, usually an email address or a unique ID. Your application needs to map this to an existing user account or create a new one. Edge cases here include: users who already have a password based account (link or reject?), email addresses that do not match the expected domain, and IdPs that send different attributes than expected.
Step 5: Test with real identity providers. This is where most implementations break. Testing with a mock IdP is necessary during development, but the real test is connecting to Okta, Azure AD, Google Workspace, and OneLogin with real configurations. Each IdP has quirks. Azure AD sends group claims differently than Okta. Google Workspace SAML has specific requirements around relay state. Budget time for IdP specific debugging.
Common Pitfalls
Certificate rotation. SAML uses X.509 certificates to sign assertions. These certificates expire. If your system does not support multiple active certificates (to allow for rotation without downtime), your customers will experience authentication failures when their IdP rotates certificates. Support at least two active certificates per tenant.
Clock skew. SAML assertions contain timestamps with validity windows, often just a few minutes. If your server clock is off by more than that window, assertions get rejected. Use NTP and add a reasonable clock skew tolerance (we typically allow 5 minutes).
Missing error handling. SSO failures are opaque to end users. "Authentication failed" tells them nothing. Log the full SAML response or OIDC error, including the specific validation failure, so your support team can diagnose issues. Surface a meaningful error to the user when possible, like "Your organization's SSO certificate has expired, please contact your IT administrator."
Ignoring the logout flow. Single sign on implies single logout. When a user logs out of your application, should they also be logged out of their IdP? When they log out of their IdP, should your application session end? Most teams skip single logout initially, but enterprise customers with compliance requirements will eventually require it.
Pricing SSO Correctly
SSO is a premium feature. It requires ongoing maintenance, customer support for IdP configuration, and testing against multiple identity providers. Pricing it as a free feature undervalues the work and the enterprise value it unlocks. Most SaaS products gate SSO behind an enterprise tier, and that is the correct approach.
On the system architecture side, SSO is not a weekend project. Plan for 3 to 6 weeks of engineering time depending on whether you need SAML, OIDC, or both, and whether you need SCIM provisioning. If you are comparing the cost of building this in house versus working with a team that has done it before, the difference is usually measured in months of avoided debugging.
If you are building an enterprise SaaS product and need SSO implementation that works with real identity providers, not just demo environments, reach out to us and we will scope the work.