2

Google has announced that traditional username/password logins to G Suite mail accounts will be disabled and logins will require OAuth authentication in the future. The CiviCRM OAuth documentation partly explains how to configure OAuth with CiviCRM, but says, "After registering OAuth2 details with CiviCRM and Microsoft [sic], you can add an incoming email account." without explaining how.

How do I register my OAuth2 details with Google?

2
5

This assumes you've already created a G Suite user and can successfully log into their e-mail manually.

On CiviCRM

On Google.com

You need to complete the "Prerequisites" section of the "Using OAuth 2.0 for Web Server Applications documentation.

  • Open the API Library in the Google API Console.
  • Select GMail API from the list of APIs.
  • Click the Enable button.
  • Visit the Credentials Overview page.
  • Click OAuth consent screen (may be labeled Configure Consent Screen).
  • Select External user type and click Create. Note: Apps with external consent screens can require review from Google. However, "test mode" allows up to 100 users. Since you'll only have one user, you can keep your app in "test mode" indefinitely. enter image description here
  • Fill in the following information - App Name (whatever you like), User support email and Developer Contact Information (your email address), and the Authorized domains. This should be your site's domain. Note that you want only the "second level domain". E.g. if your site is "database.mysite.org", just enter "mysite.org".

Google OAuth consent screen setup screenshot

  • Press Save and Continue.
  • On the Scopes screen, select Add or Remove Scopes.
  • Add the openid and https://mail.google.com scopes. Google API scopes screenshot
  • Click Save and Continue.
  • For Test users, click Add Users and add the email address(es) of the incoming email accounts you created.
  • Click Save and Continue. enter image description here
  • Click Credentials in the left navigation menu.
  • Click Create Credentials » OAuth Client ID. enter image description here
  • Set Application Type to Web Application.
  • Set Name to whatever you'd like.
  • Click Add URI under Authorized Redirect URIs. Add the Redirect URL from the CiviCRM OAuth screen (see "On CiviCRM" above).
  • Click Create.
  • You should get a screen that says OAuth client created, with a Client ID and Client Secret. enter image description here
  • To retrieve these values at a later date, click the Edit icon next to the credentials you've just created. enter image description here

On CiviCRM

  • On The Google Mail OAuth screen you should already have open, paste in the Client ID and client secret you just retrieved from Google.
  • Click Add.
  • My old notes said to not click Add, and if you did by accident, remove all your login clients in Civi and in Google. I believe this is outdated but I'm leaving it here just in case it helps someone!
  • Go to CiviCRM's Administer menu » CiviMail » Mail Accounts.
  • Add Mail Account is no longer a button, but a select box. Select Google Mail.
  • You should see a Google login screen. Log in with the incoming email account's credentials.
  • CiviCRM should correctly autodetect all the correct values. Review and press Save. Note - if this is a bounce account, you still need to set the "localpart". E.g. if your bounce address is "unsuccessful@example.org", your localpart is unsuccessful+.
  • If you haven't already, don't forget to go to Administer menu » System Settings » Scheduled Jobs and enable the Process Inbound Email job (or Fetch Bounces if this is a bounce account).
1
  • wow. super comprehensive answer. great work.
    – petednz - fuzion
    Feb 14 at 20:22

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.