Directory Sync - How to Provision Users onto Your SaaS App From Microsoft Entra, Google Workspace and More
Learn how to use Directory Sync to provision users from your SaaS app to any IdP.
If you're building a SaaS app for enterprise customers in 2024, Directory Sync is a must-have.
Otherwise, your customers’ IT teams will have to manually provision or de-provision each employee to your app one by one – and that doesn't scale.
To support directory sync, your app needs to provision users onto your platform from your enterprise customers' directories, including Microsoft Entra ID (formerly Azure AD), Okta, OneLogin, Google Workspace, or even Workday.
In this article, we’ll explore Directory Syncing and help you understand exactly what it is, and why you need to add it to your app. You’ll also learn how to implement Directory Syncing from scratch - and why it’s often better to outsource Directory Syncing to a third-party provider.
What is Directory Syncing?
Directory Syncing is the process of synchronizing user data in an organization’s directory service such as Microsoft Entra, Google Workspace, or Okta with your app’s user data.
It’s typically enabled through an integration between your enterprise customer's directory and your SaaS app using the SCIM protocol, a REST-based standard for provisioning and deprovisioning user accounts.
Specifically, you configure your SCIM integration to automatically create, update, or delete user accounts in your system based on changes in the customer’s directory. This could be when new employees join, existing ones leave, their details (like names or email addresses) change, or their roles and permissions are updated.
For enterprises that use hundreds or thousands of apps, Directory Syncing significantly reduces the time and effort that goes into provisioning or de-provisioning users.
Imagine a scenario where an IT admin has to manually create accounts and grant access to multiple apps for each newly onboarded employee, or change their access levels when their role changes or they leave the company, which for big companies can be daily. Aside from being a long, drawn-out process, manually doing this could lead to errors when assigning or revoking access.
Some employees might retain access to some accounts long after leaving the company. Worst yet, a former employee could retain critical system and data access for a period after being terminated.
Directory Syncing solves this.
By synchronizing user data with apps used within the company, admins can ensure that changes, such as user additions, modifications, or deletions, are consistently reflected across all applications used within the organization, including yours.
Read more: As a Developer, why should you support Directory Sync?
Which directories should you sync with?
The directories your app should sync with depend on the specific Identity Providers (IdPs) used by your enterprise customers.
Ultimately, if enterprise sales are going to be a serious channel for your business, you’ll want to support Directory Sync with as many IdPs as possible. No one wants a deal to be held up for a couple of weeks while engineering validates and builds another directory integration.
Here are some widely used corporate directories you might need to sync with:
- Microsoft Entra ID (formerly known as Azure AD)
- Okta
- Google Workspace/Cloud identity
- Active Directory
- OneLogin
- PingFederate
- JumpCloud
- Workday
- BambooHR
The most popular standard for Directory syncing is SCIM, a protocol designed expressly for this purpose.
How Directory Syncing with SCIM works
SCIM (System for Cross-domain Identity Management) provides a standardized approach for provisioning, updating, and de-provisioning user accounts and associated data between identity providers and SaaS apps via a REST API.
It defines several API endpoints ( /Users and /Groups) for creating and manipulating user data. It also defines a schema that specifies how Users and Group data should be structured and the attributes they should have, like names, ids, email addresses, and phone numbers.
Read more: What is SCIM?
To synchronize user data, you need to build a SCIM API in your SaaS app containing endpoints that directories can talk to, to provision users or groups in your app.
Here are a few examples of endpoints you might have:
- Create a new user: POST https://scim-server.example/scim/v2/Users
- Delete a user: DELETE https://scim-server.example/scim/v2/Users/{id}
- Read all groups: GET https://scim-server.example/scim/v2/Groups
And here’s how it works:
When a new user is registered in your customer’s directory, your SCIM endpoint (for example, POST /Users) receives a request containing the new user's information. You then process this request by creating a matching user account in your system.
For updates, such as when a user's details change, the directory sends a request to a specific SCIM endpoint in your API with the user’s ID (using either PUT /Users/{id} or PATCH /Users/{id}) along with the updated user information. Your system uses this data to either update the existing user account.
Similarly, if a user is deleted from the directory, your system will receive a DELETE /Users/{id} request. You will then use this ID to either deactivate or permanently delete the user's account from your system.
By providing a common language to communicate, SCIM standards make it easy to synchronize user data between your app and multiple directories. And, in a perfect world, you’d only need to create one SCIM integration for all the directories you support.
But that’s not usually the case. Here’s why:
SCIM has two major versions – 2.0 and 1.1 – and they don’t usually work well together. Plus, different directories implement SCIM differently. For example, one directory might be using custom user attributes that another doesn’t use. You need to account for these variations when implementing Directory Syncing with SCIM.
Read More: How each Identity Provider handles deprovisioning with SCIM
Implementing Directory Sync: Building from scratch
To implement Directory Sync using SCIM in your app, you’ll need to do the following:
- Build a SCIM API with endpoints for provisioning and deprovisioning users. Your endpoints should have the appropriate logic to add or remove user accounts, create and manage permission groups, and update user and group attributes in response to SCIM requests from your customer’s directories.
- Connect your SCIM endpoint to the directories to start receiving provisioning and deprovisioning requests.
While this might seem simple, it can be tedious. So before you start building, ask yourself the following questions:
How much effort and time will you need to support multiple identity providers?
While SCIM provides a standardized way of representing user schemas, it leaves it up to the directory service to choose which attributes to use and the kind of data to store in these attributes. Some directory services even allow enterprises to add their own custom attributes.
Before syncing your app’s data with your client’s, you’ll likely have to talk to the IT teams of your enterprise clients to know what attributes they use and how they’re using them, then map these attributes to your app’s data model.
Also, you’ll need to normalize or standardize the data you pull from different directory providers to avoid storing duplicate information.
This may take a while to set up especially if you’re supporting multiple clients.
Various IdPs may also handle user suspension and deletion differently, especially for users who are part of an access group.
For example, Microsoft Entra does not suspend a user if they remain part of any provisioned groups while JumpCloud suspends a user only if they’re deprovisioned from the groups they were provisioned through.
The inconsistencies can introduce security risks into your app. A user may end up retaining access to groups they shouldn’t simply because the IdP your client uses didn’t communicate with your app.
It’s therefore important to understand how each IdP you’re supporting handles user deprovisioning to avoid these risks and then write logic that processes each request accurately.
Do you have time and resources to put into support and ongoing maintenance?
You’ll need to maintain your custom directory sync constantly. When you bring in a new customer, you’ll have to set up a new integration with the directory service they use. And, should any of the directory providers you support have software updates or change the way they do things, you’ll need to update your integration to keep everything running smoothly.
Do you have the resources to onboard new organizations with hundreds or thousands of users?
Enterprise IT admins need to provision lots of users to your app. This can be a single employee who’s just joined the company or an entire department. Your app needs to be able to process bulk provisioning and deprovisioning requests at scale without going down.
Additionally, like with any system that processes high-volume requests, concurrent updates to the same resource can result in out-of-sequence processing.
Consider this scenario – two admins, working independently, attempt to update the same user’s information at the same time. One admin’s change might overwrite the other’s change and a user might end up having access they shouldn't have. The worst part is, these inconsistencies might not be mirrored in your customer’s directory leading to a discrepancy between the intended and actual access permissions for the user. You must have strategies in place to regularly synchronize updates.
Implementing Directory Sync: Using WorkOS
If you’d rather not deal with the headaches of implementing Directory Sync yourself, use a third-party SCIM provider like WorkOS.
Directory Sync by WorkOS is a set of developer-friendly APIs and IT admin tools that allows you to easily add enterprise-grade User Lifecycle Management into your app.
Here’s how WorkOS addresses the issues above:
- It saves time and effort during onboarding: WorkOS comes with a beautifully designed Admin Portal, which you can (manually or programmatically) send to your customer’s IT team. The portal will guide them through the full setup process and allow them to configure connection details and more importantly, map out each of their attributes. No back-and-forth is required.
- It normalizes data from multiple identity providers: WorkOS supports dozens of IdP systems, like Microsoft Entra, Okta and Google Workspace, as well as popular HRIS (Human Resources Information Systems) like Workday and BambooHR. WorkOS normalizes the attributes from each of these IdPs and presents them in a standardized format.
- It provides real-time updates via the Events API: Directory Sync comes with an Events API, which streams in real-time events to your app every time a change is made in your customer’s directory. The Events API delivers these events in order so you don’t have to worry about out-of-sequence security risks. Additionally, you can process the events at your own pace and avoid overwhelming your system with hundreds of requests at once.
Ready to get started with Directory Sync by WorkOS?