Skip to main content

Directory Sync

Set Hex user roles from you directory provider (Okta, Rippling, Google, Azure and more)

This feature is only available to users on the Enterprise tier. Additionally, teams with a single tenant install will need to contact [email protected] to get this configured.

Teams who use a directory provider for authentication and access controls of all of their various tools can now sync with Hex. When using directory sync, Hex user roles and group membership are managed in a third party tool, like Okta, Azure, and others, instead of directly in Hex's Adminstration page. This allows teams to quickly and easily keep a single source of truth for which users should have access and engage with Hex.

Understanding directory sync:

  • Groups that are created in your directory provider can be synced to Hex, appearing as groups in the Users & Groups section of your Hex Administration panel.
  • Groups can be used to determine the role of Hex users (e.g. Admin vs Author vs Viewer).
  • Any groups defined in your directory provider will also appear as groups in Hex. These Hex groups can be configured for access to shared workspace assets as with any Hex-created group. See more about managing shared group assets here.
  • Any users in your directory provider who have access to Hex will appear as a user in Hex. If a user in your directory provider is not included in a group specifying a certain Hex user role, that user will be assigned to Hex as a Viewer.

Setup steps:

  • In the Hex Administration panel, go to the Users & groups panel and scroll down to Directory sync — if you don’t see this option then Directory Sync is not currently available for your workspace. Get in touch with us at [email protected] to change that!
  • Click on Configure, which will take you to a portal to select which directory provider your company uses.
  • Configure the users and group you want to sync to Hex in your directory sync provider. We recommend that at a minimum you create two groups: Hex Admins and Hex Authors. These are the two groups of users who you will set up to be automatically assigned the corresponding Hex user role.
  • Depending on your provider, you’ll be guided through a setup flow for how to sync the details from your directory sync provider to Hex.
  • Once groups are synced from your directory provider, return to the Users & groups panel in Hex. From here you can now map which group of users should be assigned as Hex Admins and Hex Authors by selecting the appropriate group from the two options like Admin assigned to {insert desired directory provider group name}.

For a full walk through of how to set up directory sync, using Okta in this case, check out this video:


How can I edit groups which have been configured in my directory sync provider?

  • Any group synced from your directory provider cannot be edited in Hex. e.g. membership for groups which have been set up via your directory sync must be managed in your directory provider directly.

If I have directory sync enabled, can I have still add additional users to Hex from Hex?

  • Yes. You can add users to your workspace from the Administration panel. However, users added in this manner will not be added to any of your groups as defined in your directory sync provider. For example: If you added a new Admin user from Hex, that user will not be appended to the "Hex Admins" group. Thus if you have configured that group to have access to any shared workspace assets the new user would not be included in that access.

What happens if I don't specify what Hex user role someone should have?

  • If your workspace is configured to allow anyone with a specified email domain to log in to Hex, and the user joins your workspace via that method, their role will be determined by the configured default workspace role.
  • If a user is added to Hex via your directory provider and they are not included in the Admin or Author group, they will be Viewers.