Module OAuth
| OAuth | |
|---|---|
| Numero/ID of module | 66000 |
| User doc. of module | This page |
| Developer doc. of module | |
Introduction
The OAUth module is a technical module that allows you to create and manage OAuth2 connections with an OAuth2 authentication delegation server. Alone this module is useless. But once you have created OAuth2 connections, you can reuse them in some other modules, for example:
- for SMTP email sending
- for the IMAP EMail collector
- for some external modules
- for the Google SSO Login authentication (see Authentication,_SSO_and_SSL#googleoauth)
Installation
This module is included with the Dolibarr distribution, so there is no need to install it.
Setup
Creation of the OAuth entry
This is the first step. You must create an entry and choose the permission the according to the purpose the OAuth entry will be used for. This is some examples of value you can use according to OAuth provider and goal of the entry. Try to create 1 entry for each different purpose.
For SMTP access
This is example of setup if you plan to use the OAuth token to send emails.
For Google
Client ID / Secret ID: See chapter #How to get my Client / Secret ID.
Scope: Choose the scope gmail_full
For Microsoft Office365
Client ID / Secret ID: See chapter #How to get my Client / Secret ID.
Tenant: The ID of the tenant provided by Microsoft. Example: 123456ab-1234-5678-abdc-12345678abcd
Scope: Choose the scope: offline_access + outlook.office365.com/SMTP.Send. Scope email can also be added but seems not mandatory. Don't forget to also allow this permissions in Azure setup
It if fails, choose: outlook.office.com/.default
For IMAP access
This is example of setup if you plan to use the OAuth token to read your email box with the email collector.
For Google
Client ID / Secret ID: See chapter #How to get my Client / Secret ID.
Scope: Choose the scope gmail_full
For Microsoft Office365
Client ID / Secret ID: See chapter #How to get my Client / Secret ID.
Tenant: The ID of the tenant provided by Microsoft. Example: 123456ab-1234-5678-abdc-12345678abcd
Scope: Choose the scope: offline_access + outlook.office365.com/IMAP.AccessAsUser.All. Scope email can also be added but seems not mandatory. Don't forget to also allow this permissions in Azure setup
It if fails, choose: outlook.office.com/.default
For SSO Login
This is example of setup if you plan to use the OAuth provider to login. Note that for this purpose, creating the OAuth entry is enough, no need to generate the token.
For Google
Name of the entry: "Login" (The text "Login" with L uppercase. You must use this entry string for SSO Login. No other name is possible).
Client ID / Secret ID: See chapter #How to get my Client / Secret ID.
Scope: Choose the scope openid and email
You must also modify you Dolibarr conf file to use SSO Login with Google OAuth. See page Authentication,_SSO_and_SSL.
For Microsoft Office365
Not yet available ! Will probably be ...
Client ID / Secret ID: See chapter #How to get my Client / Secret ID.
Tenant: The ID of the tenant provided by Microsoft. Example: 123456ab-1234-5678-abdc-12345678abcd
Scope: Choose the scope openid and email
Other services
For Mastodon read/write
URL for endpoint termination: Should be the root url of the Mastodon server; For example: https://mastodon.social
Client ID / Secret ID: You can get them from your Mastodon profile account.
Scope: Type read,write
Generation of the token
Note: If the goal if the OAuth entry is to be used for SSO Login, you don't need to generate the token.
Once your OAuth entry has been created, you can switch on the second tab to generate and get your OAuth full token (a full token is the access token that expires after a short delay + a refresh token that allows to get a new access token once expired). This full token will then be used by the other modules or features (for example, to send email using SMTP or to read emails using IMAP).
Note about token duration of validity
- For Google, when your oauth entry is published is Testing, Google unverified, the refresh_token expires is 7 days and is limited to 100 access_token refreshes.
- For Google, when your oauth entry is published in Production, Google verified, refresh_token expire is 180 days and has unlimited access_token refreshes.
How to get my Client / Secret ID
To create an OAuth entry, you need a Client and Secret ID (and sometimes a Tenant ID). Getting them depends on your OAUTH provider.
For Microsoft 365
The following steps are:
- Go on https://portal.azure.com - Manage application to create an Application. You can get the value for Client ID in field "ID application (client)" and Tenant ID in field "ID annuary (tenant)"
- Then set property "Assignation required to No (not sure this is necessary)
- Then set Authentification chapter to add the allowed callback URL suggested by Dolibarr.
- Then set Authorized API, for example Microsoft Graph email, IMAP.ACcessAsUser.ALL, Mail.Read, Mail.Send, offline_access, openid, profile, SMTP.Send
- Then set Certificate & Secret (The Secret ID is column "Value", the column "ID of secret" can be ignored)
You can get a summary of all of this in the menu "Overview"
The is some documentation here:
- See https://afterlogic.com/mailbee-net/docs/OAuth2Office365NonInteractive.html and https://learn.microsoft.com/fr-fr/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth
- Tutorial to register an application and create a secret ID: https://learn.microsoft.com/fr-fr/azure/active-directory/develop/quickstart-register-app#register-an-application
- A thread in forum is also available related to use of OAuth2 for SMTP and IMAP: https://www.dolibarr.org/forum/t/oauth-office-365-and-email-collector/23437
For Google
The following steps are:
|
|
Page waiting to complete. To complete, create an account, go back and clic on "Modify".
Page en attente d'être complété. Pour compléter, créez un compte, revenez et cliquez sur "Modifier".
Página a completar. Para completarla, cree una cuenta, vuelva a la página y haga clic en "editar"
Seite wartet auf Vervollständigung. Um zu helfen, erstelle ein Konto, gehe zurück und klicke auf "Bearbeiten".
The is some documentation here: