How to sync users from Okta to your Python app

If you're building for the enterprise, SSO is just half the story, automated user provisioning is the other half. Without it, you're stuck manually managing accounts, opening the door to delays, mistakes, and security gaps. With provisioning in place, users get instant access when they need it, and lose it the moment they leave.

That’s where SCIM comes in. It’s the industry-standard protocol for syncing users between identity providers and applications, securely, reliably, and automatically.

In this tutorial, we’ll walk through how to sync users from Okta into your app using SCIM, Python, and WorkOS. You’ll learn how to provision, update, and deprovision users in your app automatically, without having to build a SCIM server from scratch.

While going through this tutorial, remember that some things might get outdated as products evolve. Dashboards change, and new SDK versions are released every week. If, while you follow this tutorial, something is not working for you, please refer to these docs for the most up-to-date guidance:

• WorkOS Python SDK
• Okta SCIM integration guide
• Directory Sync quickstart

!!If you want to integrate with a different directory provider or use a different SDK see our Directory Sync quickstart.!!

Prerequisites

To follow this tutorial, you will need the following:

• Access to an Okta directory
• A WorkOS account
• A Python 3.7+ app

Step 1: Install the SDK

Install the WorkOS Python SDK to your app.

  
pip install workos
  

Step 2: Set secrets

To make calls to WorkOS, you must authenticate using the WorkOS API key and client ID. Copy these values from the WorkOS dashboard.

Store the values as managed secrets and pass them to the SDK as environment variables:

Environment variables example:

	
WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'
	

!!For more information on safely handling secrets, see Best practices for secrets management.!!

Step 3: Configure the Okta connection

The first step to connecting with a directory is creating an organization in the WorkOS dashboard. You will then be able to create a new connection to the organization’s directory.

!!An organization is a collection of users that also acts as a container for enterprise features (like SSO). By enabling an SSO connection for a specific organization, you enable the feature for all users who are members of this organization. This way, you can enable features like forcing all users that use a specific email domain to use a specific SSO connection. For more information on organizations and how to use them, see Model your B2B SaaS with organizations.!!

First, we will configure Okta SCIM at the WorkOS dashboard, and then we will move on to the Okta admin dashboard to finish the configuration.

WorkOS configuration

1. Go to the WorkOS dashboard and select Organizations from the left-hand navigation bar.
2. Pick (or create) the organization for which you’d like to configure an Okta SCIM connection.
3. Select “Configure manually” under the “Directory Sync” section and enter a name for the directory.
4. Click “Create Directory”.

You’ll see WorkOS has created the Endpoint and Bearer Token which you will provide to Okta in the steps below.

Okta configuration

We will now do the configuration on the Okta side.

Instead of doing this yourself, you can use the WorkOS Admin Portal, an out-of-the-box UI that IT admins can use to configure SSO and Directory Sync connections. You can integrate it into your app or get a link from the WorkOS dashboard and send it to the admin. For more, see the docs.

To configure the connection on Okta's side, follow these steps:

1. Log in to Okta, go to the Okta admin dashboard and select “Applications” in the navigation bar.
2. If your application is already created, select it from the list of applications and move to Step 3. Otherwise, select “Browse App Catalog”, search for “SCIM 2.0 Test App (OAuth Bearer Token)” and select the corresponding result. On the following page, click “Add Integration”, enter a descriptive App name, then click “Next”.
3. In your application’s Enterprise Okta admin panel, click the “Provisioning” tab. Then, click “Configure API Integration”.
4. Check “Enable API Integration”. After that, copy and paste the Endpoint from your WorkOS Dashboard in the SCIM 2.0 Base URL field.
5. Copy and paste the Bearer Token from your WorkOS Dashboard into the OAuth Bearer Token field.
6. Click “Test API Credentials”, and then click “Save”.
7. In the “To App” navigation section, check to enable:
   • Create Users
   • Update User Attributes
   • Deactivate Users
   Click “Save”.
