Directory Sync

Organizations use directories from providers like Okta or Workday to easily manage employees and user access to resources. Directories enable IT admins to activate and deactivate employee accounts, create groups that inform access rules, accelerate adoption of new tools, and more. Directory Sync connects your application with their directories, keeping your app informed of any changes in their users, groups, and access rules. Get seamless user lifecycle management for both you and your customers by keeping your app in sync with their employee directory.

The WorkOS Directory Sync API supports read-only operations. We will never mutate end-user directories.

Request a Directory Provider

Don't see a Directory Provider you need? Contact us to request a Directory Provider!

WorkOS makes use of Cloudflare, so if you are looking to create an IP allowlist you can use the IP Ranges listed in the Cloudflare documentation.

In this guide, we’ll take you from learning about Directory Sync and POC-ing all the way through to building production-ready features fully integrated with the WorkOS Directory Sync API.

Sign in to your Developer Dashboard account to see code examples pre-filled with your API keys and resource IDs.

This guide will show you how to:

To get the most out of this guide, you’ll need:

• A Developer Dashboard account.
• A directory from a Directory Provider that WorkOS supports.

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.

Install the SDK using the command below.

npm install @workos-inc/node

As a best practice, your WorkOS API key should be kept secret and set as an environment variable on process start. The Client ID should also be set dynamically based on the release environment.

WORKOS_API_KEY='{secretKey}'
WORKOS_CLIENT_ID='{clientID}'

Webhooks should use HTTPS and expect to receive POST requests with the following headers:

NOTE: We send the header as WorkOS-Signature, but many web servers will normalize all HTTP request headers to their lowercase variants. In this case, you'll extract the workos-signature header.

Below, we’ve provided example approaches for implementing a webhook endpoint.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
const express = require('express')

const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const payload = req.body;
  const sigHeader = req.headers['workos-signature'];

  // Verify the signature and process the event

  res.status(200);
});

Set and save the webhook URL in the Developer Dashboard so WorkOS knows where to deliver events.

The Webhook Secret is used to verify webhook requests from WorkOS. Be sure to keep the value secure.

We suggest handling events using two concurrent processes to avoid the possibility of unnecessary retry requests hitting your webhook handler.

On receiving an event, you should respond with an HTTP 200 OK. Otherwise, WorkOS will consider the event delivery a failure and retry up to 12 times, with exponential backoff over 3 days.

Before processing the request payload, verify the request was sent by WorkOS and not an unknown party.

The WorkOS SDKs have methods for validating the timestamp and signature of a webhook. Examples using these methods are included below. The parameters are the payload (raw request body), the WorkOS-Signature header, and the Webhook Secret. There is an optional parameter, tolerance, that sets the time validation for the webhook in seconds. The SDK methods have default values for tolerance, usually 3-5 minutes.

1
2
3
4
5
6
7
8
9
import WorkOS from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

const webhook = workos.webhooks.constructEvent(
  payload: payload,
  sigHeader: sigHeader,
  secret: process.env.WEBHOOK_SECRET,
);

If implementing webhook validation yourself, you'll need to use the following steps:

First, extract the timestamp and signature from the header. There are two values to parse from the WorkOS-Signature, delimited by a , character.

1. issued_timestamp: The epoch time at which the event was issued, prefixed by t=.
2. signature_hash: The HMAC SHA256 hashed signature for the request, prefixed by v1=.

To avoid replay attacks, we suggest validating that the issued_timestamp does not differ too much from the current time.

Next, construct the expected signature. The expected signature is computed from the concatenation of:

1. issued_timestamp
2. The . character
3. The request’s body as a utf-8 decoded string

Hash the string using HMAC SHA256, using the Webhook Secret as the key. The expected signature will be the hex digest of the hash. Finally, compare signatures to make sure the webhook request is valid.

Once you’ve determined the event request is validly signed, it’s safe to use the event, i.e. the request body, in your application’s business logic.