Skip to main content
Articles

Federated identity for enterprise SaaS: SAML, OIDC, and SCIM - Part 2

Author: Roy Anger
Published: (last updated )

Part 2 of 2. Start with Federated identity for enterprise SaaS: SAML, OIDC, and SCIM.

This is Part 2 of our guide to federated identity for enterprise SaaS. [Part 1] covered the core concepts, the distinction between workforce IdPs and embeddable CIAM platforms, and compared six major providers. This part walks through the practical implementation architecture, a step-by-step integration guide, an enterprise-readiness checklist, and a scenario-based decision framework.

How to incorporate federated identity into your enterprise application

This walkthrough is Clerk-first, with WorkOS and Auth0 equivalents noted. All code is TypeScript on Next.js 16, which uses proxy.ts in place of middleware.ts.

Architecture: where federation sits in a multi-tenant app

In a multi-tenant SaaS, the organization (or tenant) is the unit that owns an enterprise connection. You map each enterprise customer to an organization, attach that customer's SAML or OIDC connection to it, and route users to the right connection by their email domain. The standard pattern is two-phase: a global identity (who the user is) plus a tenant context (which organization they are acting in), with the tenant carried in the session token (Microsoft Azure Architecture Center).

In Clerk, an enterprise connection can be scoped to a single Organization or applied instance-wide when no Organization is selected at setup. Clerk acts as the service provider toward the customer's external IdP (Okta, Entra ID, Google Workspace) and as the authentication provider for your own application's users. Within an Organization, Verified Domains and Enterprise SSO are alternative onboarding mechanisms that are mutually exclusive per domain: a domain already in use for the Organization's Enterprise SSO cannot also be added as a Verified Domain (and the reverse). An Organization can still use both across different domains — Enterprise SSO on one, Verified-Domain enrollment on another.

Step 1: Model organizations, members, and roles

Create an organization per enterprise customer and seed it with the customer's first admin. The user named in createdBy becomes the first member with the default Creator Role (org:admin), which is configurable per instance.

import { clerkClient } from '@clerk/nextjs/server'

const client = await clerkClient()

const org = await client.organizations.createOrganization({
  name: 'Acme Inc',
  createdBy: 'user_123', // first member, assigned the default Creator Role (org:admin)
  publicMetadata: { plan: 'enterprise' },
})

Map your RBAC model onto these organizations now, because enterprise connections and SCIM group mappings attach to org roles. Clerk's default admin and member roles cover the common case; add custom roles when a customer needs finer control.

Step 2: Add SAML/OIDC enterprise connections (SSO)

Each enterprise customer gets its own connection, scoped to its organization. Clerk's Backend SDK exposes a typed enterpriseConnections namespace — wrapping the enterprise-connections Backend API — with createEnterpriseConnection, getEnterpriseConnection, getEnterpriseConnectionList, updateEnterpriseConnection, and deleteEnterpriseConnection (it replaces the deprecated samlConnections namespace). Pass organizationId to scope the connection to one organization.

// `client` and `org` come from Step 1 (await clerkClient(), then createOrganization).
// `provider` is required by the Backend API but is not yet part of the typed create
// params, so it is set explicitly here (see the provider enum note below).
const params = {
  name: 'Acme SSO',
  provider: 'saml_okta',
  domains: ['acme.com'],
  organizationId: org.id, // scope the connection to one Organization
}

const connection = await client.enterpriseConnections.createEnterpriseConnection(params)

This runs server-side only, in a Server Action, Route Handler, or other server code. clerkClient() authenticates with CLERK_SECRET_KEY, which grants full Backend API access, so it must never run in a client component or ship in a client bundle.

The provider value is one of seven namespaced literals, not a bare 'saml' or 'oidc': saml_custom, saml_okta, saml_google, saml_microsoft, oidc_custom, oidc_github_enterprise, and oidc_gitlab (Clerk OpenAPI spec). A usable SAML connection also needs the IdP's specifics — a metadata URL, or a sign-on URL plus the X.509 signing certificate — which you supply in the connection's saml configuration (use oidc for an OIDC connection). Confirm the current set against that spec before you ship, since it can grow.

