Sync your lists
      Back to home
      1. Help Center
      2. Integrations
      3. Sync your lists

      Connecting an Azure AD (Entra ID) Application Registration

      Connect to Azure with an Application Registration to sync your audience!

      ⭐ Directory Sync requires an upgrade from the Essential Package. Review our packages here.

      Table of Contents

      1. Setting up your Directory Sync
      2. Register a new application
      3. Provide IDs to Axios HQ
      4. Add API permissions
      5. Review attributes
      6. Add client credentials
      7. Select groups
      8. Optional fields
      9. Finalize your setup
      10. Sending your information to Axios HQ
      11. What your HQ users can expect
      12. FAQs

      1. Setting up your Directory Sync

      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!

      This sync type is not available in the self-serve portion of our platform. If you are interested in connecting to Azure via Application Registration, please reach out to your account manager or to help@axioshq.com

      You can also connect to Azure via Enterprise Application. Review the capabilities of each sync here.

      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!

      Remember: Directory Sync connections bring in your users' recipients, distribution lists, and targeted audience. This connection does not handle user logins.

      • The users at your organization will use the SSO connection log into the platform to plan, write, and send essential communications.
      • The recipients of your series will be synced via the Directory Sync connection; they'll open email series that are engaging, succinct, and intentional in their design.

      Application Registration Sync Capabilities

      ✓ Able to sync to Axios HQ | ✓* Must have a Premium License (P1 or higher)

      What groups can sync App Registration
      All Azure Groups ✓
      Only select Azure groups ✓
      Security groups ✓
      Nested groups ✓
      Non-security groups ✓
      Distribution lists ✓
      Dynamic distribution groups ✓*
      Dynamic distribution lists  

      You can create a dynamic security group within Entra ID as long as you have a Premium P1 License (or higher.)

       


      2. Register a new application

      Open Azure and select App Registrations on the left sidebar.

      Axios In-House Azure Setup

      Click +New registration and register a new private application with the following:

      • Name: Axios HQ Directory Sync
      • Account Type: Accounts in this organizational directory only
      • Redirect URI: Skip this section

      Select Register

       

      3. Provide IDs to Axios HQ

      Once registered, you will be redirected to your Application Overview

      Use this outlined text file to fill out the information needed to complete the connection.


      This will direct you to a secure ShareFile link where you can download a txt file outlining the required information. Use it as you navigate through these instructions to gather the information HQ needs to setup your connection.

       

      Copy the Application (client) ID and the Directory (tenant) ID and include them in the document.
         

       

      4. Add API permissions

      Go to API permissions on the left sidebar and select +Add a permission

      In the Request API Permissions window, select Microsoft Graph

      Select Application permissions.

      Permissions are often misconfigured. 

      Please double check your settings as you add and remove the required authorizations:

      Remove the following permissions:

      • User.Read (Type: Delegated)

      Add the following permissions:

      • Group.Read.All
      • GroupMember.Read.All
      • User.Read.All

      Select Grant admin consent.

       

       

      5. Review attributes

      Axios HQ's Azure sync currently only requires the following attributes:

      Required Application Registration Attributes

      Group Attributes User Attributes
      id id
      displayName displayName
      description mail
      mail userPrincipalName
      visibility accountEnabled
      securityEnabled  
      groupTypes  

       

       

      6. Add Client credentials

      Navigate back to the Overview

      Under the Essentials heading, select Client credentials: Add a certificate or secret.

      Click +New client secret and add a client secret; give your secret a description, and choose an expiration date.

      We recommend the longest amount of time possible. When this secret expires, your users will no longer be able to access your directory through HQ.

      Copy the Secret ID and Value and provide them to Axios HQ.

      • The value will not be shown again.
      • Note that the secret values can only be viewed once, immediately after creation. Be sure to save the secret before leaving the page.

       

       

      7. Select groups (optional)

      Axios HQ allows you to sync your entire Azure directory or up to 15 specific groups. If you would like to limit the groups that sync to Axios HQ, please prove their Azure Object Ids.To locate the group Object Ids:

      Navigate to Groups on the left sidebar.

      Copy the Object Ids for the groups you would like to sync and provide them to Axios HQ.

       

       

      8. Optional Fields

      Include the following fields if they apply to your directory:

      Groups:

      As mentioned, Axios HQ allows you to sync your entire Azure directory or up to 15 specific groups. If you would like to limit the groups that sync to Axios HQ, please provide their Azure Object IDs.

      • Azure Object Ids, separated by commas

      Azure Government:

      Azure Government is a version of Azure that, compared to Azure Global, provides extra protection by limiting potential access to systems. It must be noted during setup.

      Is your team using Azure Government?

      • Yes, our team is using Azure Government
      • No, our team is using Azure Global

      Username fallback:

      Usernames are leveraged by some organizations in place of email addresses. Axios HQ can use the "username" field if no email address is provided.

      Should Axios HQ set the "username" field as a fallback?

      • Yes, use the "username" field as a fallback for email addresses
      • No, we do not use the "username" field as a fallback

      Contacts:

      Contacts are mail-enabled objects that are shared across the organization and contain external email addresses; they may have an internal address but it are not a member with login abilities. They differ from Users, who make up the internal members, such as employees or students.

      Should Axios HQ sync Contacts in addition to users?

      • Yes, sync Contacts in addition to Users
      • No, our organization does not leverage Contacts

       

      9. Finalize your setup

      Ensure you have the following required information:

      Axios HQ Organization

      • Your Organization's name: Include the name of the HQ organization you would like to link this directory to. If your team is leveraging multiple organizations, include all organizations this directory should be available within.

      Setup Owner:

      • Setup owner name and email address: this should be the best person for us to reach out to if we have any questions. Typically, this is whomever established the connection, an IT contact, or the Organization Owner.

      Application Registration Details:

      • Application (client) ID
      • Directory (tenant) ID
      • Client credentials Secret ID
      • Client credentials Value
      • Any optional fields

      📝 Use this document to send HQ your App Registration details.

       

      10. Sending your information to Axios HQ

      📬 Use this secure link to send your txt document containing:

      • Your Axios HQ Organization Name
      • Setup Owner Name and Email Address
      • Organization Name
      • Application (client) ID
      • Directory (tenant) ID
      • Client credentials Secret ID
      • Client credentials Secret Value
      • Any additional optional fields

       

      11. What your HQ users can expect

      Availability

      Your recipients are available after individually syncing a group.

      In the above example, All-Staff and Outreach have successfully synced. Engineering has encountered an error and should be reviewed by your IT team. To bring in another group, such as Management, simply select the "Sync to audience" check box and click "Update audience."

      Adding groups to your audience

      • To sync a directory group to your HQ audience, check the "Sync to audience" box and then click "Update audience." Your directory will sync, and your group members will populate.
      • The "Sync entire directory" checkbox is not currently operational of this type of Azure sync. If you would like to sync your whole audience, we recommend adding an All Staff list.

      Updates

      Your synced groups will update weekly; this means any members added or removed will be reflected on Monday.

      If you prefer to update your group before then, you can manually remove the group from your audience and re-sync it for an immediate update.

       

       

      12. FAQs

      My groups have no users

      Check your Application permissions in Azure:

      • Ensure that Group.Read.All, GroupMember.Read.All, and User.Read.All permissions are Type: Application permissions (and not Type: Delegated permissions)
      • Ensure that the User.Read permission is not enabled

      My directory is not up-to-date

      If your entire directory seems to be out of sync, check your authentication token's expiration date. If the token has expired, please send us a new one following this outlined document via this secure ShareFile folder and provide your new token, organization name, and IT contact information to us via this link.

      • Our team will update the token and provide confirmation that your sync is back online.

      My group is not up-to-date

      To troubleshoot a single group that may not have updated, first re-sync it to your audience.

      You can do this by navigating to your series then going over to Audience > Manage recipients > Manage from directory, and opening up the directory sync menu.

      • Deselect the group you need to update, then click "Update audience."
      • You should see this group disappear from your audience. Open up the menu one more and locate the group in your directory list. Check the "Sync to audience" box and click "Update audience again.
      • The group should return to your audience. If it is particularly large, please allow a few minutes for the group to fully re-sync before checking the audience count.

      If a re-sync does not work, check with your IT team. Whomever manages the Azure groups should be able to see how many members are in your audience. Ensure that no changes have been made to your Azure directory.

      • Axios HQ will not sync any members marked as "suspended," "disabled," or "inactive" in your directory. These members may be counted within Azure as part of the total group, but will not be ported over to Axios HQ.

      If you have tried the above and your numbers still seem incorrect, please reach out to our team at help@axioshq.com.

      What Azure types can Axios HQ sync?

      We currently support Global Azure and US Government Azure L4. We do not sync to Azure on-prem at this time.