8. To assign users to the SAML Application, navigate to the “Assignments” tab, from the “Assign” dropdown, select “Assign to People”. Select users you’d like to provision and select “Assign”.
9. To push groups in order to sync group membership, navigate to the “Push Groups” tab, from the “Push Groups” dropdown, select: “Find groups by name”. Search for the group you’d like to push and select it. Make sure the box is checked for “Push Immediately” and click “Save”.
10. In theWorkOS dashboard, you should now see the users and groups synced over.

!!For more details and screenshots, see the Okta SCIM integration guide.!!

Step 4: Sync users and groups to your app

Once you've connected Okta to WorkOS, any time a directory-related resource, like a user or group, is created, updated, or deleted in Okta, WorkOS will generate a corresponding event. These events allow your app to stay in sync with the identity provider in real time, ensuring user data is always up to date.

About events

Each WorkOS event has the following structure.

‍

For example, this is an event about the creation of a new user:

	
{
  "event": "dsync.user.created",
  "id": "event_07FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
    "idp_id": "8931",
    "emails": [
      {
        "primary": true,
        "type": "work",
        "value": "lela.block@example.com"
      }
    ],
    "first_name": "Lela",
    "last_name": "Block",
    "username": "lela.block@example.com",
    "state": "active",
    "created_at": "2021-06-25T19:07:33.155Z",
    "updated_at": "2021-06-25T19:07:33.155Z",
    "custom_attributes": {
      "department": "Engineering",
      "job_title": "Software Engineer"
    },
    "role": { "slug": "member" },
    "raw_attributes": {}
  },
  "created_at": "2021-06-25T19:07:33.155Z"
}
	

The different directory events are:

!!For details and sample payloads on each event, see Understanding the events lifecycle.!!

Sync events to your app

After WorkOS generates these events, your app needs to consume them to stay in sync with the latest changes. You can do this in one of two ways:

• By polling the Events API for new events, or
• By setting up webhooks to receive them automatically in real time.

Either approach ensures that your app reflects the current state of the directory.

With the events API, your application retrieves events from WorkOS. It provides a consistent, ordered stream of immutable events via a paginated endpoint, allowing your application to pull and process changes at its own pace. This architecture not only ensures data integrity and easier error recovery, but also simplifies debugging and audit logging.

With webhooks, WorkOS automatically notifies your app when an event occurs by invoking an endpoint hosted within your application. Although webhooks are popular, they are also prone to issues like missed deliveries, out-of-order events, and scalability bottlenecks (for more, see Why you should rethink your webhook strategy). We recommend using the events API instead.

Sync data using the events API

To start consuming events, you first need to pick a starting place in the data set. For that, you need a cursor.

A cursor is a bookmark to track your app’s position in the events list. The very first call to the events API won’t have a cursor. Subsequent requests to WorkOS should include the updated cursor using the after parameter. You will need to update and store your cursor after processing an event.

Determine the event types you want to pull, and call the listEvents method. In this example, we are pulling the first 100 events:

  
from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

events = workos_client.events.list_events(
    events=[
        "dsync.activated",
        "dsync.deleted",
        "dsync.user.created",
        "dsync.user.updated",
        "dsync.user.deleted",
    ],
  limit: 100,
)

  

This is an example response (one user created, and one updated):

	
{
  "data": [
    {
      "event": "dsync.user.created",
      "id": "event_07FKJ843CVE8F7BXQSPFH0M53V",
      "data": {
        "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
        "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
        "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
        "idp_id": "8931",
        "emails": [
          {
            "primary": true,
            "type": "work",
            "value": "lela.block@example.com"
          }
        ],
        "first_name": "Lela",
        "last_name": "Block",
        "username": "lela.block@example.com",
        "state": "active",
        "created_at": "2021-06-25T19:07:33.155Z",
        "updated_at": "2021-06-25T19:07:33.155Z",
        "custom_attributes": {
          "department": "Engineering",
          "job_title": "Software Engineer"
        },
        "role": { "slug": "member" },
        "raw_attributes": {}
      },
      "created_at": "2021-06-25T19:07:33.155Z"
    },
    {
      "event": "dsync.user.updated",
      "id": "event_08GHJ944DVE9G8CXRTPGI1N64W",
      "data": {
        "id": "directory_user_01E2Y2C90OI9H4TGFSK5H9TYU8",
        "directory_id": "directory_01ECBZ5PW0RNX58HY984IDCZ85",
        "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
        "idp_id": "8931",
        "emails": [
          {
            "primary": true,
            "type": "work",
            "value": "jacob.morris@example.com"
          }
        ],
        "first_name": "Jacob",
        "last_name": "Morris",
        "username": "jacob.morris@example.com",
        "state": "active",
        "created_at": "2021-05-15T13:00:00.000Z",
        "updated_at": "2021-07-01T10:45:00.000Z",
        "custom_attributes": {
          "department": "Marketing",
          "job_title": "Marketing Manager"
        },
        "role": { "slug": "admin" },
        "raw_attributes": {}
      },
      "created_at": "2021-07-01T10:45:00.000Z"
    }
  ],
  "list_metadata": {
    "after": "event_08GHJ944DVE9G8CXRTPGI1N64W"
  }
}
	

