What Are Directory Integrations? (2026 SaaS Architecture Guide)

A directory integration is an automated connection between your B2B SaaS product and your customer's central identity provider (IdP)—Okta, Microsoft Entra ID, Google Workspace, JumpCloud—that synchronizes user accounts, groups, roles, and lifecycle events into your application. If an enterprise prospect asks "do you support directory sync?" and you don't have a good answer, you're about to lose a deal—a painful reality we've discussed in our guide on building integrations your sales team actually asks for.

This guide covers what directory integrations are, why enterprise buyers treat them as non-negotiable, the real architectural tradeoffs between SCIM and API-based approaches, and how to ship directory sync without burning six months of engineering time.

What Is a Directory Integration?

A directory integration connects your SaaS application to the authoritative source of identity data in your customer's organization. That source is typically an Identity Provider (IdP) like Okta, Microsoft Entra ID, or Google Workspace.

The integration handles three core jobs:

• Provisioning — When a new employee is added to the IdP, their account is automatically created in your app with the correct role and permissions.
• Attribute sync — When profile data changes (department, title, manager), those updates propagate to your app automatically.
• Deprovisioning — When an employee leaves or changes roles, their access is revoked in your app without anyone filing a ticket.

This is fundamentally different from SSO. SAML handles authentication and single sign-on. SCIM handles user provisioning, updates, and deprovisioning. They are complementary, not interchangeable. SSO answers "can this person log in?" Directory sync answers "should this person exist in our system at all?"

Directory integrations are a specific type of customer-facing integration—they're multi-tenant, user-authenticated, and embedded in your product experience. Your customer's IT admin configures the connection, and your app receives identity data for their entire organization.

Why Enterprise Customers Demand Directory Sync

The short answer: manual user management does not scale, and the security consequences of getting it wrong are severe.

On average, companies now use 106 SaaS applications, down 18% from the 2022 peak of 130. Large enterprises with over 5,000 employees still used the most, averaging 131 apps. Every one of those apps needs user accounts created, updated, and eventually removed—which is why automated provisioning is a core part of what enterprise buyers expect in 2026.

Companies with 1,000 employees using five different SaaS applications spend approximately 216 hours annually just managing user changes manually. That's five full work weeks of an IT admin's time—on just five apps. Scale that to 100+ apps and the math breaks completely.

The security side is worse. An orphaned account is a user account that retains access to applications and systems on a network without an active owner. When employees depart suddenly or amid organizational restructuring, proper account deprovisioning procedures often fall through the cracks. Manual deprovisioning processes contribute significantly to this issue. When an employee leaves a company, IT cannot log into 106 different administrative panels to revoke access. If your SaaS app requires manual offboarding, it becomes a security liability.

The financial impact compounds fast. License waste continues to rise. Organizations are wasting an average of $21M annually on unused SaaS licenses, a 14.2% increase year-over-year. A meaningful chunk of that waste comes from orphaned accounts that were never deprovisioned—seats you're paying for that nobody uses.

For many enterprise buyers, SCIM support is a contractual requirement. If your product can't connect to their directory, you won't pass procurement. It's that simple, and it's a primary reason why your integration strategy must evolve as you move upmarket.

SCIM vs. API-Based Directory Integrations: When to Use Each

There are two fundamentally different approaches to directory integration, and understanding when to use each matters more than most teams realize.

SCIM (Push-Based Provisioning)

SCIM (System for Cross-domain Identity Management) is an open standard that defines how identity data should be exchanged between systems. Technically, SCIM is a set of APIs that allows you to manipulate the users and group objects and expose these data as JSON through the REST endpoints.

With SCIM, your SaaS app exposes a SCIM server endpoint. The customer's IdP (the SCIM client) pushes changes to you:

sequenceDiagram
    participant IdP as Customer's IdP<br>(Okta / Entra ID)
    participant App as Your SaaS App<br>(SCIM Server)
    IdP->>App: POST /scim/v2/Users (new hire)
    App-->>IdP: 201 Created
    IdP->>App: PATCH /scim/v2/Users/{id} (role change)
    App-->>IdP: 200 OK
    IdP->>App: PATCH /scim/v2/Users/{id} (set active=false)
    App-->>IdP: 200 OK (deprovisioned)

The advantage: changes propagate in near real-time, and your customer's IT team manages everything from their IdP console. You don't need API credentials to their directory.

The reality: SCIM implementations are notoriously fragmented. Microsoft Entra ID's interpretation of SCIM differs from Okta's. Many smaller or legacy directory tools don't support SCIM at all, leaving a massive blind spot in your coverage.

API-Based Directory Sync (Pull-Based)

