This guide outlines the configuration and use of an Azure mailbox using the mailbox scan method.
In this lesson we will cover:
– How to set up a Mailbox in Halo using the Azure Mailbox scan method
This integration facilitates the connection of Azure mailboxes to Halo using the scan method, enabling the ingestion of received emails to create tickets. Incoming mail can take up to 5 minutes to be processed into Halo using this method. It also allows you to send emails from Halo through the connected mailbox. To initiate this process, you need to register a new application in Azure. You can choose to create a separate application for each mailbox if needed.
Things to note when using this method:
- Halo supports the connection to standard licensed mailboxes and shared mailboxes but does not currently support other mailbox types.
- This method can take up to 5 minutes to bring emails into Halo as tickets. To use webhooks (instant) mail processing method, please use this guide instead: Configuring An Azure Mailbox (The Webhook Method)
IMPORTANT: MAKE SURE THE INBOX IS EMPTY BEFORE ADDING AND CONNECTING TO THE HALO MAILBOX, IF IT IS NOT, ALL EMAILS IN THE INBOX WILL BE TURNED INTO TICKETS*.
To start setting up the mailbox head to configuration > email > mailbox setup > new > choose 'Mailbox connection type' to be 'Office 365/Azure".
Now you will need to configure and enter the credentials required to connect to the mailbox. There are a number of 'Credential Types' to choose from on the mailbox configuration page, if you are usure which credential type to use check out our article Authentication Methods for Microsoft Integrations.
Azure Connection Configuration
To register a new application in Azure, navigate to your Azure Active Directory page and select "App Registrations > New Registration." Provide a meaningful name for your application before proceeding to specify which account types should have access to your application.
Select "New Registration"
Fig 1. New registration in Azure
Select the "Single Tenant" account type and provide a web based URI redirect, the exact redirect URI you need to enter here can be found on the mailbox setup page in your Halo.
Fig 2. Application setup
Fig 3. Redirect URI required (sensitive information has been redacted)
Once registered, navigate to the 'Authentication' tab and add a second redirect URI, this should follow the format: https://YOURHALODOMAIN/auth/account/azureresponse (similar to the previous URI added).
Note down the Application (Client) ID and Directory (Tenant) ID as these are required later.
Fig 4. Application and Tenant ID
Navigate go to the "API Permissions" tab and click "Add a permission".
Fig 5. Add application permissions
Choose "Microsoft Graph" and "Delegated".
The necessary Graph API Permissions are listed below, with notes detailing their essential functions for the integration to work correctly. Once all permissions have been chosen, click the "Add Permissions" button to incorporate them into your application:
- offline_access
- Grants the app the ability to access and update data even during user inactivity.
- openid
- Enables users to sign in to the app using their work or school accounts.
- Allows the app to access basic user profile information, enabling the authentication process.
- email
- Allows the app to read users' primary email addresses.
- Essential for accessing email-related information and enhancing user identification within the Halo ITSM/PSA Solution.
- profile
- Enables the app to see users' basic profile information, including name, picture, username, and email address.
- Assists with mailbox verification during the authentication process.
- mail.readwrite
- Grants the app the ability to create, read, update, and delete emails in user mailboxes.
- Does not include permission to send mail but ensures comprehensive control over mailbox operations.
- mail.send
- Allows the app to send emails as users in the organization.
- Facilitates seamless communication within the organization directly from the Halo ITSM/PSA Solution.
- mail.readwrite.shared
- Only required if the mailbox being connected is a shared mailbox.
- Authorizes the app to create, read, update, and delete mail that a user has permission to access, including shared mail.
- Does not include permission to send mail but ensures effective management of shared mail within the solution.
- mail.send.shared
- Only required if the mailbox being connected is a shared mailbox.
- Allows the app to send emails as the signed-in user, including sending on behalf of others.
- Enhances collaborative communication by enabling users to send emails on behalf of their colleagues.
- Only required if the mailbox being connected is a shared mailbox.
Now grant admin consent for permissions. You can do this by clicking the grant admin consent at the top of the API Permissions list
Fig 6. Grant admin consent for all permissions
Navigate to the "Certificates and Secrets" tab, and under the Client Secrets section, register a new client secret. Choose an expiry length, but remember to update this value in Halo when it expires. Take note of the secret value as it cannot be retrieved again after leaving this page.
Fig 7. Secret Value
Halo Connection Configuration
Once you've registered the application in Azure and granted the necessary permissions, proceed to set up the mailbox in Halo.
If you're working with a shared mailbox, the user authorizing the connection in Halo must also have "Read and Manage" and "Send As" permissions for the shared mailbox. Ensure these permissions are added using the M365 Admin Centre and not through the Exchange Admin Console.
Complete the credentials including Client ID, Tenant ID, and Secret Value generated in the previous steps.
If you are on v2.182+ of Halo you will need to select the 'Credentials' button and enter the credentials here instead. If you are using multiple instances you can choose which instance the credentials relate to.
Fig 8. Fields in Halo for credentials (on versions 2.182+)
Once you have entered your credentials Click the "Authorize Application" button, on more recent versions this will be "Sign in with Microsoft" button. This action will redirect you to your tenant for sign-in using the details of the desired mailbox.
If you are authorizing a licensed mailbox:
Simply sign into your licensed mailbox using its username and password. This will allow Halo to finally be able to ingest emails as tickets and send emails out.
If you are authorizing a shared mailbox:.
Ensure the "Shared Mailbox" field is populated the shared mailbox's full address.
Ensure the licensed user is added as a delegate user on the shared resource with Read & Manage permissions granted via the M365 Admin Center's Manage Mailbox Permissions.
If either of these have not been configured correctly, it is possible that Halo will try to ingest emails from the authenticating licensed account rather than the shared mailbox. In case of this improper configuration, it is advisable to remove mail from the authenticating mailbox's inbox temporarily until after you can confirm that Halo is ingesting the correct mailbox's emails.
How to ensure that the authenticating account has access to the shared mailbox:
- Log into the authenticating account in Microsoft 365.
- Head to the shared mailbox via the 'Switch Account' option.
- Once in the shared mailbox, right-click on the inbox folder, go to Permissions, and ensure the authenticating (licensed) address is marked as having full access.
- If you do not see the licensed address in the permissions, please add it as an owner.
Fig 9. Open another mailbox option (switch account)
Fig 10. Opening the shared mailbox
Contact Imports (v2.168.1+)
Once you have connected you will see an additional tab titled 'contact imports' this can be used to import contacts from Outlook as users in Halo, using the connected mailbox.
If using this functionality you will need to add the following permission to your Azure application:
- Contacts.Read
Fig 11. Contact imports configuration
Before importing contacts you may want to create some contact mappings, this maps Outlook contact fields to user fields in Halo. To create a mapping simply use the 'Add' button to add a mapping to the table, select the Outlook field and Halo User field you would like to be associated, and hit save. New users that are created will be attempted to match to a site based on their email domain, if their domain cannot be matched to a site domain they will be assigned to the default site for new users.
The 'Import Contacts' button can be used to manually import contacts, but these can also be imported on a schedule using the Halo Integrator. The checkbox 'Enable the Halo Integrator for importing Outlook Contacts from
Common Errors
The first thing to try when a mailbox stops working and no error below matches your issue, is to Disconnect and then reauthorise the mailbox in Halo
| Error | Solution |
| Length Cannot Be less than zero (Parameter 'length') | When this occurs, you must create a new secret and make sure to copy the "Value" when generating the secret, not the Secret ID. Make sure to store this "Value" somewhere safe as it is important and can't be copied again after you click off the app registration page. |
| Error is not defined, and you are in doubt as of what to do | Disconnect and then reauthorise the mailbox in Halo if in doubt |
| Failed to retrieve agents – 400 Bad Request: "Token refresh failed – invalid_grant – AADSTS9002313: Invalid request. Request is malformed or invalid. | reauthorise mailbox, if not working try regenerating the secret, make sure to copy the "Value" when generating the secret, not the Secret ID. Make sure to store this "Value" somewhere safe as it is important and can't be copied again after you click off the app registration page. |
| Connection Failed for refreshing access token for mailbox ID 3 – AADSTS9002313: Invalid request. Request is malformed or invalid. | reauthorise mailbox, if not working try regenerating the secret, make sure to copy the "Value" when generating the secret, not the Secret ID. Make sure to store this "Value" somewhere safe as it is important and can't be copied again after you click off the app registration page. |
| Emails not coming through to halo but mailbox is working and inbox is being emptied? | Run Report “select top 100 * from incomingemail order by IEdatecreated desc” then do a ctrl + f for rule and check to make sure it isn’t being caught by an email rule, if it is, it will be evident on the report which email rule is binning off all emails. Emails can then be added back from the deleted folder (in your outlook account) to inbox and then they will be processed back into halo once placed into the inbox folder. |
.
