User Attributes

Configure how attributes map from directory providers to Directory Users.

Introduction

WorkOS can automatically find and normalize most common attributes from directory providers into the Directory User object, which represents an enterprise user. More unique cases can be mapped by your customers; i.e. IT Admins.

Here is an example Directory User. The data stored varies per directory provider and may include attributes such as photo URLs, pay groups, supervisors, etc.

Directory User

JSON

 {
  "id": "directory_user_01E1X7B89OH8Z3SXFJR4H7RGX7",
  "idp_id": "821991",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "state": "active",
  "created_at": "2021-06-25T19:07:33.155Z",
  "updated_at": "2021-06-25T19:07:33.155Z",
  "object": "directory_user",
  "directory_id": "directory_01E1X194NTJ3PXMAY79DYV0F0P",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3PJNY",
  "custom_attributes": {
    "emails": [
      {
        "type": "work",
        "value": "jane@example.com",
        "primary": true
      }
    ],
    "employee_type": "Full Time",
    "employment_start_date": "2021-06-27T12:00:00.000Z",
    "department_name": "Engineering",
    "manager_email": "john@example.com",
    "division_name": "Analytics",
    "cost_center_name": "IT",
    "job_title": "Software Engineer",
    "addresses": [
      {
        "type": "work",
        "street_address": "101 123rd Ave",
        "locality": "Brooklyn",
        "region": "New York",
        "postal_code": "12345",
        "country": "USA",
        "raw_address": "101 123rd Ave, Brooklyn,  New York, 12345, USA",
        "primary": true
      },
      {
        "type": "home",
        "street_address": "102 W 321st St",
        "locality": "Brooklyn",
        "region": "New York",
        "postal_code": "54321",
        "country": "USA",
        "raw_address": "102 W 321st St, Brooklyn,  New York, 54321, USA",
        "primary": false
      }
    ],
    "username": "jane@example.com",
    "my_new_key": "<custom-mapped value>"
  },
  "raw_attributes": {
    "name": {
      "givenName": "Jane",
      "familyName": "Doe"
    },
    "active": true,
    "emails": [
      {
        "type": "work",
        "value": "jane@example.com",
        "primary": true
      }
    ],
    "groups": [],
    "locale": "en_US",
    "schemas": ["urn:directory:schemas:core:1.0"],
    "password": "redacted",
    "userName": "jane@example.com",
    "externalId": "821991",
    "displayName": "Jane Doe"
  }
}

In this guide, we’ll explain how to map data from directory providers to the Directory Users.

Definitions

Standard attributes: The most common user information, normalized across providers.
Auto-mapped attributes: Detailed user attributes for specific use cases, normalized across providers. You can opt-in to each attribute you want to receive.
Custom-mapped attributes: For unique cases, you can create your own attributes that your customers can map when setting up a directory.
Raw attributes: The entire unprocessed attribute payload that we receive from the directory provider and provide in a field called raw_attributes.

Standard attributes

Every Directory User comes with the following standard attributes. These are the core set of attributes that are common across all identity providers. These are structured fields with a guaranteed schema in the top-level Directory User payload.

Attribute	Type and description	Status
`idp_id`	The user’s unique identifier, assigned by the directory provider. Different directory providers use different ID formats	Required
`first_name`	The user’s first name	Optional
`last_name`	The user’s last name	Optional
`email`	The user’s email	Optional
`state`	The user’s state. May be `active`, or `inactive`	Required

emails, job_title, and username were previously considered standard attributes, but have been deprecated in favor of equivalent auto-mapped custom attributes.

Custom attributes

For more detailed user information, you can opt-in to auto-mapped custom attributes and define your own custom-mapped custom attributes. Custom attributes will appear in the custom_attributes field. These attributes can be configured in the WorkOS Dashboard.

Auto-mapped attributes

When enabled, the values will be mapped without additional setup. Not every directory provider has data for every field, so they are always optional if enabled. These fields are named and schematized by WorkOS – they cannot be renamed.