In all subsequent calls, you have to use list_metadata.after for pagination. You'd pass that value as a after parameter to get the next page of results, and then update it to the new value contained in the API's response.

For more info, see the Sync data using the Events API quickstart.

Step 5 (optional): Get specific users and groups

The API offers some more endpoints you can use for specific use cases.

Get a user

To get the details of an existing directory user:

	
from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

user = workos_client.directory_sync.get_user(
    user_id="directory_user_01E64QS50EAY48S0XJ1AA4WX4D"
)
	

The response looks like this:

	
{
  "id": "directory_user_01E64QS50EAY48S0XJ1AA4WX4D",
  "idp_id": "2836",
  "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
  "first_name": "Marcelina",
  "last_name": "Davis",
  "email": "marcelina@example.com",
  "groups": [
    {
      "id": "directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT",
      "name": "Engineering",
      "created_at": "2021-06-25T19:07:33.155Z",
      "updated_at": "2021-06-25T19:07:33.155Z",
      "raw_attributes": {}
    }
  ],
  "state": "active",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "custom_attributes": {
    "department": "Engineering",
    "job_title": "Software Engineer"
  },
  "raw_attributes": {},
  "role": { "slug": "member" }
}
	

List users

You can get directory users for a given directory or directory group:

	
from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

users = workos_client.directory_sync.list_users(
    group_id="directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT"
)
	

The response is an array of users. You can use this to build an onboarding experience that allows an admin to select who to invite and create accounts for.

Get a group

To get the details of an existing directory group:

	
from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

group = workos_client.directory_sync.get_group(
    group_id="directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT"
)
	

List groups

To get directory groups for a given directory or directory user:

	
from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

groups = workos_client.directory_sync.list_groups(
    user_id="directory_user_01E64QS50EAY48S0XJ1AA4WX4D"
)
	

!!Use the optional limit, before, and after parameters to paginate through results. See the API Reference for details.!!

Step 6 (optional): Stream events to Datadog

WorkOS supports real-time streaming of events to Datadog. By analyzing WorkOS activity directly in Datadog, you are able to:

• View trends in user sign-ins, user growth, new SSO connections and more.
• Debug customer issues related to sign-in, email verification, password resets and more.
• Generate reports of user activity per customer organization.
• Set alerts for unexpected activity, such as sudden spike in failed password attempts.

To set up real-time streaming of WorkOS events to Datadog, follow these steps:

1. Create a new Datadog API key to give WorkOS permission to send event activity as logs to your Datadog account.
2. Configure event streaming in the WorkOS dashboard using the Datadog API key.
3. Add the WorkOS Datadog dashboard to your Datadog account.

For detailed instructions and screenshots, see the docs: Stream events to Datadog.

Next steps

• Example apps: Check out our sample apps hat demonstrate how to use the WorkOS SDKs to power Directory Sync.
  • Python Flask Directory Sync app
  • Python Django Directory Sync app
  • Other SDKs
• Handle inactive users: Learn why inactive users are deleted from directories by default and how to configure this behavior.
• User attributes: Configure how attributes map from directory providers to Directory Users.
• Using WorkOS with On-prem Customers: Best practices for using WorkOS with on-prem customers.
• Identity Provider Role Assignment: Learn how to map role data from identity providers to roles in your app with Directory Sync.