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; 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.
{ "id": "directory_user_01E1X7B89OH8Z3SXFJR4H7RGX7", "idp_id": "821991", "first_name": "Jane", "last_name": "Doe", "job_title": "Software Engineer", "username": "[email protected]", "emails": [ { "type": "work", "value": "[email protected]", "primary": true } ], "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": { "employee_type": "Full Time", "employment_start_date": "2021-06-27T12:00:00.000Z", "department_name": "Engineering", "manager_email": "[email protected]", "division_name": "Analytics", "cost_center_name": "IT", "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 } ], "my_new_key": "<custom-mapped value>" }, "raw_attributes": { "name": { "givenName": "Jane", "familyName": "Doe" }, "active": true, "emails": [ { "type": "work", "value": "[email protected]", "primary": true } ], "groups": [], "locale": "en_US", "schemas": ["urn:directory:schemas:core:1.0"], "password": "redacted", "userName": "[email protected]", "externalId": "821991", "displayName": "Jane Doe" } }
In this guide, we’ll explain how to map data from directory providers to the Directory Users.
raw_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 | Required |
last_name | The user’s last name | Required |
username | The user’s username | Required |
emails | The user’s list of email objects (type, value, primary) | Required |
state | The user’s state. May be active , suspended , or inactive | Required |
job_title | The user’s job title | Optional |
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.
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 |
employee_type | The user’s employment type | Optional |
employment_start_date | The user’s start date | Optional |
manager_email | The email address for the user’s manager | Optional |
Auto-mapped attributes can be enabled or disabled in the WorkOS Dashboard under Configuration → Directory Sync.
Updates to these settings will typically take 30 minutes to 1 hour to reflect in your Directory User API response.
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 | Not 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 | Not available |
division_name | Available | Available | Available | Not available | Not available | Available | Available | Not available | Not available |
employment_start_date | Not available | Not available | Available | Available | Available | Available | Available | Available | Not available |
employee_type | Available | Available | Available | Not available | Available | Available | Available | Not available | Not available |
manager_email | Available | Available | Available | Available | Available | Available | Available | Available | Not available |
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 are not supported. These admin-defined attributes must be defined as top-level flat keys.
Custom-mapped attributes can be created in the WorkOS Dashboard under Configuration → Directory Sync. You can set the status of the attribute to “Required” or “Optional”. For all required attributes your customers must map the field to a relevant field in their HRIS or SCIM provider. This can be done via the Admin Portal.
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.