The alternative is to pull user data directly from the IdP's REST API. Your app authenticates with the customer's directory (via OAuth or API key) and periodically fetches users, groups, and membership data.

This approach is necessary when:

• The IdP doesn't support outbound SCIM (Google Workspace is the classic example—Google only lets you pull data and doesn't push)
• You need data the SCIM schema doesn't cover (license assignments, activity logs, custom attributes)
• Your customer uses a directory that isn't SCIM-compliant (legacy LDAP systems, smaller IdPs)

For pulling user data from SaaS apps that aren't IdPs at all—pulling user lists from any SaaS app—API-based sync is the only option.

The Honest Tradeoff

Most production systems need both. SCIM for the top IdPs that support it, API-based sync for everything else. Relying exclusively on SCIM ignores the long tail of identity providers that your customers actually use.

The Engineering Cost of Point-to-Point Identity Integrations

Here's where product managers and engineering leads need to pay close attention. Building directory integrations provider-by-provider is significantly harder than it looks on paper.

Start with SCIM. It's supposed to be a standard. In practice:

SCIM offers different ways to implement certain operations, resulting in IDPs having different requirements for what your SCIM API needs to support. Ideally, this is what a standard is supposed to avoid. For example, when updating a User and Group, some IDPs support HTTP PATCH, while others may only support HTTP UPDATE. Okta uses HTTP PATCH only for user activation/deactivation and password sync. According to the Okta documentation, "All other updates to User objects are handled through a PUT method request." Microsoft Entra ID, on the other hand, doesn't support PUT at all and only supports updates via HTTP PATCH. This variability increases implementation effort and complicates interoperability across SaaS apps.

So "implement SCIM" actually means "implement SCIM twice, with different HTTP method support, different attribute mapping rules, and different error handling expectations." And that's before you've touched Google Workspace (pull-only), JumpCloud (its own patterns), or any of the smaller IdPs your enterprise customers use.

Beyond SCIM fragmentation, the non-obvious costs of point-to-point integrations stack up fast:

1. Schema Fragmentation: Google Workspace calls it primaryEmail. Microsoft Graph calls it userPrincipalName. Okta calls it profile.email. Okta represents a user's department as a flat string. Entra ID nests it inside a complex object. Your backend must normalize all of these into a single internal representation.

2. Pagination Divergence: Google Workspace uses pageToken. Microsoft Graph uses @odata.nextLink and OData-style queries. Okta uses HTTP Link headers with cursor-based pagination. Your synchronization jobs must implement completely different cursor logic for every provider, each with different behavior when underlying data changes mid-pagination.

3. OAuth Token Lifecycle Management: Each directory provider has different OAuth flows, token expiry durations, and refresh behaviors. Bearer tokens were the easy part. Managing OAuth 2.0 authorization code flows, storing refresh tokens securely, and handling invalid_grant errors requires dedicated infrastructure. If a token expires silently at 2 AM, your directory sync stops, and offboarded employees retain access to your app.

4. Rate Limits: Azure AD polls your SCIM endpoint periodically (about every 40 minutes) and whenever an admin makes a change. Rate limits on outbound API calls to Google's Directory API are aggressive. You need per-provider backoff strategies.

Two integrations per quarter is a realistic pace for a team building these from scratch. If your enterprise customers use five or six different IdPs, that's over a year just for directory sync. Every new identity provider requires a new code path, new tests, and ongoing maintenance when APIs inevitably deprecate endpoints.

Architecting a Unified User Directory API

The alternative to point-to-point connectors is a unified directory API—a single interface that normalizes users, groups, roles, and lifecycle events across all identity providers into one consistent schema.

Instead of writing if (provider === 'okta') { ... } else if (provider === 'google') { ... }, your application makes a single request to a unified endpoint. The underlying platform handles the translation.

graph TD
    A[Your SaaS Application] -->|GET /unified/users| B(Unified API Layer)
    B -->|Translates Schema & Pagination| C{Proxy API Layer}
    C -->|Microsoft Graph API| D[Entra ID]
    C -->|Admin SDK API| E[Google Workspace]
    C -->|Okta REST API| F[Okta]
    C -->|Directory API| G[JumpCloud]

A concrete example:

# List users from any connected directory — same call, same schema
curl https://api.truto.one/unified/user-directory/users \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Integrated-Account-Id: CUSTOMER_DIRECTORY_ACCOUNT_ID"

The response comes back in a normalized format regardless of whether the customer uses Okta, Entra ID, Google Workspace, or JumpCloud:

{
  "results": [
    {
      "id": "usr_abc123",
      "email": "jane.doe@acme.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "status": "active",
      "department": "Engineering",
      "title": "Staff Engineer",
      "manager_id": "usr_xyz789",
      "groups": [
        { "id": "grp_001", "name": "Platform Team" }
      ],
      "roles": [
        { "id": "role_admin", "name": "Admin" }
      ]
    }
  ],
  "next_cursor": "eyJsYXN0X2lkIjogMTIzfQ=="
}

