OAuth2

Complete

Gmail OAuth2 configuration

Complete

The following instructions can be used to configure a Mail Server that connects to Gmail using OAuth2.
These instructions apply to the Email Document Loader Job as well, although the ports will be different.

1. In Administration - Organisation, create or edit a Mail Server

Enter the following details:

Name Gmail
Description Account settings for Gmail
Host smtp.gmail.com
Port 587
Timeout 120
Connection Security STARTTLS
Authentication Method OAuth2  - Gmail

2. Click Authorise

The first time this is done, a New OAuth2 Client Registration window will be displayed.
This prompts for the following details:

  • Client Id
  • Client Secret

These are obtained in the following steps. Note the Redirect URI.

3. Log in to https://console.cloud.google.com

Create a new project: https://console.cloud.google.com/projectcreate
Project name: OpenVPMS
Click CREATE
 

4. Enable the GMail API

 
i. Select API & Services from the Dashboard
ii. Select Enabled API & services
 
 
iii. Click ENABLE APIS AND SERVICES
 
iv. In the API Library, enter gmail api in the search field.
     Select Gmail API from the results.
 
 
v. Click ENABLE

5. App Registration
i. Under the APIs & Services, click OAuth consent screen
ii. If you are part of an Organisation , select Internal, else select External.
iii. Click CREATE

 
 
iv. On the OAuth consent screen, enter:
  • App name: OpenVPMS
  • User support email: an email address for users to contact you with questions about their consent
  • Under Developer contact information, enter:
 
 
v. Click SAVE AND CONTINUE
 
vi. On the Scopes screen, click ADD OR REMOVE SCOPES
vii. In the Updated selected scopes popup, under Manually add scopes, enter:
    https://mail.google.com
    and click ADD TO TABLE
viii. In the table, select:
and click UPDATE
 
 

ix. On completion, Your non-sensitive scopes should display:

  • .../auth/userinfo.email
  • .../auth/userinfo.profile
  • openid

while Your restricted scopes should display:

Click SAVE AND CONTINUE
 

6. Test users

i. Click ADD USERS
ii. In the Add users popup, enter the email addresses of the users whose accounts will be access by OpenVPMS
iii. Click ADD
 

 

iv. Click SAVE AND CONTINUE

7. Credentials

i. Under APIs & Services, select Credentials
ii. Click CREATE CREDENTIALS
iii. Click OAuth client ID

 

iv. Under Create OAuth client ID, enter

v. Click CREATE

A popup will display, containing the Client ID and Client Secret:

Gmail is now ready to accept authorisation.

8. Update OAuth2 Client Registration

Back in the OAuth2 Client Registration editor, enter the Client Id and Client Secret.
 

 

    Click OK. This should automatically start the Authorise flow. A new browser will be displayed.

    After logging in, follow the prompts, and select 'Read, compose, send and permantly delete all your mail from Gmail'

Click Continue.

 

9. Check Authorisation

In the Mail Server window, click Check Authorisation.

    If successful, the Gmail account will appear in the Username field. Click OK.

 

10. Troubleshooting

Authorisation will fail if details haven't been entered correctly. Google error messages can be range from the helpful "Access blocked: authorisation error. The OAuth client was deleted" (indicating that a OAuth 2.0 Client IDs has been deleted in the Google console), to the not so helpful "Sorry, something went wrong there. Try again". 

If authorisation fails, ensure that the:

1. The Client Id and Client Secret from step 7 v. have been correctly entered in the OAuth2 Client Registration window in step 8.

2. Authorized redirect URI in step 7 iv matches that shown in step 8.

3. Scopes match those in step 5 ix.

If the above all match, try performing authorisation in a different browser. The "Sorry, something went wrong there. Try again" error has been seen in Firefox (117.0), but was resolved by using Google Chrome (116.0). 

 

Microsoft Outlook OAuth2 configuration

Complete

The following instructions can be used to configure a Mail Server that connects to Microsoft Outlook using OAuth2.
These instructions apply to the Email Document Loader Job as well, although the ports will be different.

1. In Administration - Organisation, create or edit a Mail Server

Enter the following details:

Name Microsoft Outlook
Description Account settings for Microsoft Outlook
Host smtp.office365.com
Port 587
Timeout 120
Connection Security STARTTLS
Authentication Method  OAuth2  - Outlook

2. Click Authorise

The first time this is done, a New OAuth2 Client Registration window will be displayed.
This prompts for the following details:

  • Tenant Id
  • Client Id
  • Client Secret

These are obtained in the following steps. Note the Redirect URI.

3. Log in to https://portal.azure.com/

Select Manage Azure Active Directory


 

4. Click App Registrations

5. Click New Registration

This displays a Register an application page.

Enter:

6. Click Register

This displays an Overview page.

The Application (client) ID is copied into the Client Id field in step 3
The Directory (tenant) ID is copied into the Tenant Id field 3
 

7. Click Certificates & secrets

8. Click New client secret

This displays a popup. Enter:

  • Description: OpenVPMS
  • Expires: select an expiry date. This should be well into the future, as when the secret expires, mail access will fail

9. Click Add

This displays the new secret. The Value field must be copied to the Client Secret field in step 3.

10. Click Client API permissions

11. Click Add a permission

This displays a Request API permissions popup.

Select Microsoft Graph.

12. Select Delegated permissions

Then select the permissions:

  • email
  • offline_access
  • openid
  • IMAP.AccessAsUser.All
  • SMTP.Send

Click Add permissions.

 

On completion, API permissions should look as follows:

13. Microsoft is now ready to accept authorisation.

Back in the OAuth2 Client Registration editor, enter the Tenant Id, Client Id and Client Secret.
 

Click OK. This should automatically start the Authorise flow. A new browser will be displayed.

After logging in, follow the prompts:

 

14. In the Mail Server window, click Check Authorisation

If successful, the Outlook account will appear in the Username field.

Click OK.