Skip to content

[IMP] General: Google Oauth Docs edit #3965

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
tiku-odoo wants to merge 1 commit into from
Closed

[IMP] General: Google Oauth Docs edit #3965

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 96 additions & 73 deletions content/administration/maintain/google_oauth.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,64 +21,87 @@ Setup in Google
Create a new project
--------------------

To get started, go to the `Google API Platform
<https://console.cloud.google.com/apis/credentials/consent>`_. Log in with your *Google Workspace*
account if you have one, otherwise log in with your personal Gmail account (this should match the
email address you want to configure in Odoo).
To get started, go to the `Google API Console <https://console.developers.google.com>`_. Log in
with your *Google Workspace* account if you have one, otherwise log in with your personal Gmail
account (this should match the email address you want to configure in Odoo).

After that, click on :guilabel:`Create Project`, located on the far right of the OAuth consent
screen. If a project has already been created in this account, then the :guilabel:`New Project`
option will be located on the top left under the :guilabel:`Select a project` drop-down menu.
After that, click on :guilabel:`Create Project`, located on the far right of the :guilabel:`OAuth
consent screen`. If a project has already been created in this account, then the :guilabel:`New
Project` option will be located on the top right under the :guilabel:`Select a project` drop-down
menu.

On the :guilabel:`New Project` screen, rename the :guilabel:`Project name` to `Odoo` and browse for
the :guilabel:`Location`. Set the :guilabel:`Location` as the `Google Workspace` organization. If
you are using a personal Gmail account, then leave the :guilabel:`Location` as `No Organization`.
On the :menuselection:`New Project` screen, rename the :guilabel:`Project name` to `Odoo` and
browse for the :guilabel:`Location`. Set the :guilabel:`Location` as the *Google Workspace
organization*. If you are using a personal Gmail account, then leave the :guilabel:`Location` as
:guilabel:`No Organization`.

.. image:: google_oauth/new-project.png
:align: center
:alt: Project Name and Location for Google Oauth.
:alt: Project Name and Location for Google OAuth.

Click on :guilabel:`Create` to finish this step. On the next screen, :guilabel:`User Type` options,
select the :guilabel:`External` option, and then click on :guilabel:`Create` again, which will
finally navigate to the :guilabel:`Edit app registration` page.
Click on :guilabel:`Create` to finish this step.

OAuth consent screen
--------------------

