Set up Gmail 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 authentication requires a bit of work and configuration; please be patient.
Unless you are a Google Workspaces user or plan to verify (Publish) your help desk application on Google, note that OAuth refresh tokens will expire every 7 days in Google. In this case, you may want to set up an App Password instead and use Basic authentication.
What you will need:
- a Hesk administrator account,
- a Google account,
- your Google mail (Gmail) account must have IMAP enabled to allow fetching emails,
- cURL support enabled in your PHP (check with your hosting company)
Part 1: prepare Hesk
- login into your Hesk admin panel with an administrator account
- go to Hesk > Admin > Tools > OAuth Providers
- click the New Provider button
- give the provider a descriptive name, for example, "Google"
- into the Authorization Endpoint URL field, enter:
- into the Token Endpoint URL field, enter:
- keep the form open and continue with the registration steps below in a new browser tab or window
Part 2: register Hesk
- Open the Google API Console.
- on the Enabled APIs & services page, click the CREATE PROJECT link
- give the application a name, for example, Hesk OAuth or Help desk or something that will help you recognize it, then click the CREATE button.
- when the project is created, click the + ENABLE APIS AND SERVICES link
- in the search box, search for Gmail api
- select the Gmail API from the list and click the ENABLE button
- open the OAuth consent screen, select desired user type, and click CREATE
- enter your help desk details (App Name, User support email, Developer email) and click SAVE AND CONTINUE
- on the next Scopes sub-page, click ADD OR REMOVE SCOPES
- in the filters box, type in Gmail API and select it - the one with the scope set to https://mail.google.com/
- click the UPDATE button at the bottom to add the Gmail API scope
- at the bottom of the app registration page, click SAVE AND CONTINUE
- on the Test users page, click + ADD USERS, then select the email account you will use with Hesk and add it.
When all the users you need are added (likey just the one you will use to send/fetch emails in Hesk, or maybe another test one), click SAVE AND CONTINUE
- now open the Credentials page and click + CREATE CREDENTIALS, and select OAuth Client ID
- under Application type select Web application, and give it a name
- under Authorized redirect URIs click ADD URI and enter your 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 Authorized redirect URIs box at Google.
- click CREATE
- copy Your Client ID into Hesk > Tools > OAuth Providers > New Provider > Client ID field
- copy Your Client Secret and paste it into Hesk > Tools > OAuth Providers > New Provider > Client Secret field
- go to your Hesk > Tools > OAuth Providers > New Provider form, and into the Scope box, enter (copy from below):
- your New Provider form should now be full. Click Save, and you will be redirected to Google for verification.
- at Google, sign in with the account you will use in Hesk for email sending and/or fetching
- on the Google hasn't verified this app page, click Continue
- click Continue on the permission request page 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.