Setting up directory sync

Integrate existing directories into your Axios HQ audience

Axios HQ invites you to bring in your audience in a few different ways: manually add individuals one-by-one, upload a CSV of recipients’ emails and names, or connect your existing directories and have them sync automatically!

Why it matters

• Setting up a directory sync allows you to connect your current email distribution lists and sync them to Axios HQ.
• As your email lists change you won’t have to worry about updating your audience to match in Axios HQ. Updates will sync automatically!

Table of contents: 

1. Directory types we support
2. Syncing your directory
3. Attributes
4. FAQ
5. Common Providers

1. Directory types we support

We partner with WorkOS to facilitate most of our integrations. You can find an introduction to WorkOS and their workflow here.

We support the following directory providers:

Each directory provider has allowances and limitations, and certain group types within these directories may sync more seamlessly than others. 

Relevant setup options we recommend reviewing include:

• Nested groups: Nested groups may not sync with Axios HQ. There are often workarounds to bring in this group membership, depending on your directory provider.
• Dynamic groups: Dynamic groups are those that are gathered with a query, rather than set up individually by a user. Certain directory providers do not support adding dynamic groups to applications within their system.

2. Syncing your directory

🛠️ How it works

• Navigate to Settings > Integrations, then locate Direcory Sync and click "Connect."
• You will be taken to a setup portal provided by WorkOS.
• Select your directory provider from the list and walk through the setup instructions for your directory.
• When your directory sync is complete, you will see the linked connection at Settings > Integrations.

3. Attributes

By default Axios HQ syncs only a limited list of attributes coming from your directory: 

• email
• first_name
• last_name
• any group assignments

If you would like to sync the following additional attributes, please reach out to help@axioshq.com and we will be able to turn this on for your team: 

4. FAQ

📚 Sending

Can I still send from HQ before setting up a directory sync?

Yes! You can still send from HQ before setting up a directory sync. You can manually add recipients by navigating to your series audience and either:

• Upload a CSV of multiple individuals by clicking on "Manage recipients" and selecting "Import CSV" 
• Individually add new recipients by clicking on "Add individuals"   

Can I use a CSV and my directory groups?

Yes! Add individuals one-by-one or via CSV at any time. If a CSV is uploaded or deleted, contacts added via Directory Sync will not be affected. If a recipient is on a CSV and synced via directory sync with the same email address, they will not receive an edition twice.

📚 Troubleshooting

My recipients aren't syncing / I see my recipient is listed as "Inactive"

📚 Access

Who can access my organization's synced directory?

Only Owners, Admins, and Members with granted permission can access your synced directory.

Can I restrict access to certain synced directory groups?

Some providers may allow you to select specific directory groups in the setup options. Others will sync all available groups.

Within Axios HQ, users either have access to the synced directory or they do not; at the moment, our platform does not support restricting user access to specific directory groups.

Will synced members (recipients) gain access to the platform?

No. Synced audience members (recipients) will not gain access to the platform. Access is only granted by inviting users to your organization and through our SSO integration.

📚 Sync

How often will syncs be performed?

• BambooHR, Breathe HR, Cezanne HR, Fourth, Google Workspace, HiBob, and  Workday directories poll every 30 minutes starting from the time of the initial sync.
• Okta SCIM 2.0 directories sync events in real time.
• By default, Entra ID SCIM 2.0 directories sync events on a scheduled time interval, typically every 40 minutes. There's also an option for on-demand provisioning which syncs events in real time.

We have more than one directory, how can I sync them both?

Reach out to us at help@axioshq.com to set up an additional directory. Each organization is entitled to two directories without charge, and can add more connections for an additional fee.

If a directory member is offboarded via the SCIM group management, is that member automatically disabled / removed from the directory sync (audience)?  

Yes, and this recipient will be removed from all audiences across all series within your organization. However, the users themselves will not be removed from the platform.

• If a member of the directory is also an HQ user, the connections must be viewed separately.
• User access will be revoked when a user is deprovisioned from the SAML app (ie: their account is deleted or marked inactive) but their username will still be visible as a collaborator; the user will simply no longer be able to login.

📚 Security

Can we review WorkOS's Privacy Policy?

Yes, check out WorkOS's Privacy Policy and Security FAQs here.

5. Common Providers

Below is a list of common Directory providers and some additional recommendations and troubleshooting tips.

Google Workspace

• Google's setup requires a Super Admin or custom admin role to facilitate the connection. Make sure one of these two accounts officially authenticates any connections to Axios HQ.
  
  • The custom admin role should be configured with the following API privileges:
    • Users > Read
    • Groups > Read
• If your team has only synced select Google groups, you can add more to your setup by navigating to  Settings > Integrations > Connected Apps, and selecting the gear next to your connection. Under the "Group sync" heading, edit the groups you'd like to bring into HQ!

Microsoft Entra ID (Azure Active Directory)

• Microsoft directories can be synced via Enterprise Application or App Registration. Check out our comparison page if your team is using Entra ID/Azure AD to see which setup would be best for you.
  • Our self-serve portal available in the HQ platform only provides the option for the Enterprise Application. If your directory configuration is incompatible and you would prefer an App Registration, reach out to help@axioshq.com.
• We are not able to sync with Azure on-premises directories at this time.
• Any groups synced to an Enterprise Application in Azure Active Directory must be security groups. For this reason, you can sync a Dynamic Distribution Group, but cannot sync a Dynamic Distribution List.
• If your Azure Active Directory setup is not pulling in email addresses:
  • Review the "state" field on the directory member in Azure. If the state is set to "state": "inactive", the member will not be synced to your HQ audience. Learn how to see if your audience members are Inactive, here.
  • You may need to configure attribute mapping in your SCIM app in Azure. Review this tutorial from Microsoft, and consider mapping a known email attribute, such as UPN, to the emails[type eq "work"].value SCIM attribute.

• WorkOS, by default, syncs a number of attributes to HQ. The only attributes we currently sync from Azure to ensure functionality are:
  
  

  userPrincipalName	Switch([IsSoftDeleted], , "False", "True", "True", "False")
  mail	displayName
  surname	givenName
  objectId	Join(" ", [givenName], [surname])

Okta

• Organizations that plan to sync Okta for both Directory Sync and SSO connections should create two separate applications, one for each connection. This will avoid users provisioned for SSO from being mistakenly pulled into the Directory Sync.
• If you are encountering issues with users not appearing in the sync:
  • For Okta applications that have both SCIM and SAML, users that were assigned to the app before provisioning was added will need to be provisioned before they can be synced.
• Users must be assigned to the directory sync application you are configuring. Some organizations may want to limit this, to avoid Axios HQ from appearing as an application that can be clicked on the users' dashboards. However, this step is required for the directory sync. We suggest completing this step and then hiding the application tile from the users' portals, if this is a concern.