Use Gmail with OAuth2

In the old days, a user would be able to log into Gmail with their email address and password. However, when a user enables 2 factor authentication, this is not possible anymore. One way to circumvent this, is the configuration of an App Password or LSA, but Google itself does not recommend this :

Tip: App Passwords aren’t recommended and are unnecessary in most cases. To help keep your account secure, use “Sign in with Google” to connect apps to your Google Account.

Warning

LSA were supposed to be phased out by 2020. Also, in case you have not clicked the link above, LSA means ‘Less Secure App’ . Please do not use these anymore!

This guide contains a HOWTO on how to connect your Gmail account through OAuth2 with Group Office.

Create an app

Note

Please read the full documentation for OpenID Connect for full context.

  1. Log into Google using your gmail credentials.

  2. Open the Credentials page in the Google API Dashboard.

  3. Click the button Create Credentials > OAuth client ID

../../_images/google-credentials-dashboard-1.png

  1. A new form is opened.

    1. Enter a name for your app in the field ‘name’.

    2. Enter one or more URIs in the field ‘URIs’ under the header ‘Authorized JavaScript origins’. These should match the URL configuration setting in your Group Office instance.

    3. The field ‘URIs’ under the header ‘Authorized redirect URLs’ should contain the value https://yourhost/go/modules/community/oauth2client/gauth.php/callback. ‘Yourhost’ refers to the URL configuration setting of your Group Office instance.

    4. In the right column, a Client ID, a Client Secret and a Creation date are displayed. Write these down or download the JSON credential file by clicking the ‘Download JSON’ button

../../_images/google-credentials-dashboard-2.png

  1. The next step is to customize the OAuth consent screen:

    1. In the first step, enter an App Name (to be displayed to the end user), a support email address (yours). Fill in the rest of your form as per your domain settings.

    2. In the Scopes Step, be sure to add the scope ‘https://mail.google.com’.

    3. The next step is to add test users if needed. Please note that your default email address already has access.

    4. Confirm your settings. Currently, your app is in testing mode. Click the button ‘publish app’ to move to production. This may take some time.

Note

Once an app has been published, anybody with a Gmail account can use this app. Furthermore, refresh tokens will expire while your app remains in test mode.

Configure Group Office

In System settings > OAuth2 Client Settings, when you add an Google connection, the following fields should be entered:

  • Select “Google” as provider

  • The Client id field is the Application ID of your app.

  • The Client secret is the client secret you should have written down in step 1d above. Please make sure that you write down the value of the secret, not the Secret ID.

After saving, you can configure the email accounts as per the generic documentation.

A note to developers

When using the official Group Office development environment, please make sure to set the URL to http://localhost:8000 in the system settings. Localhost is the only non-https URL that accepted by Google. You cannot use http://host.docker.internal:8000 as the URL in your system configuration.