SSO implementation for SaaS

Here’s a practical blueprint for implementing SSO (Single Sign-On) in a SaaS product.

1) Choose the SSO protocol

For most SaaS apps, support SAML 2.0 and/or OpenID Connect (OIDC):

• OIDC: Best for modern apps, easier to implement, great for login.
• SAML: Still common in enterprise environments, especially with older IdPs.

Recommendation:
Support OIDC first if you can, then add SAML for enterprise compatibility.

---

2) Define the tenant model

In SaaS, SSO is usually tenant-specific.

Each tenant can have:

• IdP type: Okta / Azure AD / Google / custom
• Protocol: SAML or OIDC
• Issuer/entity ID
• Client ID / client secret (OIDC)
• SAML metadata / certificates
• Allowed domains
• Auto-provisioning rules
• Just-in-time provisioning enabled/disabled

Example:

{
  "tenant_id": "acme",
  "sso_enabled": true,
  "protocol": "oidc",
  "issuer": "https://login.microsoftonline.com/xxxx/v2.0",
  "client_id": "abc123",
  "client_secret": "encrypted-value",
  "allowed_domains": ["acme.com"],
  "jit_provisioning": true
}

---

3) Core SSO flow

Typical login flow:

1. User enters email on your login page
2. You determine tenant from email domain or tenant selection
3. If tenant has SSO enabled, redirect to IdP
4. IdP authenticates user
5. IdP returns assertion/token to your app
6. Your app verifies the response
7. Create local session
8. Map user to tenant and roles
9. Redirect to app

---

4) Identity mapping

You need to map external identities to internal users.

Common keys:

• email
• sub (OIDC subject)
• NameID (SAML)
• IdP-specific unique ID

Rules:

• Prefer a stable immutable identifier (sub / NameID)
• Use email only for initial matching or provisioning
• Do not rely on email alone if users can change addresses

---

5) Provisioning strategy

You need to decide how users are created in your system.

Option A: Just-in-time provisioning

Create user on first successful SSO login.

Pros:

• Simple
• Low admin overhead

Cons:

• Less control over lifecycle

Option B: SCIM provisioning

Use SCIM 2.0 to sync users/groups from IdP.

Pros:

• Better enterprise experience
• Handles deprovisioning
• Syncs roles/groups

Cons:

• More work to implement

Best practice:
Use SSO for authentication and SCIM for provisioning.

---

6) Authorization model

SSO only proves identity. You still need authorization.

Decide how roles are assigned:

• Static roles in your app
• Roles based on IdP group claims
• Admin-managed role mapping per tenant

Example:

• IdP group acme-admins → app role Tenant Admin
• IdP group acme-users → app role Member

---

7) Security requirements

Important controls:

• Verify signatures on SAML assertions / OIDC tokens
• Validate issuer, audience, nonce, timestamps
• Enforce HTTPS only
• Encrypt secrets at rest
• Support certificate rotation
• Use short-lived sessions
• Protect against replay attacks
• Log authentication events
• Support MFA at IdP level
• Restrict login domains by tenant

---

8) UX considerations

Good SaaS SSO UX usually includes:

• Email-first login page
• “Sign in with SSO” button
• Domain discovery
• Error messages for misconfiguration
• Admin setup wizard
• Test connection button
• Metadata upload / OIDC discovery URL support

Example admin setup fields:

• SSO enabled checkbox
• Domain(s)
• Protocol selection
• Metadata URL or upload
• Certificate rotation
• Group mapping rules
• JIT provisioning toggle

---

9) OIDC implementation outline

If using OIDC:

Flow

• Redirect user to authorization endpoint
• Receive code
• Exchange code for tokens
• Validate ID token
• Create session

Validate:

• iss
• aud
• exp
• nonce
• signature using JWKS

---

10) SAML implementation outline

If using SAML:

Flow

• SP initiates auth request
• Redirect to IdP
• Receive SAML response
• Validate:
  • XML signature
  • audience
  • issuer
  • recipient
  • timestamps
• Extract NameID / attributes
• Create session

---

11) Multi-tenant routing

How to detect which tenant to use:

• Email domain matching
• Subdomain routing (acme.yoursaas.com)
• Tenant chooser page
• Organization-specific login URL

Best approach:

• Support domain-based discovery
• Also allow explicit org URL for enterprise customers

---

12) Audit and observability

Log:

• login success/failure
• tenant matched
• IdP used
• provisioning events
• role mapping changes
• deprovisioning events

Track:

• SSO error rates
• failed assertions/tokens
• login latency
• certificate expiry

---

13) Recommended architecture

A clean SaaS SSO design often looks like:

• Auth service: handles SSO callbacks and session creation
• Tenant config service: stores IdP settings
• User identity service: maps external identities to internal users
• Provisioning service: SCIM/JIT user lifecycle
• Audit log service: records auth and admin actions

---

14) Libraries / tools

Common libraries:

OIDC

• Node.js: openid-client
• Python: authlib
• Java: Spring Security OAuth2 Client
• Go: coreos/go-oidc

SAML

• Node.js: passport-saml, samlify
• Python: python3-saml
• Java: Spring Security SAML
• .NET: ITfoxtec.Identity.Saml2

---

15) Practical MVP plan

If you want a fast and solid MVP:

1. Build email-based tenant discovery
2. Support OIDC login
3. Store tenant IdP config securely
4. Implement token validation
5. Add user auto-provisioning
6. Add admin setup UI
7. Add audit logs
8. Add SCIM later
9. Add SAML after OIDC is stable

---

16) Common mistakes

Avoid these:

• Using email as the only identity key
• Not validating token/audience/signature
• Ignoring tenant isolation
• No certificate rotation support
• No SCIM/deprovisioning plan
• Mixing auth and authorization
• Hardcoding one IdP for all tenants

---

If you want, I can also provide:

1. a reference architecture diagram,
2. a database schema for tenant SSO configs, or
3. a sample implementation in Node.js / Python / Java.