Your application writes one integration against this schema. Whether the customer connects Google Workspace or JumpCloud, your code remains untouched.

How the Unified Layer Works Internally

Truto's Unified User Directory API takes this approach. The architecture uses a generic execution engine with declarative configuration—no integration-specific code paths in the runtime logic:

1. Integration Configs: A declarative configuration defines how to communicate with each third-party API—its base URL, authentication scheme, and pagination strategy.
2. Declarative Mappings: The translation between the unified schema and the native provider schema is handled by declarative expressions. When Okta returns users in one format and Entra ID returns them in another, the mapping layer reshapes the JSON on the fly—not if/else branches in your codebase.
3. Credential Management: The platform proactively refreshes OAuth tokens ahead of expiry, abstracting token lifecycle management away from your core application logic.

This architecture means adding support for a new directory provider doesn't require deploying new code. It's a data operation—a new configuration that describes the provider's API surface and the mapping to the unified schema.

Automating Provisioning and Deprovisioning with Unified Webhooks

Batch synchronization—polling a directory API every 24 hours—is insufficient for security-critical events like employee terminations. Deprovisioning must happen in real-time.

This requires webhooks. But handling webhooks from dozens of different IdPs introduces the same fragmentation issues as REST APIs. Every provider delivers events differently. Okta uses event hooks with its own payload format. Entra ID uses Microsoft Graph change notifications. Google Workspace uses push notifications through a completely different channel mechanism. Each signs payloads differently and structures event data uniquely.

A unified webhook layer normalizes these provider events into canonical event types:

{
  "event_type": "record:updated",
  "resource": "users",
  "unified_model": "user-directory",
  "data": {
    "id": "usr_abc123",
    "email": "former.employee@acme.com",
    "status": "deactivated"
  },
  "integrated_account_id": "ia_xyz789",
  "timestamp": "2026-04-02T14:30:00Z"
}

Instead of parsing Okta's user.lifecycle.deactivate and Google's admin.directory.user.delete, your application subscribes to one webhook format and handles all directory providers identically. When a record:deleted or record:updated event arrives for a user whose status changed to deactivated, your deprovisioning logic fires immediately—revoking active sessions and API keys the millisecond an IT administrator disables an account in the central directory.

For cases where a provider doesn't support outbound webhooks natively, scheduled sync jobs can poll the directory API at short intervals and emit synthetic events when changes are detected, delivering them to your webhook endpoint in the same normalized format.

What This Looks Like in Practice

Here's a realistic architecture for a B2B SaaS product that needs directory integration across its customer base:

flowchart LR
    A[Customer's IdP<br>Okta / Entra ID /<br>Google Workspace] -->|OAuth + API Calls| B[Unified Directory API]
    B -->|Normalized Users,<br>Groups, Roles| C[Your SaaS App]
    A -->|Provider Events| D[Unified Webhooks]
    D -->|Canonical Events<br>record:created<br>record:updated<br>record:deleted| C
    C -->|Provision / Deprovision| E[Your User Database]

Your app maintains a single integration path. New directory providers become available without code changes on your side. Your customer's IT admin connects their IdP through an embedded authentication flow, and sync starts automatically.

This is how you go from "we support Okta and Entra ID" to "we support any directory your customers use" without a dedicated integrations team.

Where to Go From Here

Directory integrations aren't a feature you can put off if you're selling to enterprises. SCIM has become a core requirement for modern onboarding architecture. The right SCIM implementation makes it easier to support delegated administration, directory-driven access control, and audit-ready user management without introducing brittle scripts or manual workflows. For developers, SCIM is no longer just an IT checkbox, but a product capability that directly impacts enterprise adoption, security posture, and operational scalability.

The practical path forward:

1. If you're starting from zero, don't build SCIM server endpoints and per-provider API connectors in parallel. Pick a unified directory API that handles both patterns, and ship coverage across Okta, Entra ID, and Google Workspace in one sprint instead of three quarters.
2. If you've already built Okta and Entra ID, audit your connectors for the edge cases that break in production: token refresh failures, pagination drift, and the PATCH-vs-PUT mismatch that causes silent sync failures.
3. If you need real-time deprovisioning, layer unified webhooks on top of your directory sync. Polling every 40 minutes isn't fast enough when the requirement is "revoke access immediately when someone leaves."

The gap between "we support directory sync" and "our directory sync actually works reliably across every IdP our customers use" is where deals are won or lost. Close that gap with architecture, not headcount.