Help Desk Software

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:

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

    New OAuth provider
     

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

    New app registration
     
  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.

    Register an application
     
  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

    Application registered

  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
     
    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 setup
     
  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

    Client secret value
     
  13. in the left menu click API permissions then + Add a permission

    API permissions
     
  14. select Microsoft APIs, then Microsoft Graph

    Microsoft Graph API
     
  15. click Delegated permissions

    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

    IMAP AccessAsUser All permission

    Then click the Add permissions button at the bottom.

    Your permissions page should now look something like this:

    Final app permissions
     
  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.

    Filled in New OAuth provider form
     
  19. at Microsoft, sign in with the account you will use in Hesk for email sending and/or fetching

    Microsoft OAuth consent (permissions requested) page
     
  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.
     
    OAuth provider verified

 

 

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

URL mismatch error

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.

 

 

Help Desk Software