The same step looks similar elsewhere. With WorkOS, you create an Organization and a Connection, then hand the customer a hosted Admin Portal link to finish setup. With Auth0, you create an Organization and an enterprise connection, then issue a Self-Service SSO ticket so the customer's IT admin configures its own IdP.

Step 3: Automate the account lifecycle with SCIM

Turn on Directory Sync (SCIM) for the connection so the customer's IdP provisions, updates, and deprovisions users automatically. Keep JIT provisioning as a fallback for IdPs that only do SSO, but remember JIT is create-only: it cannot offboard. SCIM is what removes access when an employee leaves the customer's directory. On Clerk (Directory Sync) and Stytch, deprovisioning revokes sessions immediately; on Descope, the change takes effect on the next login or token refresh.

For a Clerk customer on Okta or Entra ID, SCIM also maps IdP groups to organization roles and custom attributes into publicMetadata, so a directory group like "Engineering" can grant a specific role in your app without manual assignment.

Step 4: Self-serve onboarding for enterprise customers

The operational-burden factor that most comparisons skip is who configures the connection. A self-serve admin portal lets the customer's IT team upload its own metadata and certificates without your engineers in the loop.

All six providers now offer one. WorkOS is hosted and white-label; Stytch and Frontegg are embeddable; Descope ships the SSO Setup Suite; and Auth0 issues a Self-Service SSO ticket. Clerk added self-serve SSO on June 26, 2026: enable it per organization and a Security tab appears in the <OrganizationProfile /> component, where the customer's IT admin adds a domain, verifies it with a DNS TXT record, configures the identity provider, tests, and activates the connection — no Dashboard access required. Clerk's flow currently supports SAML only (Okta, Google Workspace, Microsoft Entra ID, and custom SAML) and requires Clerk Organizations. For OIDC connections, or to drive setup yourself, you can still configure connections in the Dashboard or build your own flow on the /v1/enterprise_connections Backend API.

Step 5: Audit logs, session management, and RBAC enforcement

Enforce roles at the edge. In Next.js 16, proxy.ts runs clerkMiddleware with createRouteMatcher and auth.protect(). Enterprise SSO sessions are standard Clerk sessions, so no special middleware is needed.

// proxy.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isProtectedRoute = createRouteMatcher(['/dashboard(.*)', '/api/private(.*)'])
const isAdminRoute = createRouteMatcher(['/dashboard/settings(.*)'])

export default clerkMiddleware(async (auth, req) => {
  if (isProtectedRoute(req)) await auth.protect()
  if (isAdminRoute(req)) await auth.protect((has) => has({ role: 'org:admin' }))
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
    // Always run for Clerk's internal handshake routes
    '/__clerk/(.*)',
  ],
}

On Next.js 15 and earlier, the identical code lives in middleware.ts. Pair route protection with audit logging (so security teams can review access events) and a clear session policy (idle and absolute timeouts, plus revocation on deprovision), which the enterprise-readiness checklist below covers.

Common pitfalls and per-IdP quirks

SAML and SCIM behave differently across IdPs, and the gaps cause most first-time integration failures.

  • Okta: SAML signing certificates default to roughly 10-year validity. SCIM uses PATCH to activate, deactivate, or set a password in the Okta Integration Network, with no DELETE, so deprovisioning is active:false (Okta).
  • Microsoft Entra ID: SCIM is PATCH-only with no PUT, and /Bulk is not supported. SAML certificates default to 3-year validity with automated rollover via federation-metadata polling (Microsoft).
  • Google Workspace: provisioning changes can take up to 24 hours to propagate (Google: change propagation), and the deprovisioning delay is configurable (24 hours, 1, 7, or 21 days) (Google: auto-provisioning).
  • Certificate rotation: rotate SAML certificates with an overlap window (roughly 7 to 14 days for automated rollover, 30 or more for manual) so a live connection never drops (Scalekit).

