[FW][ADD] maintain: connect office365 with azure oauth

closes odoo/documentation#3352

X-original-commit: 5b9d1cba2a
Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>
Signed-off-by: Samuel Lieber (sali) <sali@odoo.com>
This commit is contained in:
Sam Lieber (sali) 2023-01-17 15:39:07 +00:00
parent 3690bba092
commit 0f1be083b5
11 changed files with 219 additions and 2 deletions

View File

@ -7,6 +7,7 @@ Maintain
.. toctree::
maintain/domain_names
maintain/azure_oauth
maintain/google_oauth
maintain/mailjet_api
maintain/update

View File

@ -0,0 +1,216 @@
=======================================================
Connect Microsoft Outlook 365 to Odoo using Azure OAuth
=======================================================
Odoo is compatible with Microsoft's Azure OAuth for Microsoft 365. In order to send and receive
secure emails from a custom domain, all that is required is to configure a few settings on the
Azure platform and on the back end of the Odoo database. This configuration works with either a
personal email address or an address created by a custom domain.
.. seealso::
`Microsoft Learn: Register an application with the Microsoft identity platform
<https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app>`_
Setup in Microsoft Azure Portal
===============================
Create a new application
------------------------
To get started, go to `Microsoft's Azure Portal <https://portal.azure.com/>`_. Log in with the
:guilabel:`Microsoft Outlook Office 365` account if there is one, otherwise log in with the
personal :guilabel:`Microsoft account`. A user with administrative access to the Azure Settings
will need to connect and perform the following configuration. Next, navigate to the section
labeled :guilabel:`Manage Azure Active Directory`.
Now, click on :guilabel:`Add (+)`, located in the top menu, and then select :guilabel:`App
registration`. On the :guilabel:`Register an application` screen, rename the :guilabel:`Name` to
`Odoo` or something recognizable. Under the :guilabel:`Supported account types` section select
:guilabel:`Accounts in any organizational directory (Any Azure AD directory - Multitenant) and
personal Microsoft accounts (e.g. Skype, Xbox)`.
Under the :guilabel:`Redirect URL` section, select :guilabel:`Web` as the platform, and then input
`https://<odoo base url>/microsoft_outlook/confirm` in the :guilabel:`URL` field. The Odoo base URL
is the canonical domain at which your Odoo instance can be reached in the URL field.
.. example::
*mydatabase.odoo.com*, where *mydatabase* is the actual prefix of the database's subdomain,
assuming it's hosted on Odoo.com
After the URL has been added to the field, :guilabel:`Register` the application so it is created.
API permissions
---------------
The :guilabel:`API permissions` should be set next. Odoo will need specific API permissions to be
able to read (IMAP) and send (IMAP) emails in the Microsoft 365 setup. First, click the
:guilabel:`API permissions` link, located in the left menu bar. Next, click on the :guilabel:`(+)
Add a Permission` button and select :guilabel:`Microsoft Graph` under :guilabel:`Commonly Used
Microsoft APIs`. After, select the :guilabel:`Delegated Permissions` option.
In the search bar, search for the following :guilabel:`Deregulated permissions` and click
:guilabel:`Add permissions` for each one:
- :guilabel:`SMTP.Send`
- :guilabel:`IMAP.AccessAsUser.All`
.. note::
The :guilabel:`User.Read` permission will be added by default.
.. image:: azure_oauth/permissions.png
:align: center
:alt: API permissions needed for Odoo integration are listed under the Microsoft Graph.
Assign users and groups
=======================
After adding the API permissions, navigate back to the :guilabel:`Overview` of the
:guilabel:`Application` in the top of the left sidebar menu.
Now, add users to this application. Under the :guilabel:`Essentials` overview table, click on the
link labeled :guilabel:`Managed Application in Local Directory`, or the last option on the bottom
right-hand side of the table.
.. image:: azure_oauth/managed-application.png
:align: center
:alt: Add users/groups by clicking the Managed application in local directory link for the
created application.
In the left sidebar menu, select :guilabel:`Users and Groups`. Next, click on :guilabel:`(+) Add
User/Group`. Depending on the account, either a :guilabel:`Group` and a :guilabel:`User` can be
added, or only :guilabel:`Users`. Personal accounts will only allow for :guilabel:`Users` to be
added.
Under :guilabel:`Users` or :guilabel:`Groups`, click on :guilabel:`None Selected` and add the users
or group of users that will be sending emails from the :guilabel:`Microsoft account` in Odoo.
:guilabel:`Add` the users/groups, click :guilabel:`Select`, and then :guilabel:`Assign` them to the
application.
Create credentials
------------------
Now that the Microsoft Azure app is set up, credentials need to be created for the Odoo setup.
These include the :guilabel:`Client ID` and :guilabel:`Client Secret`. To start, the
:guilabel:`Client ID` can be copied from the :guilabel:`Overview` page of the app. The
:guilabel:`Client ID` or :guilabel:`Application ID` is located under the :guilabel:`Display Name`
in the :guilabel:`Essentials` overview of the app.
.. image:: azure_oauth/application-id.png
:align: center
:alt: Application/Client ID located in the Overview of the app.
Next, the :guilabel:`Client Secret Value` needs to be retrieved. To get this value, click on
:guilabel:`Certificates & Secrets` in the left sidebar menu. Then, a :guilabel:`Client Secret`
needs to be produced. In order to do this, click on the :guilabel:`(+) New Client Secret` button.
A window on the right will populate with a button labeled :guilabel:`Add a client secret`. Under
:guilabel:`Description`, type in `Odoo Fetchmail` or something recognizable, and then set the
:guilabel:`expiration date`.
.. important::
A new :guilabel:`Client Secret` will need to be produced and configured if the first one
expires. In this event, there could be an interruption of service, so the expiration date should
be noted and set to the furthest possible date.
Next, click on :guilabel:`Add` when these two values are entered. A :guilabel:`Client Secret Value`
and :guilabel:`Secret ID` will be created. It is important to copy the :guilabel:`Value` or
:guilabel:`Client Secret Value` into a notepad as it will become encrypted after leaving this page.
The :guilabel:`Secret ID` is not needed.
.. image:: azure_oauth/secretvalue.png
:align: center
:alt: Client Secret Value or Value in the app's credentials.
After these steps, the following items should be ready to be set up in Odoo:
- A client ID (:guilabel:`Client ID` or :guilabel:`Application ID`)
- A client secret (:guilabel:`Value` or :guilabel:`Client Secret Value`)
This completes the setup on the :guilabel:`Microsoft Azure Portal` side.
Setup in Odoo
=============
Enter Microsoft Outlook credentials
-----------------------------------
First, open the Odoo database and navigate to the :guilabel:`Apps` module. Then, remove the
:guilabel:`Apps` filter from the search bar and type in `Outlook`. After that, install the module
called :guilabel:`Microsoft Outlook`.
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:`Outlook Credentials`.
:guilabel:`Save` the progress.
Then, copy and paste the :guilabel:`Client ID` (Application ID) and :guilabel:`Client Secret
(Client Secret Value)` into the respective fields and :guilabel:`Save` the settings.
.. image:: azure_oauth/outlookcreds.png
:align: center
:alt: Outlook Credentials in Odoo General Settings.
Configure outgoing email server
-------------------------------
On the :guilabel:`General Settings` page, under the :guilabel:`Custom Email Servers` setting,
click the :guilabel:`Outgoing Email Servers` link to configure the Microsoft account.
Then, create a new email server and check the box for :guilabel:`Outlook`. Next, fill in the
:guilabel:`Name` (it can be anything) and the Microsoft Outlook email :guilabel:`Username`.
If the :guilabel:`From Filter` field is empty, enter either a :ref:`domain or email address
<email_communication/default_from>`.
Then, cick on :guilabel:`Connect your Outlook account`.
A new window from Microsoft opens to complete the :guilabel:`authorization process`. Select the
appropriate email address that is being configured in Odoo.
.. image:: azure_oauth/verify-outlook.png
:align: center
:alt: Permission page to grant access between newly created app and Odoo.
Then, allow Odoo to access the Microsoft account by clicking on :guilabel:`Yes`. After this, the
page will navigate back to the newly configured :guilabel:`Outgoing Mail Server` in Odoo. The
configuration automatically loads the :guilabel:`token` in Odoo, and a tag stating
:guilabel:`Outlook Token Valid` appears in green.
.. image:: azure_oauth/outlook-token.png
:align: center
:alt: Valid Outlook Token indicator.
Finally, click :guilabel:`Test Connection`. A confirmation message should appear. The Odoo database
can now send safe, secure emails through Microsoft Outlook using OAuth authentication.
Multiple user configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each user should have a separate server set up. The :guilabel:`from-filter` should be set so that
only the user's email is sent from that server. In other words, only a user with an email address
that matches the set :guilabel:`from-filter` is able to use this server.
After setting the :guilabel:`from-filter`, set up a fallback email account to allow for the sending
of :guilabel:`notifications`. The fallback email must be configured as a :guilabel:`general
transactional server`. The :guilabel:`mail.default.from` system parameter must be set to the
:guilabel:`username` of the general transactional server account. For more information see
:ref:`Use a default email address <email_communication/default>`.
.. note::
The :guilabel:`System Parameters` can be accessed by activating
:doc:`../../applications/general/developer_mode` in the :menuselection:`Settings --> Technical
--> Parameters --> System Parameters` menu.
Configure incoming email server
-------------------------------
The incoming account should be configured in a similar way to the outgoing email account. Navigate
to the :guilabel:`Incoming Mail Servers` in the :guilabel:`Technical Menu` and :guilabel:`Create` a
new configuration. Check or Select the button next to :guilabel:`Outlook Oauth Authentication` and
enter the :guilabel:`Microsoft Outlook username`. Click on :guilabel:`Connect your Outlook
account`. Odoo will state: :guilabel:`Outlook Token Valid` Now :guilabel:`Test and Confirm` the
account. The account should be ready to receive email to the Odoo database.
.. seealso::
:doc:`../../applications/general/email_communication/email_servers`

Binary file not shown.

After

Width:  |  Height:  |  Size: 54 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 47 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 23 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 64 KiB

View File

@ -208,7 +208,7 @@ Connection`.
`yourdomain.com`. Replace `yourdomain` with the custom domain for the Odoo database. If there
isn't one, then use the :guilabel:`mail.catchall.domain` system parameter.
For more information see :ref:`Using a default email address <email_domain/default>`.
For more information see :ref:`Using a default email address <email_communication/default>`.
The :guilabel:`System Parameters` can be accessed by activating
:doc:`../../applications/general/developer_mode` in the :menuselection:`Settings --> Technical

View File

@ -167,7 +167,7 @@ To fully test the configuration, use the `Mail-Tester <https://www.mail-tester.c
gives a full overview of the content and configuration in one sent email. Mail-Tester can also be
used for other, lesser-known providers.
.. _email_domain/default:
.. _email_communication/default:
Use a default email address
===========================