For the "Allow Mail" functionality implemented "Gmail API" integration via "OAuth2 Google Cloud authentication" using a "Google Service Account" for "impersonation" with "Domain Wide Delegation" for any Email send-out from the farmerswife (fw) Server app!
Background: Gmail has deprecated "basic" authentication in Q3 2024!
The previously working "Gmail > App Password" no longer works!
Requires:
- You need to use a "Google Business" account in order to be able to use the "Google API" in combination with "Google Service Accounts", "Impersonation" and "OAuth2 Google Cloud authentication" and "Domain Wide Delegation".
These features are not available in a free Gmail account. - Before you get started, ensure your Google user has a "Super Admin" Google Cloud Permission level!
- And identify the email address to be used as "FROM:" for all emails sent from your farmerswife system.
- Ensure you can sign in with this user on these to platforms:
Step 1: Create a New Project
Open a web browser and go to the Google Cloud Console: https://cloud.google.com/
At the top click on the "Select a resource" selector and and click on the "NEW PROJECT" button:
Give your Project a unique and recognizable name; e.g. "farmerswifeAllowMailGmailAPI" and click on "CREATE":
Step 2: Create a Service Account
If not already still there, go to the Google Cloud Console: https://console.cloud.google.com
Make sure you're inside the correct Project you created in the previous step, here called "farmerswifeAllowMailGmailAPI".
In the navigation menu on the left and select: IAM & Admin > Service Accounts.
Click on the CREATE SERVICE ACCOUNT button.
Give your Service Account a descriptive name, e.g. "fwAllowMailGmailAPI-ServiceAccount" .
Use the "CREATE AND CONTINUE" button:
Step 3: Grant Service Account access to the Project
On the "Grant this service account access to project" for "fwAllowMailGmailAPI-ServiceAccount" leave everything "default".
Click on CONTINUE:
Step 4: Grant users access to this service account
On the "Grant users access to this service account (optional)" for "fwAllowMailGmailAPI-ServiceAccount" leave everything "default".
Click on DONE:
After creating the Service Account, click on it to see the "DETAILS" tab and copy & save it's "Unique ID"; this is the "Client ID" you will need on the below Step 7:
Still on the Service Account you just created, here called "fwAllowMailGmailAPI-ServiceAccount" go to the KEYS tab of your Service Account.
Click the ADD KEY button and select Create new key:
Choose the Key type as JSON.
Click CREATE:
A JSON file containing the private key will be downloaded to your local computer.
Save this file securely as it will be used to authenticate your application with Google Cloud!
Keep the JSON private key confidential. Do not share it publicly or embed it directly in your code. Consider storing it securely using Google Cloud Secret Manager.
Step 6: Enable the Gmail Api
If not still there, go to the Google Cloud Console: https://console.cloud.google.com
Make sure you're inside the correct Project you created in the previous step, here called "farmerswifeAllowMailGmailAPI".
In the navigation menu on the left and select:
APIs & Services > Enabled APIs & services and then click on "+ ENABLE APIs AND SERVICES":
And on the "Welcome to the API Library" search for: gmail api ...
... and select the search result to end up here:
Click on the "Gmail API" search result and then click on "ENABLE":
Step 7: Enable "domain wide delegation
For this step you need to switch to this platform: https://admin.google.com
And you need to sign in as a "Google Workspace Admin".
On the left main navigation menu go to:
Security > Access and data control > API controls and on the API controls page click on the "MANAGE DOMAIN WIDE DELEGATION" option:
On the Domain-wide delegation page use the “Add new" button:
On the "Add a new client ID" pop-up window copy & paste the "Unique ID" of the Service Account from above
"Step 4: Grant users access to this service account" into the Client ID field.
And add only this restricted "OAuth scope" (updated 2024-11-05):
https://www.googleapis.com/auth/gmail.send
Click on AUTHORIZE to finish this step:
By following these steps, you'll have a Google Cloud Platform Service Account with the necessary permissions and private key for integrating with the Gmail API using impersonation and OAuth2 authentication.
Step 8: Applying the configuration on the fw Server app
After you have created the Google Cloud Platform Service Account within a Project, granted the needed Permissions and downloaded the JSON private key via "Google Cloud IAM & Admin" you are now ready to finish this configuration.
Continue by renaming the generated and downloaded private JSON file to: "google-service-private-key.json" and upload it to your farmerswife Server app's "system" folder.
You also need to use the optional farmerswife Server-side "server.cfg".
If you have never used it, carefully review the detailed info here.
Do the following steps:
- While working on the server.cfg file, ensure the fw Server app is not running!
- Download the pre-configured "server.cfg" from the bottom of this article, which only contains these 2 new variables; or if you are already using the server.cfg simply copy and paste these 2 variables at the bottom of all already existing variables:
GMAIL_OAUTH2_ENABLED 1 GMAIL_OAUTH2_IMPERSONATIONEMAIL example@mydomain.com
Open the server.cfg file in a Text Edit program and change "example@mydomain.com" to use an existing qualified email address from within your Google Cloud environment. This email address is going to be used as the "FROM:" email address.
Save the changes. And copy this server.cfg into the "system" folder of your fw Server application, if you have not used it before.
Launch your farmerswife Server app.
Then go to your running farmerswife Server app > Setup button > General tab > to configure these settings
Allow Mail: Yes
Outgoing Mail Server (SMTP): keep empty, it's not in use.
Sub-menu > Use TLS: No ... it's not in use; if you enable it, you'll get a "TLS handshake" error.
Port: 0
Use the "Test" option on the "Allow Mail" sub-menu, to ensure the fw Server app can now send impersonated emails through your Google Cloud, see the following scree shot.
And if you encounter issues, enable the "MAIL DEBUG" option on Allow Mail sub-menu. After closing the fw Server app's Setup window, the de-bug info after having used the "Test" button will get flushed into the log.txt located within the fw Server app's "system" folder:
Please feel free to send us feedback; you might know an even better way on how to configure this.