Directory Sync now maps custom attributes without custom code

At WorkOS, we’ve seen Directory Sync emerge as the next step after SSO in the journey towards Enterprise Readiness. Just as SSO gives automated access to your application based on your customers’ identity providers, Directory Sync enables automated user provisioning and deprovisioning, based on your customers’ human resources (HR) directories. 

WorkOS Directory Sync already connects your app to the external list of users found in your customers’ HR directory. Like you would with our SSO integration, you integrate with WorkOS once to connect to a range of directory providers.

As we spoke with our Directory Sync customers, it became clear that they were going beyond just syncing user lists, especially if they were building applications that used their own customers’ HR information. We found that customers using Directory Sync wanted to be able to pull in data like the name of an employee’s manager or office location. In turn, we wanted to create a simple and seamless user experience for pulling in these custom attributes.

Attribute mapping doesn’t need to be complex 

Syncing attributes is more complicated than simply mapping fields to values because each directory stores attribute information differently. 

For instance, an attribute like email may be referred to as `email`, `email_id`, or `email_address` across different providers. In the past, this variation meant that you had to know each provider’s attributes. You also had to write code to deal with the varying attribute names across multiple directory providers.

To make this a little more concrete, say you wanted to pull management chain information into your application, and that information is stored in a customer’s HR directory. Without custom attributes, you would have to configure raw attribute information from each directory provider and write conditional statements into your code for each provider your customers might work with. Further, anytime you wanted to add support for a new directory provider, you would have to update your code. In addition to these scalability issues, there is a lot of room for error in the process. 

WorkOS normalizes custom attributes for you 

Now, with custom attributes available via WorkOS Directory Sync, our customers can use the WorkOS dashboard to map the attributes they want to pull in from various directory providers. This enables our customers to minimize Directory Sync integration errors and normalize the information they need. Adding support for an additional directory provider in the future can be done directly from the WorkOS dashboard, rather than updating the application’s codebase. As a result, you not only save time - you also future-proof your integration as custom attributes works for any directory provider that WorkOS supports. 

In the screenshot below, you can see that the custom attributes are normalized in the same way that core attributes like `first_name`, `last_name`, and `username` in Directory Sync are. You can just reference the custom attributes in your application instead of conditionally searching for provider-specific raw attributes.

Enable your customers to map their own custom attribute with Admin Portal

We also heard from you that each company often has unique names for attributes, and that setting up attribute mapping should happen at the time of Directory Sync setup. 

That’s why we brought custom attribute mapping to the WorkOS Admin Portal. Your customers’ IT admins, the ones who best know the fields offered by their directory providers, can configure the custom attribute mapping for the fields that you define for your application. 

In the screenshot below, you can see how your customers will be guided to set up attribute mapping from within the WorkOS Admin Portal. Customers can input the directory provider value that maps to the WorkOS attribute.

Try custom attribute mapping for yourself

Customers like OfficeTogether and Universal Avenue have already been using custom attribute mapping since our beta launch in September 2021. 

OfficeTogether, a desk reservation and scheduling platform for the hybrid office, guides their customers to map in an attribute of people’s managers using Admin Portal, which will enable teams in their application to easily see each other’s in-office schedules to maximize collaboration and in-person overlap. 

Custom attribute mapping is now generally available for all WorkOS customers, and you can try it out in the Configurations section of your WorkOS dashboard. Click on the Custom Attribute tab that appears, then test it out.  

You may also need to update your SDK to use custom attribute mapping. For reference, you can see which SDK version supports attribute mapping: 

• .NET: v1.3.0 or newer
• Go: v1.3.0 or newer
• PHP: v1.3.0 or newer
• Node: v1.3.0 or newer
• Python: v1.0.0 or newer
• Ruby: v1.5.0 or newer
• Laravel: v1.1.0 or newer

If you have any questions at all, send us a message in your shared Slack channel or email us at support@workos.com!