Configure how attributes map from directory providers to Directory Users.
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 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.
{ "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.
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.
For more detailed user information, you can opt-in to additional predefined attributes and define your own custom attributes. These attributes will appear in the custom_attributes
field on Directory User objects and can be configured in the WorkOS Dashboard.
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 |
---|---|
addresses | The user’s list of address objects (street_address , locality , region , postal_code , country , primary , raw_address ) |
cost_center_name | The user’s cost center name |
department_name | The user’s department name |
division_name | The user’s division name |
emails | The user’s list of email objects (type , value , primary ) |
employee_type | The user’s employment type |
employment_start_date | The user’s start date |
job_title | The user’s job title |
manager_email | The email address for the user’s manager |
username | The user’s username |
Predefined attributes can be enabled or disabled in the WorkOS Dashboard on the Identity Provider Attributes page.
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.
The following support table outlines the attribute availability across directory providers.
Attributes | SCIM | 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 attributes can be utilized to enrich Directory User objects with additional data from the identity provider. 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 identity provider.
Custom attributes can be created in the WorkOS Dashboard on the Identity Provider Attributes page.
When a custom attribute is deleted, the attribute will be deleted from all Directory User objects.
Updates to custom 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.
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:
{ "top_level_attribute": "value", "top_level_with_nested": { "nested_attribute": "nested_value" } }
If you are interested in nested attributes support, please contact support.
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 July 22, 2025. IdP role assignment or custom attributes should be used instead.
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.
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.
Attributes that cannot be mapped for a particular Directory User will result in a null
value for the attribute. dsync.user.updated events are not emitted when an attribute changes from null
to undefined
or vice versa.