How to sync users from Google Workspace to a Ruby on Rails app using WorkOS

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 Microsoft Entra ID (formerly Azure AD) into your app using SCIM, Node.js, 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 Ruby SDK
• Google Workspace 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 a Google Workspace directory.
• A WorkOS account.
• A Ruby app

Step 1: Install the SDK

Add the WorkOS Ruby SDK to your app:

	
gem install workos
	

If you're using Bundler to manage your application's gems, add the WorkOS gem to your Gemfile:

  
source 'https://rubygems.org'

gem '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 either as environment variables or directly in your app’s configuration.

Environment variables example:

	
WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'
	

For more info on how to handle secrets safely see Best practices for secrets management.

Step 3: Configure the Google Workspace 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.!!

1. Select environment: Login to your WorkOS dashboard and ensure you have the desired environment selected.
2. Send an admin invite link: Select “Organizations” in the navigation. Select the organization that’d like to enable a Google Directory Sync connection. On the Organization page, under “Invite an admin to set up this organization,” select “Invite Admin.” Select “Directory Sync” and any other features you’d like the organization to be able to onboard. Enter the email address of the organization admin, or copy the setup link and send it to the organization admin.
3. Authenticate with admin credentials: Have the organization choose Google as a provider and follow the Google prompts to authenticate with admin credentials.
4. Select which groups to sync to Your Application: The organization admin can then select to filter which groups and memberships are synced to the directory. If groups are being filtered, then only users with a membership within one of the synced groups will be synced.
5. Sync users and groups to Your Application: Changes will appear live in the Directory Sync portal under the “Users” tab.

!!For more details and screenshots, see the Google Directory Sync integration guide.!!

Step 4: Sync users and groups to your app

Once you've connected Google Workspace to WorkOS, any time a directory-related resource—like a user or group—is created, updated, or deleted in Google Workspace, 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:

  
require "workos"

events = WorkOS::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"
  }
}
  

Retrieve more events from the API using cursor pagination. To fetch the next set of events, provide the ID of the latest processed event in the after parameter.

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:

  
require "workos"

WorkOS.configure do |config|
  config.key = "WORKOS_API_KEY"
end

user = WorkOS::DirectorySync.get_user(
  "directory_user_id"
)
  

The response looks like this:

  
{
  "id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
  "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:

  
require "workos"

WorkOS.configure do |config|
  config.key = "WORKOS_API_KEY"
end

users = WorkOS::DirectorySync.list_users(
  directory: "directory_id"
)
  

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:

  
require "workos"

WorkOS.configure do |config|
  config.key = "WORKOS_API_KEY"
end

group = WorkOS::DirectorySync.get_group(
  "directory_group_id"
)
  

List groups

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

  
require "workos"

WorkOS.configure do |config|
  config.key = "WORKOS_API_KEY"
end

groups = WorkOS::DirectorySync.list_groups(
  directory: "directory_id"
)
  

!!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 that demonstrate how to use the WorkOS SDKs to power Directory Sync.
  • Ruby Example 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.