Attribute	Type and description	Status
`addresses`	The user’s list of address objects (`street_address`, `locality`, `region`, `postal_code`, `country`, `primary`, `raw_address`)	Optional
`cost_center_name`	The user’s cost center name	Optional
`department_name`	The user’s department name	Optional
`division_name`	The user’s division name	Optional
`emails`	The user’s list of email objects (`type`, `value`, `primary`)	Optional
`employee_type`	The user’s employment type	Optional
`employment_start_date`	The user’s start date	Optional
`job_title`	The user’s job title	Optional
`manager_email`	The email address for the user’s manager	Optional
`username`	The user’s username	Optional

Enable or disable an auto-mapped attribute

Auto-mapped attributes can be enabled or disabled in the WorkOS Dashboard under Directory Sync configuration.

Updates to these settings may take up to an hour to reflect in your Directory User API response. A dsync.user.updated event is emitted for each Directory User changed by toggling auto-mapped attributes.

WorkOS Dashboard UI showing "Edit auto-mapped attributes" dialog

Support per directory provider

The following support table outlines the attribute availability across directory providers.

Attributes	SCIM	Google	Workday	HiBob	People HR	BambooHR	Breathe HR	Cezanne HR	Fourth
`addresses`	Available	Available	Available	Available	Available	Available	Available	Available	Not available
`cost_center`	Available	Available	Available	Not available	Not available	Not available	Not available	Available	Not available
`department_name`	Available	Available	Available	Available	Available	Available	Available	Available	Available
`division_name`	Available	Not available	Available	Not available	Not available	Available	Available	Not available	Not available
`emails`	Available	Available	Available	Available	Available	Available	Available	Available	Not available
`employment_start_date`	Not available	Not available	Available	Available	Available	Available	Available	Available	Available
`employee_type`	Available	Available	Available	Not available	Available	Available	Available	Not available	Available
`job_title`	Available	Available	Available	Available	Available	Available	Available	Available	Not available
`manager_email`	Available	Available	Available	Available	Available	Available	Available	Available	Not available
`username`	Available	Available	Available	Available	Available	Available	Available	Available	Not available

Custom-mapped attributes

If your application may require additional fields, this is where custom-mapped fields are useful. You can create attributes that appear as fields in the Admin Portal. Your customers can map these fields to the correct values in their system when setting up Directory Sync with their directory provider.

Nested attributes

Nested attributes are not currently supported. These admin-defined attributes must be defined as top-level flat keys.

For instance, in the following example top_level_attribute can be mapped, but top_level_with_nested.nested_attribute cannot be mapped:

Attributes Example

JSON

 {
  "top_level_attribute": "value",
  "top_level_with_nested": {
    "nested_attribute": "nested_value"
  }
}

Create a custom-mapped attribute

Custom-mapped attributes can be created in the WorkOS Dashboard under Directory Sync configuration. For attributes set as Required, your customers must map the field to a relevant field in their HRIS or SCIM provider. This can be done via the Admin Portal.

WorkOS Dashboard UI showing custom attribute editing

Updates to custom-mapped attributes may take up to an hour to reflect in your Directory User API response. A dsync.user.updated event is emitted for each Directory User changed by modifying custom-mapped attributes.

Raw attributes [Deprecated]

These are unfiltered and unstructured attributes that are unique to each directory provider. These attributes are included as fields in the raw_attributes object that is included in the Directory User. The raw_attributes property will be phased out by April 21, 2025. IdP role assignment or custom attributes should be used instead.

Frequently asked questions

Are existing directories required to update the attribute mapping when new required custom attributes are added?

No, when you add a new required custom attribute to your settings, this won’t be retroactively required for directories that have already been set up and configured. However, in the WorkOS dashboard, you will be able to navigate directly to the existing directory and fill in details for those attributes manually.

Can our customers add their own custom attributes outside of what is defined in the WorkOS dashboard?

We do not currently support this functionality, as you have to define any custom attributes in the dashboard first. Please reach out to support if you have a specific use case that you would like to discuss.

What happens if an attribute cannot be mapped from the IdP?

Attributes that cannot be mapped for a particular Directory User will result in a null value for the attribute. A dsync.user.updated event is still emitted if an auto-mapped or custom attribute is enabled or disabled, regardless of whether a non-null value was mapped.