The integration with Entra ID allows you to send/read in HotH emails from a M365 account. To get up and running, you need to add a new Application Registration in Entra ID.
Prerequisites
For sending emails from HotH, the designated end-user account must have Authenticated SMTP enabled in: M365 Admin Centre, Active Users, open the end-user account details, Mail, Manage email apps, tick Authenticated SMTP. You’ll also want to tick POP here (or IMAP) if you wish HotH to add emails as Tickets in the system.
1. Add an Application Registration in Entra ID
- Navigate to the Microsoft Entra ID section of the Azure Portal.
- In the App Registrations section, click to add a New Registration:
- Give it a name – e.g. HotH email integration.
- Under Supported Account Types, select Accounts in this organizational directory only.
- Under Redirect URI (optional) – Select Web in the first dropdown and enter your HotH system URL – ask HotH if you’re unsure what this is.
- Click Register to then be presented with an Overview page.
- Make a note of the following for later use (or send to HotH if you want help completing
the setup):
o Application (client) ID.
o Click on the Endpoints tab and copy the top two entries:
OAuth 2.0 authorization endpoint (v2)
OAuth 2.0 token endpoint (v2)
- Click the Certificates & secrets link on the left hand side.
- Click + New client secret in the Client secrets section:
- Set Expires to 24 months and click Add (you don’t need to give it a Description).
- Copy the Value (not the Secret ID) of the newly generated Secret. **You won’t be able to see it
again**:
- Click on API Permissions link on the left hand side.
- Click + Add a permission
- On the Microsoft APIs tab, click on Microsoft Graph, then Delegated permissions.
- Tick the following options:
o offline_access (under OpenId permissions section)
o POP.AccessAsUser.All (under POP section)
o SMTP.Send (under SMTP section)
o Most customers choose to use POP protocol for HotH to monitor a mailbox. However, if IMAP protocol is preferred, then ignore the POP line above and add the IMAP scope instead: IMAP.AccessAsUser.All (under IMAP section). N.B. You should not usually require both POP and IMAP. - Click Add Permissions button at the bottom.
- Configured permissions should have been added:
- Click Grant admin consent for … and click Yes on the confirmation popup. The Status field should now read Granted for… against all the permissions.
- Click to view Enterprise applications via the link at the bottom of the API Permissions summary screen.
- If not opened automatically, locate and open the Enterprise Application with the same name as the App Registration you just created.
- Click the Properties menu item.
- Select Assignment Required = Yes (this ensures only the specific end-user can request a token)
- Save
- Click the Users and groups menu item. This is where you’ll add the end-user allowed to use the app.
- Click + Add user/group
- Click on None Selected under Users and groups.
- Click the required end-user (the account which will be used to send/read emails from HotH) and click the Select button.
- Click the Assign button
2. HotH Configuration and Authentication
- Log in to your HotH hosted system as a Supervisor login on an Incognito/InPrivate browser window (to ensure not logged in to Microsoft).
- Click on the Settings Cog
and select More Tools, OAuth Scripts - Add a new script using the + button, making sure you start the script with the prefix oauth: (e.g. oauth:email). You may wish to use the same name as the App Registration here for simplicity.
- Fill in the following fields with the data noted during the App Registration:
o Application (client) ID
o OAuth 2.0 Auth Endpoint (v2)
o OAuth 2.0 Token Endpoint (v2)
o Client Secret - Enter the URL of your HotH hosted site in the Redirect URI field.
- In the Authorization Scope field, copy and paste the following text to auth HotH for POP and SMTP access (amend accordingly if IMAP is preferred):
offline_access https://outlook.office.com/POP.AccessAsUser.All https://outlook.office.com/SMTP.Send - Click Save
- Click Auth
- You will now be redirected to a Microsoft Login page – log in using the end-user account you wish to use for sending/reading in HotH emails. It is important to log in as the correct user here.
- You should then be redirected back to the HotH OAuth script (now showing an Authorization token). Setup is complete. OK the script. You do not need to stay signed in as the MS user.
- If authorisation fails, try opening a new tab in the browser and browse to any M365 service page. Log out of Microsoft as yourself. Click back to your HotH tab and click the Auth button again. You should now be redirected to a Microsoft login page where you can log in using the account to be used for HotH emails.
3. HotH Email Setup
Your HotH email setup may differ from the notes below. Please ask HotH for assistance if you are unsure about any of the following settings. HotH email setup is usually completed by HotH support but is noted here for general information.
Outbound Email:
- To configure HotH to use the new OAuth script for outbound emails, click on the Settings Cog and select Email Settings.
- Click Outbound Email Settings at the top, click the Modify button, and complete the fields:
o SMTP Server = smtps:smtp.office365.com:587
o SMTP Account = the end-user account which will send your HotH-generated emails
o SMTP Password = the name of the HotH OAuth script you just created, prefixed with oauth: (e.g. oauth:email). - Click OK
- Ensure that the From address on the HotH email templates matches the end-user you wish to send HotH-generated emails from.
- Outbound email as the end-user should now work.
Inbound Email:
- Once you have competed the authorisation process you then need to update the credentials of the POP mailbox. The password needs to be updated to the name of your OAuth:*** email script.
- Firstly, look on the default Folder (Settings Cog > Folders) in the Email section, click Modify to amend the password on the POP3 Password settings. If the POP credentials are not here, try the Settings Cog > Email Settings > Inbound Email Settings
- Please Contact HotH if you require assistance with the automatic creation of new tickets from incoming emails.
Still haven’t found what you’re looking for? Contact documentation@houseonthehill.com