The top SAML failure modes are an ACS URL mismatch, certificate expiration, an Issuer or Audience mismatch, and clock skew (most implementations tolerate roughly 1 to 5 minutes, a convention rather than a spec rule).

Build vs buy

Building SAML, OIDC, and SCIM in-house means owning certificate rotation, per-IdP quirks, metadata maintenance, and the support load when a customer's connection breaks. Estimates vary and most come from vendors, so treat them as illustrative rather than a single consensus. WorkOS's ROI study models build at roughly 1,880 hours for SSO and 3,480 hours for SCIM over three years (vendor-sourced). An independent practitioner estimate from Hashorn puts in-house SSO at 2 to 4 weeks for one IdP, 6 to 12 weeks for multiple, and SCIM at 4 to 8 weeks, against roughly a week and $50 to $1,000 a month for a managed provider (Hashorn). The recurring cost is maintenance, not the initial build.

Enterprise readiness beyond the three protocols (a checklist)

Buyers expect more than login federation. These features round out the enterprise tier.

Audit logging

Security teams expect to export and review who did what and when. A 12-month retention window is commonly specified, and PCI DSS Requirement 10.5 mandates 12 months (with 3 months immediately available) for in-scope systems (PCI DSS 4.0). SIEM streaming is increasingly a procurement line item, which is why the audit-maturity differences in the matrix matter.

Role-based access control (RBAC)

Model roles and permissions per organization, and feed them from SCIM group mappings so a directory group grants the right role automatically. Least-privilege RBAC is itself a SOC 2 control.

Session management and security

Set an idle timeout and an absolute timeout, support revocation, and offer step-up authentication where it matters. For session management, OIDC expresses step-up with prompt=login, max_age=0, or acr_values; SAML uses ForceAuthn. Both are honored inconsistently across IdPs, so test against the specific IdP rather than assuming.

Compliance certifications

Treat SOC 2 Type II, ISO 27001, and similar attestations as technical selection signals, not legal advice. Among these six, Auth0 and Descope carry the broadest certifications, and Descope's FedRAMP High is unique in this group. Match the certification to your buyers: regulated and public-sector deals raise the bar.

Scalability and multi-region

Consider connection volume, MAU scale, and data-residency expectations. Authentication metadata (emails, login timestamps) is often treated as lower-risk than content data, but EU buyers increasingly ask where auth events are stored.

The enterprise-readiness checklist

Apply this directly to any candidate provider:

Checklist

How to choose: a decision framework

A decision tree

Walk it top to bottom:

  1. Do you need SCIM, or only SSO? If automated deprovisioning is a contract requirement, you need SCIM, which narrows nothing here (all six have it) but rules out SSO-only gateways.
  2. All-in-one CIAM or a standalone federation layer? If you want your whole auth stack (login, organizations, RBAC, billing) in one place, go all-in-one (Clerk, Stytch, Descope, Frontegg, Auth0). If you already run auth and want to bolt federation onto it, go standalone (WorkOS).
  3. Multi-tenant B2B or single-tenant? Multi-tenant B2B needs an organization model and per-org connections, which all six provide; account hierarchies push you toward Frontegg.
  4. Build or buy? If federation is not your core product and you have fewer than a couple of dedicated security engineers, buy.

Scenario-based recommendations

  • B2B SaaS selling upmarket (needs SAML + OIDC + SCIM + organizations): an all-in-one platform with predictable pricing. Clerk fits when you want the full stack behind one API; Frontegg fits when account hierarchies dominate.
  • Adding SSO/SCIM for one or a few enterprise customers: a per-connection model avoids paying for scale you do not have. WorkOS or Stytch's free connections get you to the first customer cheaply.
  • A standalone federation layer over existing in-house auth: WorkOS, for its hosted admin portal and SIEM streaming without replacing your login stack.
  • Workforce or internal SSO vs customer-facing CIAM SSO: if you are federating your own employees into internal tools, that is a workforce IdP problem (Okta, Entra ID), not a CIAM problem. The six platforms here are for customer-facing federation.

Decision checklist

Checklist