If the page doesn't redirect to the :menuselection:`User Type` options, click on :guilabel:`OAuth
consent screen` in the left menu.

Under :guilabel:`User Type` options, select the appropriate :guilabel:`User Type`, and then click on
:guilabel:`Create` again, which will finally navigate to the :menuselection:`Edit app registration`
page.

.. warning::
*Personal* Gmail Accounts are only allowed to be **External** User Type, which means Google may
require an approval, or for *Scopes* to be added on. However, using a *Google WorkSpace* account
allows for **Internal** User Type to be used.

Note, as well, that while the API connection is in the *External* testing mode, then no approval is
necessary from Google. User limits in this testing mode is set to 100 users.

Edit app registration
---------------------

- On the :guilabel:`Oauth consent screen` step, under the :guilabel:`App information` section,
enter `Odoo` in the :guilabel:`App name` field. Select the organization's email address under the
:guilabel:`User support` email field.
- Next, under :menuselection:`App Domain --> Authorized domains`, click on :guilabel:`Add Domain`
and enter `odoo.com`.
- After that, under the :guilabel:`Developer contact information` section, enter the organization's
email address. Google uses this email address to notify the organization about any changes to
your project.
- Next, click on the :guilabel:`Save and Continue` button.
- Then, skip the :guilabel:`Scopes` page by scrolling to the bottom and clicking on
:guilabel:`Save and Continue`.
- Next, add the email being configured under the :guilabel:`Test users` step by clicking on
:guilabel:`Add Users` and then the :guilabel:`Save and Continue` button. A summary of the
:guilabel:`App registration` appears.
- Finally, scroll to the bottom and click on :guilabel:`Back to Dashboard`.
Next we will configure the app registration of the project.

On the :guilabel:`OAuth consent screen` step, under the :guilabel:`App information` section, enter
`Odoo` in the :guilabel:`App name` field. Select the organization's email address under the
:guilabel:`User support` email field.

Next, under :menuselection:`App Domain --> Authorized domains`, click on :guilabel:`Add Domain` and
enter `odoo.com`.

After that, under the :guilabel:`Developer contact information` section, enter the organization's
email address. Google uses this email address to notify the organization about any changes to your
project.

Next, click on the :guilabel:`Save and Continue` button. Then, skip the :menuselection:`Scopes` page
by scrolling to the bottom and clicking on :guilabel:`Save and Continue`.

If continuing in testing mode (External), add the email addresses being configured under the
:guilabel:`Test users` step, by clicking on :guilabel:`Add Users`, and then the :guilabel:`Save and
Continue` button. A summary of the app registration appears.

Finally, scroll to the bottom and click on :guilabel:`Back to Dashboard` to finish setting up the
project.

Create Credentials
------------------

Now that you have set up the project, you need to create credentials, which includes the
:guilabel:`Client ID` and :guilabel:`Client Secret`. First, click on :guilabel:`Credentials` in the
left sidebar menu.
Now that the project is set up, credentials should be created, which includes the *Client ID* and
*Client Secret*. First, click on :guilabel:`Credentials` in the left sidebar menu.

Then, click on :guilabel:`Create Credentials` in the top menu and select
:guilabel:`OAuth client ID` from the dropdown menu.
Then, click on :guilabel:`Create Credentials` in the top menu and select :guilabel:`OAuth client ID`
from the dropdown menu.

- Under :guilabel:`Application Type`, select :guilabel:`Web Application` from the dropdown menu.
- In the :guilabel:`Client ID` field, enter `Odoo`.
- In the :guilabel:`Name` field, enter `Odoo`.
- Under the :guilabel:`Authorized redirect URIs` label, click the button :guilabel:`ADD URI`, and
then input `https://yourdbname.odoo.com/google_gmail/confirm` in the :guilabel:`URIs 1` field. Be
sure to replace the *yourdbname* part of the URL with your actual Odoo database name.
- Next, click on :guilabel:`Create` to generate an OAuth :guilabel:`Client ID` and
:guilabel:`Client Secret`. Finally, copy each generated value for later use when configuring in
Odoo, and then navigate to the Odoo database.
then input `https://yourdbname.odoo.com/google_gmail/confirm` in the :guilabel:`URIs 1` field.
Be sure to replace the *yourdbname* part of the URL with the actual Odoo database name.
- Next, click on :guilabel:`Create` to generate an OAuth :guilabel:`Client ID` and :guilabel:`Client
Secret`. Finally, copy each generated value for later use when configuring in Odoo, and then
navigate to the Odoo database.

.. image:: google_oauth/client-credentials.png
:align: center
Expand All @@ -91,32 +114,37 @@ Enter Google Credentials
------------------------

First, open Odoo and navigate to the :guilabel:`Apps` module. Then, remove the :guilabel:`Apps`
filter from the search bar and type in `Google`. Install the module called :guilabel:`Google Gmail`.
filter from the search bar and type in `Google`. Install the module called :guilabel:`Google
Gmail`.

Next, navigate to :menuselection:`Settings --> General Settings`, and under the :guilabel:`Discuss`
section, ensure that the checkbox for :guilabel:`Custom Email Servers` is checked. This populates a
new option for :guilabel:`Gmail Credentials`. Then, copy and paste the :guilabel:`Client ID` and
:guilabel:`Client Secret` into the respective fields and :guilabel:`Save` the settings.
section, ensure that the checkbox for :guilabel:`Custom Email Servers` or :guilabel:`External Email
Servers` is checked. This populates a new option for :guilabel:`Gmail Credentials` or :guilabel:`Use
a Gmail Sever`. Then, copy and paste the respective values into the :guilabel:`Client ID` and
:guilabel:`Client Secret` fields and :guilabel:`Save` the settings.

Configure outgoing email server
-------------------------------

After that, on the :guilabel:`General Settings` page, under :guilabel:`Custom Email Servers`, click
:guilabel:`Outgoing Email Servers` to configure the external Gmail account.
To configure the external Gmail account, return to the top of the :guilabel:`Custom Email Servers`
setting and then click the :guilabel:`Outgoing Email Servers` link.

.. image:: google_oauth/outgoing-servers.png
:align: center
:alt: Configure Outgoing Email Servers in Odoo.

Then, :guilabel:`Create` a new email server and select the option for :guilabel:`Gmail`. Next, fill
in the :guilabel:`Description` (can be anything) and the email :guilabel:`Username` and click on
:guilabel:`Connect your Gmail account`.
Then, click on :guilabel:`New` or :guilabel:`Create` to create a new email server, and fill in the
:guilabel:`Name`, :guilabel:`Description`, and the email :guilabel:`Username` (if required).

