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?

  • has the timeline on this altered? workspaceupdates.googleblog.com/2020/03/…
    – petednz - fuzion
    Commented Feb 14, 2021 at 21:53
  • @petednz-fuzion I didn't know that! That's good news. I edited my question to avoid scaring people. Commented Feb 14, 2021 at 22:32
  • Jon, your answer above worked great, except that for some reason it only works for a while, and then the access becomes lost. We've set this up for three separate instances of Civi and have had to re-do the steps three times now for all. Curious if you had any thoughts?
    – Kristin
    Commented Jul 8, 2022 at 22:59
  • @Kristin I haven't had that issue so I'm not sure what might be causing it. Commented Aug 16, 2022 at 19:54

1 Answer 1


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

On CiviCRM

On Google.com

If the steps belong don't work, check the "Prerequisites" section of the "Using OAuth 2.0 for Web Server Applications documentation to see if anything has changed.

  • 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.
  • 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 "[email protected]", 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).
  • wow. super comprehensive answer. great work.
    – petednz - fuzion
    Commented Feb 14, 2021 at 20:22
  • 1
    Just been trying to do this and it's worked great up until the fourth step up from the bottom: 'Add Mail Account' is still a button for me. Has something changed since this was written, or have I missed something somewhere? Commented Nov 19, 2021 at 15:20
  • 1
    For others experiencing the bug somnolentsurfer describes - it's a bug that's fixed in CiviCRM 5.44+. Commented May 26, 2022 at 22:22
  • Amazing work Jon. Thank you so much! Worked great and the step by step directions were spot on.
    – guyiac
    Commented Sep 30, 2022 at 19:11
  • 1
    I'd just use the internal option instead of external and stay in test mode. Commented Apr 13, 2023 at 22:44

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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