Connecting an Azure AD (Entra ID) Application Registration

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

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. Update your existing connection
13. 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!

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!

Application Registration Sync Capabilities

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

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

 

---

2. Register a new application

Open Azure and select App Registrations on the left sidebar.

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

 

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:

 

---

 

5. Review attributes

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

Interested in syncing more attributes? Check out the "Optional fields" section below!

---

 

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 individual, 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 select specific groups. If you would like to limit the groups that are visible to your users in Axios HQ, please provide their Azure Object IDs.

• Azure Object IDs, separated by commas

Attributes:

Allow Axios HQ users to create dynamic recipient lists by utilizing employee attributes. Syncing attributes will pull in each of the below fields to HQ; your team can approve the visibility of these attributes at the time of setup to tailor what users will be able to see and leverage within the platform. For custom attributes, simply provide the desired field name.

• A list of the below attributes that should be visible/available to your users
• Custom attribute names, 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
  • 🛠️ Note: Please add the OrgContact.Read.All permission to your registered application to enable the contact sync
• 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.

Directory updates

Your synced groups will update nightly at midnight EST; 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. Update your existing connection

🔒 Update your secret

Azure secrets are set to expire after a certain amount of time. Once your setup is connected, it's typically good to go for a year or two, depending on the client credentials expiration date your team selected.

If you need to update your secret, navigate to Azure, find the App Registration you've created for Axios HQ, and generate a new one.

Generate a new secret by following these steps in Azure:

• Navigate to App Registrations on the left navbar
• Select the Axios HQ application you registered for this sync
• Navigate to "Certificates & secrets"
• Select the "Client secrets" tab
• Select "New client secret"

Please provide us with the secret value that is generated. This can be a simple txt file.

📝 Fill out this document and share it with us via this secure ShareFile link.

 

⭐ Update your optional fields

Optional fields including syncing specific groups, attributes, or Contacts can be edited at any time. Review what we have available in the Optional Fields section above, and send us any edits you'd like using the form below!

📝 Fill out this document and share it with us via this secure ShareFile link.

---

 

13. FAQs

Incorrect Directory Groups & Members

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
• If you are expecting Contacts, please make be sure to specify this at the time of setup. You will  also need an extra permission in your App Registration: OrgContact.Read.All

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 specific group is not up-to-date

Our directories sync overnight, so if you have membership that was edited after midnight EST, we recommend resyncing the group you wish to send to. 

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 only syncs valid members of your directory.
  • We 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.
  • This includes group objects. Although Axios HQ does not bring in the group object as a member, any membership of the groups that are nested will be properly reflected in the parent group. For example, if a Parent Group (of 1 direct member and 1 nested group) included a Child Group (with 5 direct members,) the flattened Parent Group in HQ would appropriately have 6 recipients. In Azure, you may see "7 members" because the group itself is included in this count.

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

Updating the Sync

My Azure secret has (or will) expire. How can I send a new one?

Send us a new Azure secret by filling out this form. Please be sure to include your HQ organization

How do I edit / add / remove groups from this connection?

• Edit groups within Azure. The changes will automatically sync to HQ.
• Add or remove groups from this connection by reaching out to us at help@axioshq.com.

Azure Connection

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.