Configuring Google OAuth2 SMTP

This guide is for Cerberus administrators who want to set up Google OAuth2 for sending emails from the Cerberus server. This new authentication method, available in Version 2025.3, offers a more secure alternative to traditional basic authentication on the SMTP Event Target configuration page.

To use Google OAuth2 with Cerberus, you must perform a one-time setup that involves two distinct administrative roles:

• A Google Cloud administrator.
• A Google Workspace Super Administrator.

This process ensures that Cerberus is correctly authorized to send emails on behalf of a user in your organization via smtp.gmail.com.

This article focuses exclusively on the first part of this process: creating and configuring the credentials in your Google Cloud and Google Workspace environments. After completing these steps, you will use these credentials to configure the SMTP Event Target in Cerberus, as detailed in our separate support article Configuring SMTP To Send Email Notifications.

Prerequisites:

• A Google Workspace domain.
• Administrative access to the Google Cloud Console in order to create the Service Account.
• Super Administrator access to the Google Workspace Admin Console in order to enable domain-wide delegation.

Step 1: Create a Google Cloud Project for OAuth2

If you don't already have one, you'll need to create a Google Cloud Project. Every service account and API lives within a Google Cloud Project.

• Go to the Google Cloud Console at https://console.cloud.google.com/
• Click on the hamburger menu in the top left and select IAM& Admin > Create a Project.

• On the New Project screen:
  • In the Project Name field, enter a descriptive name for your project (e.g., "Cerberus Email Service")
  • Look for your organization's name (e.g., "cerberusftp.com") and ensure it is selected.
  • For the Location, click Browse and select your organization's folder.
  • Click Create.

After the project has been created, make sure it is selected in the project dropdown menu.

Step 2: Enable the Gmail API

This step is required to grant the Service Account permission to send emails.

• In the Google Cloud menu, select APIs & Services.
• Click on Library as shown above.
• In the search bar, type "Gmail API" and press Enter.
• In the project picker, select the project that you have created.
• Click on the Gmail API card in the search results.

• Once you click on the card as shown below, you will find a button to ENABLE if it's not already enabled.
• Click Enable to activate the Gmail API for your project.

Step 3: Create the Service Account and Key File for OAuth2

This Service Account will be the identity that Cerberus uses to authenticate before sending mail using Google SMTP Server (smtp.gmail.com).

• In the Google Cloud Console, navigate to IAM & Admin > Service Accounts.
• Click + Create Service Account.
• Enter a name for the Service Account (e.g., "Cerberus Mail Sender") and click CREATE AND CONTINUE.
• You can skip the optional roles and user access settings. Click DONE.

Step 4: Generate and Download the Private Key

This key file contains the credentials your Cerberus application needs.

• On the Service Accounts page, find your newly created Service Account and click its email address to open the details.
• Navigate to the KEYS tab.
• Click ADD KEY and select Create New Key.

• Choose JSON as the key type and click "CREATE".
• The JSON file will be downloaded to your computer. This is the only copy of this private key, so please be sure to save it in a secure location. You will need to provide the path to this file in Cerberus's UI.

Step 5: Enable Domain-wide Delegation

This step is required to allow the Service Account to send emails on behalf of a user. These steps must be performed by a Google Workspace Super Administrator.

Instructions for the Super Administrator:

• On the Service Account details page, find the "Unique ID" field (your Service Account's Client ID) and copy this value.

• Click Add New.
• In the Client ID field, paste the Unique ID you copied from the Service Account details.

• In the OAuth scopes field, enter https://mail.google.com
• Click AUTHORIZE.

Important Note on Security

• Principle of Least Privilege: A Service Account with Domain-wide Delegation has the potential to access all user data for the scopes you select. As a best practice, only assign the minimum necessary scopes (e.g., https://mail.google.com/ for email sending) to ensure the Service Account only has the permissions it needs.
• Service Account Key Security: The JSON key file you downloaded contains a private key. It is a powerful credential. Treat this file like a password and store it securely. Ensure that only authorized personnel have access to it.

We recommend to refer some important articles by Google on Service Account:

Google: Best Practices For Managing Service Account Keys

Google: Creating And Managing Service Account Keys

Troubleshooting

The following section provides steps for troubleshooting common issues that may arise when creating a Service Account or configuring Google OAuth2 for email notifications.

Can't Create a Google Cloud Project

Symptom: The "NEW PROJECT" button is disabled or you receive a "permissions error" when trying to create a project.

Likely Cause: You do not have the required permissions to create a project within the Google Cloud organization.

Solution:

• You need to have the roles/resourcemanager.projectCreator IAM role on your Google Cloud organization.
• You will need to contact your Google Cloud administrator to have this permission granted.

Can't Find "Gmail API" Role

Symptom: You are unable to search for or enable the "Gmail API" in the API Library, or you cannot find the "Gmail Send As" role in the IAM role list.

Likely Cause: Your Google Cloud Project is not associated with a Google Workspace organization. The "Gmail Send As" role and Domain-wide Delegation are exclusive to Google Workspace accounts.

Solution:

• Ensure you are signed in with a Google Account that is part of a Google Workspace domain.
• Go back to Step 1 in the documentation and create a new project under your organization's folder, not under a personal account.

Can't Create the Service Account or Key File

Symptom: You receive an error when trying to create a new Service Account or download its key file.

Likely Cause: Your user account does not have the necessary permissions within the Google Cloud Project to perform these actions.

Solution:

• To create a Service Account, you need the roles/iam.serviceAccountCreator role.
• To create a key file, you need the roles/iam.serviceAccountKeyAdmin role.
• If you are not a Project Owner, you will need to ask your Google Cloud administrator to grant you these roles.