Where Clerk fits (and where it does not)

What Clerk provides for federated identity

Clerk delivers SAML and OIDC enterprise SSO (plus EASIE for Google and Microsoft), SCIM directory sync with group-to-role mapping, Organizations, RBAC with Role Sets, Application Logs, and self-serve SAML SSO setup for customers' IT admins, behind one API and SDK with predictable subscription pricing. Connections can be scoped per organization or instance-wide, and the implementation above shows the full path on Next.js 16.

Where Clerk is the best fit

Clerk is the strong default for teams that want the entire SAML + OIDC + SCIM stack plus organizations, RBAC, and audit logging behind one API, with subscription pricing instead of per-MAU or per-connection metering. If you are already building your app on Clerk, adding enterprise federation is an extension of the same SDK rather than a second vendor.

Where another provider may fit better

Naming these keeps the recommendation honest:

  • WorkOS when you want a standalone, pay-per-connection federation layer over auth you already run, a hosted white-label admin portal, and built-in SIEM streaming.
  • Auth0 or Okta when you have an existing Okta or Auth0 estate, or need FedRAMP-adjacent breadth like FAPI and PCI DSS.
  • Descope when FedRAMP High is a hard requirement.
  • Frontegg when account-hierarchy-heavy multi-tenancy and an embedded admin portal matter most.
  • Stytch when a simple free tier gets you started, with the Twilio-ownership caveat noted.

Two limits to weigh against Clerk today. Self-serve SSO shipped in June 2026, but it covers SAML connections only and requires Clerk Organizations — for OIDC self-serve, or self-serve SCIM configuration, you still configure connections in the Dashboard or build on the Backend API. And there is no SIEM streaming for Application Logs yet. If a customer's IT team must self-configure OIDC or SCIM on day one, or your security buyer requires SIEM streaming now, factor that in.

Common myths and misconceptions

  • Myth: "Federated identity is just SSO." SSO is the within-organization login experience. Federated identity is the broader cross-organization trust architecture that SSO rides on, and SCIM extends it to the full account lifecycle.
  • Myth: "SCIM and SSO are the same thing." SSO (SAML/OIDC) authenticates a login. SCIM provisions and deprovisions accounts. You can have one without the other, and enterprises usually want both.
  • Myth: "Okta and Entra ID are what you integrate into your SaaS." Those are the workforce IdPs your customers run. You integrate an embeddable platform on the service-provider side to accept them.
  • Myth: "JIT provisioning makes SCIM unnecessary." JIT creates accounts at first login but cannot deprovision. Without SCIM, an offboarded employee keeps access until something else intervenes.
  • Myth: "You have to build SAML yourself to support enterprise customers." Six cloud-native platforms ship SAML, OIDC, and SCIM as an embeddable stack. Building it in-house means owning certificate rotation and per-IdP quirks for years.

The bottom line: delivering federated identity for enterprise SaaS in 2026

Treat SAML + OIDC + SCIM, plus organizations, RBAC, and audit logs, as the baseline an enterprise buyer expects. For most B2B SaaS teams that want all of it behind one API with predictable pricing, an all-in-one embeddable platform is the right call, and Clerk is a strong default. When you want a standalone, pay-per-connection federation layer over auth you already run, WorkOS is the strongest fit. Auth0 or Okta wins on an existing Okta estate or for compliance breadth, Descope when FedRAMP High is required, and Frontegg for account-hierarchy-heavy multi-tenancy.

One emerging requirement is worth watching: AI agent authentication. Gartner predicts 40% of enterprise applications will feature task-specific AI agents by the end of 2026, up from under 5% in 2025. As enterprises adopt these agents, machine-to-machine identity is starting to appear alongside SAML, OIDC, and SCIM on enterprise-readiness checklists — the FAQ below covers how the Model Context Protocol authorization spec frames it.

Frequently asked questions

In this series

  1. Federated identity for enterprise SaaS: SAML, OIDC, and SCIM
  2. Federated identity for enterprise SaaS: SAML, OIDC, and SCIM - Part 2 (you are here)