Skip to main content
Cluely uses WorkOS’s Directory Sync to manage user access to the Cluely platform. Information below on Directory Sync is from WorkOS’s documentation.

​
Introduction

Organizations use company directories and HRIS systems to manage users and enforce their access to organization resources. Directories enable IT admins to activate and deactivate accounts, create groups that inform access rules, accelerate adoption of new tools, and more.

​
Definitions

ULM : User Lifecycle Management (or ULM) is the process of managing a user’s access to an app. This occurs from app onboarding until they are removed from an app. ULM is also commonly referred to as identity provisioning. SCIM : System for Cross-domain Identity Management (or SCIM) is an open standard for managing automated user and group provisioning. It’s a standard that many directory providers interface with. HRIS : A Human Resources Information System (or HRIS) is software designed to maintain, manage, and process detailed employee information and human resources-related policies. Examples include: Workday, HiBob, BambooHR, etc. User Provisioning : Provisioning is the process of creating a user and setting attributes for them – inside of an app. User Deprovisioning : Deprovisioning is the process of removing a user from an app.

​
What is Directory Sync?

Directory Sync is a set of developer-friendly APIs and IT admin tools that allows you to implement enterprise-grade User Lifecycle Management (ULM) into your existing app. ULM allows IT admins to centrally provision and deprovision users from their directory provider. A directory provider is the source of truth for your enterprise customer’s user and group lists. Directory Sync sends automatic updates to your app for changes to directories, groups, users, or access rules. Common directory providers include: Microsoft Active Directory, Okta, Workday, and Google Workspace. See the full list of supported directory providers on the integrations page.

​
Why use Directory Sync?

ULM increases the security of your app and makes it easier for your customers to use your app. ULM is most often implemented using SCIM. SCIM requests are sent between directory providers and your app to inform you of changes to a user’s identity. Changes can include:
  • Provisioning an identity for a user (account creation)
  • When a user’s attribute has changed (account update)
  • Deprovisioning a user from your app (account deletion)
Each directory provider implements SCIM differently. Implementing SCIM is often a challenging process and can introduce security vulnerabilities into your app. Directory Sync hides this complexity, so you can focus on building core product features in your app.

​
What your customer experiences

Let’s take a look at two different user provisioning scenarios.

​
(N) Your app doesn’t use Directory Sync

Without ULM, your customers have to manually add, update, and remove users from your app. Imagine a scenario where your customer has purchased your software and onboards a new employee to your app. Your customer would have to do the following:
  1. The IT admin provisions the employee in their directory provider (if they use one) and manually in your app.
  2. All employee information has to be set manually in both the directory provider and your app.
  3. The IT admin has to manually provision a login method for the employee; through either SSO (if they use an identity provider) or a self-registration page.
  4. The IT admin sends the invite link to their employee. Often initiating a back and forth via either email, messaging app, or IT helpdesk ticket.
  5. The employee has to proceed with the registration method and can then use your app.
All future changes to this employee’s data and access are manually entered by the IT admin. This is error prone and can lead to security vulnerabilities where users get unauthorized access to resources. As your customers adopt more cloud software, these manual processes do not scale well. Manual input error can lead to the source of truth (directory) drifting from your app’s state. As a result, ULM has become a table stakes product requirement for enterprises.

​
(Y) Your app uses Directory Sync

If your app supports ULM via Directory Sync, the IT admin can provision this employee from one place:
  1. Add the employee to their directory provider.
  2. Assign the employee to your app with the appropriate role once; via the directory provider admin page.
  3. Optional. Have the employee go through a password setup if they are not using an identity provider (SSO).
Directory Sync makes this integration easy by providing APIs your app interfaces with. All updates for this directory will automatically be sent to your app from WorkOS.

​
API overview

Directory, directory group, and directory user are the main components your app interfaces with.

​
Directory

A directory is the source of truth for your customer’s user and group lists. WorkOS supports dozens of integrations including SCIM. Directory updates are delivered to you via webhooks. Your app stores a mapping between your customer and their directory. This allows you to maintain your app in sync with the directory provider used by your customer. You can enable self-service Directory Sync setup for your customers using the Admin Portal.

​
Directory group

A directory group is a collection of users within an organization who have been provisioned with access to your app. Directory groups are mapped from directory provider groups. Directory groups are most often used to categorize a collection of users based on shared traits. i.e. Grouping software developers at a company under an “Engineering” group.

​
Directory user

A directory user is a person or entity within an organization who has been provisioned with access to your app. Users can belong to multiple directory groups. Users have attributes associated with them. These attributes can be configured for your app’s needs.