Set up Microsoft 365 OAuth authentication for use with 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

1. 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.

2. go to Hesk > Admin > Tools > OAuth Providers
    
3. click the New Provider button
    
4. give the provider a descriptive name, for example, "Exchange"
    
5. keep the form open and continue with the registration steps below in a new browser tab or window
   
   
    

Part 2: register Hesk

1. 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.
    
2. click the + New Registration button in the top menu
   
   
    
3. 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:
   https://helpdesk.example.com/admin/oauth_providers.php
   
   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.

   
    
4. click the Register button at the bottom to register Hesk
   
   
5. copy the Application (Client) ID into Hesk > Tools > OAuth Providers > New Provider > Client ID field
   
   
   
   
6. click the Endpoints link
    
7. copy the OAuth 2.0 authorization endpoint (v2) (top most) URL into Hesk > Tools > OAuth Providers > New Provider > Authorization Endpoint URL field
   
   
8. copy the OAuth 2.0 token endpoint (v2) (second from top) URL into Hesk > Tools > OAuth Providers > New Provider > Token Endpoint URL field
   
   
9. under Client Credentials click the Add a certificate or secret link
    
10. under Client Secrets click + New client secret
     
    
    
    
11. give the secret a descriptive name, set Expires to 24 months, and click the Add button at the bottom
    
    
    
    

    Client secret has an expiration date. Remember to create a new client secret when the existing one expires (add a reminder to your calendar)!

    
     
12. 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
    
    
     
13. in the left menu click API permissions then + Add a permission
    
    
     
14. select Microsoft APIs, then Microsoft Graph
    
    
     
15. click Delegated permissions
    
    
     
16. find and add these permissions; for example, in the Select permissions search box, type in these permissions one by one, and select each one:
    
    offline_access
    openid
    IMAP.AccessAsUser.All
    POP.AccessAsUser.All
    SMTP.Send
    
    
    
    Then click the Add permissions button at the bottom.
    
    Your permissions page should now look something like this:
    
    
     
17. 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
    
    
18. your New Provider form should now be full. Click Save, and you will be redirected to Microsoft for verification.
    
    
     
19. at Microsoft, sign in with the account you will use in Hesk for email sending and/or fetching
    
    
     
20. accept the permission request to allow Hesk to access the mailbox and/or send emails using the selected account
     
21. 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:

1. go to Azure Active Directory App registrations page (see Part 2, step 1 above)
2. select (click on) the Hesk application registration
3. in the left menu, click Authentication
4. under Redirect URIs fix (or add) the correct Hesk oauth_providers.php URL
5. 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 usually happens when OAuth configuration in Hesk is done when logged into another Microsoft365 account.

Try this:

1. open Hesk in a PRIVATE/INCOGNITO browser window to make sure you are not logged in anywhere
2. go to Tools > Oauth Providers
3. click the "Edit" icon next to your Microsoft 365 OAuth provider
4. click "Save"
5. you will be prompted to login into Microsoft 365; make 100% sure you login with the email account you will use in Hesk
6. when back at Hesk, go to Settings > Email
7. test the IMAP email connection; it should show the correct number of unread emails now (make sure you have at least one unread email inside your mailbox when testing)

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.

Email connections worked normally, but suddenly stopped.

Perhaps the OAuth credentials have expired or have changed? Especially note that the "Client Secret" is valid for a maximum of 24 months (this is a Microsoft limit), and then it has to be renewed.

Check your Azure Active Directory App registrations page to see if the "Client Secret" has expired perhaps. Get the new client secret and update your OAuth provider:

1. open Hesk in a private (incognito) browser window to make sure you are not logged in anywhere
2. go to Hesk Tools > OAuth Providers
3. click the "Edit" icon for your provider
4. update all the details, such as the client secret
5. click "Save" and you will be redirected to Microsoft
6. Make 100% sure you login with the email account you use in Hesk into Microsoft
7. when you get back to Hesk, go to Settings > Email and test the email connections again (test SMTP, IMAP and/or POP3)

Note: you should repeat the above process even if your client secret is still valid.