Next, click on :guilabel:`Gmail OAuth Authentication` or :guilabel:`Gmail` (under the
:guilabel:`Authenticate with` or :guilabel:`Connection` section). Finally, click on
:guilabel:`Connect your Gmail Account`.

A new window from :guilabel:`Google` opens to complete the authorization process. Select the
A new window labeled :guilabel:`Google` opens to complete the authorization process. Select the
appropriate email address that is being configured in Odoo.

If the email address is a personal account, an extra step pops up, click :guilabel:`Continue` to
allow the verification and connect the Gmail account to Odoo.
If the email address is a personal account, then an extra step pops up, so click
:guilabel:`Continue` to allow the verification and connect the Gmail account to Odoo.

Then, allow Odoo to access the Google account by clicking on :guilabel:`Continue` or
:guilabel:`Allow`. After that, the page navigates back to the newly configured outgoing email
Expand All @@ -127,18 +155,17 @@ server in Odoo. The configuration automatically loads the token in Odoo, and a t
:align: center
:alt: Configure Outgoing Email Servers in Odoo.

Finally, save the settings and :guilabel:`Test the Connection`. A confirmation message should
appear. The Odoo database can now send safe, secure emails through Google using OAuth
authentication.
Finally, :guilabel:`Test the Connection`. A confirmation message should appear. The Odoo database
can now send safe, secure emails through Google using OAuth authentication.

Google OAuth FAQ
================

Production VS Testing Publishing Status
---------------------------------------

Choosing :guilabel:`Production` as the :guilabel:`Publishing Status` (instead of Testing) will
display the following warning message:
Choosing :guilabel:`Production` as the :guilabel:`Publishing Status` (instead of
:guilabel:`Testing`) will display the following warning message:

.. image:: google_oauth/published-status.png
:align: center
Expand All @@ -158,39 +185,35 @@ populate.
:align: center
:alt: 403 Access Denied Error.

To correct this error, return to the :guilabel:`OAuth consent screen` under
:guilabel:`APIs & Services` and add test user(s) to the app. Add the email that you are configuring
in Odoo.
To correct this error, return to the :guilabel:`OAuth consent screen` under :guilabel:`APIs &
Services` and add test user(s) to the app. Add the email that you are configuring in Odoo.

Gmail Module not updated
------------------------

If the :guilabel:`Gmail Module` in Odoo has not been updated to the latest version, then a
If the *Google Gmail* module in Odoo has not been updated to the latest version, then a
:guilabel:`Forbidden` error message populates.

.. image:: google_oauth/forbidden-error.png
:align: center
:alt: Forbidden you don't have the permission to access the requested resource.

To correct this error, go to the :guilabel:`Apps` module and clear out the search terms. Then,
search for `Gmail` or `Google` and upgrade the :guilabel:`Google Gmail` module. Finally, click on
the three dots on the upper right of the module and select :guilabel:`Upgrade`.
To correct this error, go to the :menuselection:`Apps` module and clear out the search terms. Then,
search for `Gmail` or `Google` and upgrade the :guilabel:`Google Gmail` module. Finally, click
on the three dots on the upper right of the module and select :guilabel:`Upgrade`.

Application Type
----------------

When creating the :guilabel:`Credentials` (OAuth Client ID and Client Secret), if
:guilabel:`Desktop App` is selected for the :guilabel:`Application Type`, an
:guilabel:`Authorization Error` appears.
When creating the credentials (OAuth *Client ID* and *Client Secret*), if :guilabel:`Desktop App` is
selected for the :guilabel:`Application Type`, an :guilabel:`Authorization Error` appears.

.. image:: google_oauth/error-400.png
:align: center
:alt: Error 400 Redirect URI Mismatch.

To correct this error, delete the credentials already created and create new credentials, selecting
:guilabel:`Web Application` for the :guilabel:`Application Type`. Then, under
:guilabel:`Authorized redirect URIs`, click :guilabel:`ADD URI` and type:
`https://yourdbname.odoo.com/google_gmail/confirm` in the field.

.. note::
Replace *yourdbname* in the URL with the Odoo database name.
:guilabel:`Web Application` for the :guilabel:`Application Type`. Then, under :guilabel:`Authorized
redirect URIs`, click :guilabel:`ADD URI` and type:
`https://yourdbname.odoo.com/google_gmail/confirm` in the field, being sure to replace *yourdbname*
in the URL with the Odoo database name.
Loading