Set up Microsoft 365 OAuth authentication for use with Hesk
This guide works with Hesk version 3.4.0 and newer. To use OAuth, please upgrade to the latest version of Hesk.
Setting up OAuth (modern) authentication requires a bit of work and configuration; please be patient.
Microsoft is making rocket science out of email authentication, so blame them, not Hesk :)
What you will need:
- a Hesk administrator account,
- a Microsoft 365 administrator account,
- cURL support enabled in your PHP (check with your hosting company)
- to send emails, you will need to enable SMTP AUTH for the user account that you will use in Hesk. See Microsoft's guide here:
Enable or disable authenticated client SMTP submission (SMTP AUTH) in Exchange Online
Part 1: prepare Hesk
- login into your Hesk admin panel with an administrator account
We recommend opening Hesk in a private browser window when setting up OAuth (just Hesk, not the Azure portal mentioned in Part 2). This will make sure you are prompted to login into your Microsoft account when saving the OAuth Provider and can select the correct account you will use for Hesk.
- go to Hesk > Admin > Tools > OAuth Providers
- click the New Provider button
- give the provider a descriptive name, for example, "Exchange"
- keep the form open and continue with the registration steps below in a new browser tab or window
Part 2: register Hesk
- Open the Azure Active Directory App registrations page by clicking here.
Or manually navigate to the App registrations page:
- log in to Microsoft Azure at https://portal.azure.com
- search for and open the Azure Active Directory service,
- in the left menu under Manage click App registrations.
- click the + New Registration button in the top menu
- give the application a name, for example, Hesk OAuth or Help desk or something that will help you recognize it.
Under Redirect URI select Web and enter the full URL address of your Hesk oauth_providers.php file, for example:
Remember, this file resides inside the Hesk's /admin directory, so if you renamed the admin directory, make sure to set the correct Redirect URI!
It is very important to enter the correct URL of your oauth_providers.php file. You can copy the URL of the Hesk OAuth Providers page from your browser address bar and paste it into the Redirect URI box at Microsoft.
- click the Register button at the bottom to register Hesk
- copy the Application (Client) ID into Hesk > Tools > OAuth Providers > New Provider > Client ID field
- click the Endpoints link
- copy the OAuth 2.0 authorization endpoint (v2) (top most) URL into Hesk > Tools > OAuth Providers > New Provider > Authorization Endpoint URL field
- copy the OAuth 2.0 token endpoint (v2) (second from top) URL into Hesk > Tools > OAuth Providers > New Provider > Token Endpoint URL field
- under Client Credentials click the Add a certificate or secret link
- under Client Secrets click + New client secret
- give the secret a descriptive name, set Expires to 24 months, and click the Add button at the bottom
- copy the secret Value (not the Secret ID) by clicking on the copy icon and paste it into Hesk > Tools > OAuth Providers > New Provider > Client Secret field
- in the left menu click API permissions then + Add a permission
- select Microsoft APIs, then Microsoft Graph
- click Delegated permissions
- find and add these permissions; for example, in the Select permissions search box, type in these permissions one by one, and select each one:
Then click the Add permissions button at the bottom.
Your permissions page should now look something like this:
- go to your Hesk > Tools > OAuth Providers > New Provider form, and into the Scope box, enter (copy from below):
openid offline_access https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/POP.AccessAsUser.All https://outlook.office.com/SMTP.Send
- your New Provider form should now be full. Click Save, and you will be redirected to Microsoft for verification.
- at Microsoft, sign in with the account you will use in Hesk for email sending and/or fetching
- accept the permission request to allow Hesk to access the mailbox and/or send emails using the selected account
- Congratulations - your new OAuth provider is now (hopefully) registered in Hesk. You can go to the Hesk > Settings > Email page and select this OAuth provider for authentication.
Common problems and error messages
AADSTS50011: The redirect URI 'http://helpdesk.example.com/admin/oauth_providers.php' specified in the request does not match the redirect URIs configured for the application...
This means the oauth_providers.php URL address (configured under Part 2, step 3 above) is not correct.
To fix this:
- go to Azure Active Directory App registrations page (see Part 2, step 1 above)
- select (click on) the Hesk application registration
- in the left menu, click Authentication
- under Redirect URIs fix (or add) the correct Hesk oauth_providers.php URL
- save changes
Note: if you don't see "Redirect URIs" on the Authentication page, click + Add a platform, then Web and enter your oauth_providers.php URL address, then Configure button and save changes.
Hesk can connect to Office 365, but it doesn't find any unread emails (or downloads incorrect emails)
This issue is usually related with using the wrong Microsoft login when registering an OAuth provider. Try this:
- delete the OAuth provider from Hesk
- open Hesk in a PRIVATE BROWSING window to make sure you are not logged in anywhere
- add the OAuth provider again
- when adding it and asked to login, make 100% sure you login with the email account you will use for Hesk
When I return to Hesk from Office 365, the page is blank or shows a 500 Internal Server Error
The most common reason for a blank (500 Internal Server Error) error page when returning to Hesk's oauth_providers.php page is that your server does not have cURL enabled for PHP.
Ask your hosting company to enable cURL for your PHP installation, then try again.