Difference between revisions of "Authentication, SSO and SSL"

From Dolibarr ERP CRM Wiki
Jump to navigation Jump to search
Visual
Tag: 2017 source edit
Tag: 2017 source edit
 
(45 intermediate revisions by 2 users not shown)
Line 9: Line 9:
 
*ldap
 
*ldap
 
*forceuser
 
*forceuser
−
*...
+
*googleoauth (for Google OAuth 2 authentication, Dolibarr 18+)...
  
 
You can combine several methods (some combinations are however technically not compatible). If you use several method (separated by a coma), you will try to authenticate using the first method and if it fails, the next method will be used. For example, if you set  
 
You can combine several methods (some combinations are however technically not compatible). If you use several method (separated by a coma), you will try to authenticate using the first method and if it fails, the next method will be used. For example, if you set  
Line 22: Line 22:
 
=Description of available authentication modes=
 
=Description of available authentication modes=
  
−
==dolibarr==
+
==Mode dolibarr==
−
With this method, the login and pass you entered on login page will be compared to the login and the hashed password saved into the Dolibarr database (Table llx_user).
+
With this method, the login and pass you entered on login page will be compared to the login and the hashed password saved into the Dolibarr database ([[Table llx_user]]).
  
−
==http==
+
==Mode http==
 
You can set the authentication mode to "http" if your Dolibarr web application is protected by an Apache http basic authentication form. The login/pass are stored into the file used by the HTTP Basic system to store passwords (it is often a file called '''.htpasswd''' if you used the '''mod_auth_basic''' + '''mod_authn_file''' plugin of Apache).
 
You can set the authentication mode to "http" if your Dolibarr web application is protected by an Apache http basic authentication form. The login/pass are stored into the file used by the HTTP Basic system to store passwords (it is often a file called '''.htpasswd''' if you used the '''mod_auth_basic''' + '''mod_authn_file''' plugin of Apache).
  
Line 34: Line 34:
 
Note that the user must also exists as a existing user into the Dolibarr user database. Also the date of validity of this user must be valid.
 
Note that the user must also exists as a existing user into the Dolibarr user database. Also the date of validity of this user must be valid.
  
−
==ldap==
+
==Mode ldap==
 
If you set the authentication mode to LDAP, the test of the validity of your login and password are done using a LDAP database.
 
If you set the authentication mode to LDAP, the test of the validity of your login and password are done using a LDAP database.
  
Line 44: Line 44:
 
<br />
 
<br />
  
−
==forceuser==
+
==Mode forceuser==
−
When this method is used, there is no need to enter a login or password. No login page is show. The user will be automatically set to the one defined into the variable '''$dolibarr_auto_user''' saved into  '''htdocs/conf/conf.php'''
+
When this method is used, there is no need to enter a login or password. No login page is shown. The user will be automatically set to the one defined into the variable '''$dolibarr_auto_user''' saved into  '''htdocs/conf/conf.php'''
  
 
This mode is used only on development platforms. For example on an instance used to make demo or automated tests.
 
This mode is used only on development platforms. For example on an instance used to make demo or automated tests.
  
 
Note that the user must also exists as a existing user into the Dolibarr user database. Also the date of validity of this user must be valid.
 
Note that the user must also exists as a existing user into the Dolibarr user database. Also the date of validity of this user must be valid.
 +
 +
==Mode googleoauth==
 +
This code is to use the Google OAuth 2 authentication. It is available with version 18+.
 +
 +
*First enable the [[Module OAuth]] on Dolibarr.
 +
*Into the setup of the module, you must create an OAuth entry for provider Google and label "'''Login'''" (no other label will works). You will find a value for a '''Redirect URI''' that you must use in the next step.
 +
*Go on Google console https://console.cloud.google.com/ - Menu API and services - Credentials, and create an '''OAuth ID client'''. You must use the URL found at previous step as '''Authorized redirect URIs'''.
 +
*Go back to the Dolibarr OAuth setup page to enter the '''client ID''' and '''secret ID''' of the OAuth entry you have created. Choose the scope/permissions "'''openid'''" and "'''email'''".
 +
*Edit the file conf/conf.php and set $dolibarr_main_authentication to "googleoauth" or "dolibarr,googleoauth" to allow both authentication with Dolibarr login/pass and with Google OAuth2
 +
 +
Now try to login. You must enter your Google account and you will be able to login without password if and only if a user exists into the Dolibarr database with the same email address than the one used to login to Google.
 +
 +
==Mode openid==
 +
The method "openid" is an old method for using openID.
 +
Try to use instead the next method "openid_connect"
 +
 +
==Mode openid_connect==
 +
 +
===OpenID Connect using the native method===
 +
This is a new method available with Dolibarr v18 to connect using OpenID Connect.
 +
 +
 +
====In the Dolibarr conf file====
 +
 +
#Configure the authentication methods in <code>conf.php</code> (<code>/var/www/html/conf/conf.php</code>) and add <code>openid_connect</code>. For e.g.:
 +
 +
<code>$dolibarr_main_authentication='openid_connect,dolibarr'</code>
 +
 +
 +
==== Dolibarr application setup ====
 +
 +
Then you must set parameters and options of your openid connect service. From v21, you can enable the module OpenIDConnect to edit them. From v18 to v20, you must edit them from menu '''Home - Setup - Other'''.
 +
 +
{| class="wikitable"
 +
!Name
 +
!Example
 +
!Comment
 +
!Description
 +
|-
 +
|<code>MAIN_AUTHENTICATION_OIDC_CLIENT_ID</code>
 +
|<code>My-Super-Awesome-Client-ID-1234</code>
 +
|OpenID Connect Client ID
 +
|Application client ID
 +
|-
 +
|<code>MAIN_AUTHENTICATION_OIDC_CLIENT_SECRET</code>
 +
|<code>My-Very-Hidden-Client-Secret-1234</code>
 +
|OpenID Connect Client Secret
 +
|Application client secret
 +
|-
 +
|<code>MAIN_AUTHENTICATION_OIDC_AUTHORIZE_URL</code>
 +
|<code><nowiki>https://tenant.us.auth0.com/oauth/authorize</nowiki></code>
 +
|OpenID Authorize URL
 +
|<code>/authorize</code> endpoint
 +
|-
 +
|<code>MAIN_AUTHENTICATION_OIDC_TOKEN_URL</code>
 +
|<code><nowiki>https://tenant.us.auth0.com/oauth/token</nowiki></code>
 +
|OpenID Connect token URL
 +
|<code>/token</code> endpoint
 +
|-
 +
|<code>MAIN_AUTHENTICATION_OIDC_USERINFO_URL</code>
 +
|<code><nowiki>https://tenant.us.auth0.com/userinfo</nowiki></code>
 +
|OpenID Connect userinfo URL
 +
|<code>/userinfo</code> endpoint
 +
|-
 +
|<code>MAIN_AUTHENTICATION_OIDC_REDIRECT_URL</code>
 +
|<code><nowiki>https://dolibarr.domain.com/?openid_mode=true</nowiki></code>
 +
|OpenID Connect redirect URL
 +
|Dolibarr URL followed by <code>/?openid_mode=true</code>
 +
|-
 +
|<code>MAIN_AUTHENTICATION_OIDC_LOGIN_CLAIM</code>
 +
|<code>email</code>
 +
|OpenID Connect login claim
 +
|OpenID Connect claim matching the Dolibarr user login. If not set or empty, defaults to <code>email</code>
 +
|-
 +
|<code>MAIN_LOGOUT_GOTO_URL</code>
 +
|See later
 +
|Identity Provider logout URL
 +
|Composed IdP logout URL
 +
|}
 +
 +
 +
Source page https://github.com/Dolibarr/dolibarr/issues/22740.
 +
 +
====Composing <code>MAIN_AUTHENTICATION_OPENID_URL</code>====
 +
 +
The MAIN_AUTHENTICATION_OPENID_URL will be generated (but if you prefer, you can set it manually from Home - Setup - Other) to
 +
 +
<pre>
 +
MAIN_AUTHENTICATION_OIDC_AUTHORIZE_URL?client_id=MAIN_AUTHENTICATION_OIDC_CLIENT_ID&redirect_uri=mydolibarr/core/modules/openid_connect/callback.php&scope=MAIN_AUTHENTICATION_OIDC_SCOPES&response_type=code
 +
</pre>
 +
 +
This is the main OpenID Connect authentication URL, which allows the user to log in and then be redirected back to Dolibarr. It makes use of some already existing OpenID 2.0 features.
 +
 +
#Retrieve the <code>/authorize</code> endpoint of your OpenID server. The value depends on the used Identity Provider.  E.g.: <code><nowiki>https://tenant.us.auth0.com/authorize</nowiki></code>
 +
#Build the URL parameters:
 +
 +
<br />
 +
{| class="wikitable"
 +
!Param name
 +
!Description
 +
!Example
 +
|-
 +
|client_id
 +
|Application client ID
 +
|<code>My-Super-Awesome-Client-ID-1234</code>
 +
|-
 +
|redirect_uri
 +
|Dolibarr URL followed by <code>/?openid_mode=true</code>, then URL encoded. Must be authorized as callback URL
 +
|Before URL encoding: <code><nowiki>https://dolibarr.domain.com/?openid_mode=true</nowiki></code> - After URL encoding: <code>https%3A%2F%2Fdolibarr.domain.com%2F%3Fopenid_mode%3Dtrue</code>
 +
|-
 +
|scope
 +
|OpenID scope of required user info
 +
|<code>openid profile email</code>
 +
|-
 +
|response_type
 +
|OAuth flow name, here we use <code>code</code> for the Authorization Code flow
 +
|<code>code</code>
 +
|-
 +
|state
 +
|A number
 +
|1234568
 +
|}
 
<br />
 
<br />
  
−
==googleauth==
+
The final MAIN_AUTHENTICATION_OPENID_URL content should be like:  <code><nowiki>https://tenant.us.auth0.com/authorize?client_id=My-Super-Awesome-Client-ID-1234&redirect_uri=https%3A%2F%2Fdolibarr.domain.com%2F%3Fopenid_mode%3Dtrue&scope=openid</nowiki> profile email&response_type=code&state=anumber</code>
−
This method is still in development and is not yet available
+
 
 
<br />
 
<br />
  
−
==openid==
+
==== Composing <code>MAIN_LOGOUT_GOTO_URL</code> ====
−
This method is not yet available and still in development.
 
  
 +
# Retrieve the <code>/logout</code> endpoint. The value depends on the used Identity Provider.  E.g.: <code><nowiki>https://tenant.us.auth0.com/v2/logout</nowiki></code>Build the URL parameters
 +
# Build the URL parameters
  
−
However, if you need to connect using OpenID, you can already do it using the following solution:
+
{| class="wikitable"
 +
!Param name
 +
!Description
 +
!Example
 +
|-
 +
|client_id
 +
|Application client ID
 +
|<code>My-Super-Awesome-Client-ID-1234</code>
 +
|-
 +
|returnTo
 +
|URL to be redirected to after logout. Use Dolibarr URL. Must be authorized as logout URL
 +
|<code><nowiki>https://dolibar.domain.com</nowiki></code>
 +
|}
 +
 
 +
# The final MAIN_LOGOUT_GOTO_URL content should be like:  <code><nowiki>https://tenant.us.auth0.com/v2/logout?client_id=My-Super-Awesome-Client-ID-1234&returnTo=https://dolibar.domain.com</nowiki></code>
 +
 
 +
<br />
 +
 
 +
===OpenID Connect using OpenID and the HTTP Basic of Apache===
 +
If you need to connect using OpenID Connect without using the native method (for example for Dolibarr < 18), you can also do it using the following solution:
  
−
===Connect to dolibarr using Openid and the HTTP Basic of Apache===
 
 
The idea is to use two elements:
 
The idea is to use two elements:
  
Line 88: Line 229:
  
 
     <Directory /home/.../htdocs>
 
     <Directory /home/.../htdocs>
−
    # Docroot
+
        # Docroot
−
    AuthType openid-connect
+
        AuthType openid-connect
−
    Require valid-user
+
        Require valid-user
−
    Require env no-auth
+
        Require env no-auth
 
     </Directory>
 
     </Directory>
  
Line 122: Line 263:
 
         Satisfy any
 
         Satisfy any
 
     </Files>
 
     </Files>
 +
 +
 +
    # And to support/manage the disconnetion
 +
    RewriteEngine on
 +
    RewriteCond %{REQUEST_URI} /user/logout.php
 +
    RewriteRule ^ /sso_redirect?logout= [R,L]
 +
 
</syntaxhighlight>
 
</syntaxhighlight>
  

Latest revision as of 15:50, 6 March 2025


Authentication setup in Dolibarr

There is different solutions to be authenticated with Dolibarr. You can set the selected authentication method into the file htdocs/conf/conf.php in the parameter $dolibarr_authentication_mode. This is a list of available values:

  • dolibarr
  • http
  • ldap
  • forceuser
  • googleoauth (for Google OAuth 2 authentication, Dolibarr 18+)...

You can combine several methods (some combinations are however technically not compatible). If you use several method (separated by a coma), you will try to authenticate using the first method and if it fails, the next method will be used. For example, if you set 

$dolibarr_authentication_mode="ldap,dolibarr"

the system will try to authenticate using the LDAP database and if it fails it will try to login using the internal Dolibarr login/password

Each authentication mode may have complementary parameters (also into htdocs/conf/conf.php file) to have them working. Let's have a look at each available method:

Description of available authentication modes

Mode dolibarr

With this method, the login and pass you entered on login page will be compared to the login and the hashed password saved into the Dolibarr database (Table llx_user).

Mode http

You can set the authentication mode to "http" if your Dolibarr web application is protected by an Apache http basic authentication form. The login/pass are stored into the file used by the HTTP Basic system to store passwords (it is often a file called .htpasswd if you used the mod_auth_basic + mod_authn_file plugin of Apache).

This is an exemple of setup for Apache to protect your instance to be accessed using the HTTP Basic authentication (uncomment the section under line "# To restrict access by a HTTP basic auth" in this example)

https://github.com/Dolibarr/dolibarr/blob/develop/dev/setup/apache/virtualhost

Note that the user must also exists as a existing user into the Dolibarr user database. Also the date of validity of this user must be valid.

Mode ldap

If you set the authentication mode to LDAP, the test of the validity of your login and password are done using a LDAP database.

The parameters to define where is your LDAP must be defined into the variable $dolibarr_main_auth_ldap_... (Fo security purpose, the parameters defined into the LDAP module of Dolibarr are used only by the pages of the application that need LDAP access, but for the authentication, only variables defined into the conf/conf.php file are used)

See the file https://github.com/Dolibarr/dolibarr/blob/develop/htdocs/conf/conf.php.example for the list of $dolibarr_main_auth_ldap_... variables.

Note that the user must also exists as an existing user into the Dolibarr user database. Also the date of validity of this user must be valid.

Mode forceuser

When this method is used, there is no need to enter a login or password. No login page is shown. The user will be automatically set to the one defined into the variable $dolibarr_auto_user saved into htdocs/conf/conf.php

This mode is used only on development platforms. For example on an instance used to make demo or automated tests.

Note that the user must also exists as a existing user into the Dolibarr user database. Also the date of validity of this user must be valid.

Mode googleoauth

This code is to use the Google OAuth 2 authentication. It is available with version 18+.

  • First enable the Module OAuth on Dolibarr.
  • Into the setup of the module, you must create an OAuth entry for provider Google and label "Login" (no other label will works). You will find a value for a Redirect URI that you must use in the next step.
  • Go on Google console https://console.cloud.google.com/ - Menu API and services - Credentials, and create an OAuth ID client. You must use the URL found at previous step as Authorized redirect URIs.
  • Go back to the Dolibarr OAuth setup page to enter the client ID and secret ID of the OAuth entry you have created. Choose the scope/permissions "openid" and "email".
  • Edit the file conf/conf.php and set $dolibarr_main_authentication to "googleoauth" or "dolibarr,googleoauth" to allow both authentication with Dolibarr login/pass and with Google OAuth2

Now try to login. You must enter your Google account and you will be able to login without password if and only if a user exists into the Dolibarr database with the same email address than the one used to login to Google.

Mode openid

The method "openid" is an old method for using openID. Try to use instead the next method "openid_connect"

Mode openid_connect

OpenID Connect using the native method

This is a new method available with Dolibarr v18 to connect using OpenID Connect.


In the Dolibarr conf file
  1. Configure the authentication methods in conf.php (/var/www/html/conf/conf.php) and add openid_connect. For e.g.:

$dolibarr_main_authentication='openid_connect,dolibarr'


Dolibarr application setup

Then you must set parameters and options of your openid connect service. From v21, you can enable the module OpenIDConnect to edit them. From v18 to v20, you must edit them from menu Home - Setup - Other.

Name Example Comment Description
MAIN_AUTHENTICATION_OIDC_CLIENT_ID My-Super-Awesome-Client-ID-1234 OpenID Connect Client ID Application client ID
MAIN_AUTHENTICATION_OIDC_CLIENT_SECRET My-Very-Hidden-Client-Secret-1234 OpenID Connect Client Secret Application client secret
MAIN_AUTHENTICATION_OIDC_AUTHORIZE_URL https://tenant.us.auth0.com/oauth/authorize OpenID Authorize URL /authorize endpoint
MAIN_AUTHENTICATION_OIDC_TOKEN_URL https://tenant.us.auth0.com/oauth/token OpenID Connect token URL /token endpoint
MAIN_AUTHENTICATION_OIDC_USERINFO_URL https://tenant.us.auth0.com/userinfo OpenID Connect userinfo URL /userinfo endpoint
MAIN_AUTHENTICATION_OIDC_REDIRECT_URL https://dolibarr.domain.com/?openid_mode=true OpenID Connect redirect URL Dolibarr URL followed by /?openid_mode=true
MAIN_AUTHENTICATION_OIDC_LOGIN_CLAIM email OpenID Connect login claim OpenID Connect claim matching the Dolibarr user login. If not set or empty, defaults to email
MAIN_LOGOUT_GOTO_URL See later Identity Provider logout URL Composed IdP logout URL


Source page https://github.com/Dolibarr/dolibarr/issues/22740.

Composing MAIN_AUTHENTICATION_OPENID_URL

The MAIN_AUTHENTICATION_OPENID_URL will be generated (but if you prefer, you can set it manually from Home - Setup - Other) to 

MAIN_AUTHENTICATION_OIDC_AUTHORIZE_URL?client_id=MAIN_AUTHENTICATION_OIDC_CLIENT_ID&redirect_uri=mydolibarr/core/modules/openid_connect/callback.php&scope=MAIN_AUTHENTICATION_OIDC_SCOPES&response_type=code

This is the main OpenID Connect authentication URL, which allows the user to log in and then be redirected back to Dolibarr. It makes use of some already existing OpenID 2.0 features.

  1. Retrieve the /authorize endpoint of your OpenID server. The value depends on the used Identity Provider. E.g.: https://tenant.us.auth0.com/authorize
  2. Build the URL parameters:


Param name Description Example
client_id Application client ID My-Super-Awesome-Client-ID-1234
redirect_uri Dolibarr URL followed by /?openid_mode=true, then URL encoded. Must be authorized as callback URL Before URL encoding: https://dolibarr.domain.com/?openid_mode=true - After URL encoding: https%3A%2F%2Fdolibarr.domain.com%2F%3Fopenid_mode%3Dtrue
scope OpenID scope of required user info openid profile email
response_type OAuth flow name, here we use code for the Authorization Code flow code
state A number 1234568


The final MAIN_AUTHENTICATION_OPENID_URL content should be like: https://tenant.us.auth0.com/authorize?client_id=My-Super-Awesome-Client-ID-1234&redirect_uri=https%3A%2F%2Fdolibarr.domain.com%2F%3Fopenid_mode%3Dtrue&scope=openid profile email&response_type=code&state=anumber


Composing MAIN_LOGOUT_GOTO_URL
  1. Retrieve the /logout endpoint. The value depends on the used Identity Provider. E.g.: https://tenant.us.auth0.com/v2/logoutBuild the URL parameters
  2. Build the URL parameters
Param name Description Example
client_id Application client ID My-Super-Awesome-Client-ID-1234
returnTo URL to be redirected to after logout. Use Dolibarr URL. Must be authorized as logout URL https://dolibar.domain.com
  1. The final MAIN_LOGOUT_GOTO_URL content should be like: https://tenant.us.auth0.com/v2/logout?client_id=My-Super-Awesome-Client-ID-1234&returnTo=https://dolibar.domain.com


OpenID Connect using OpenID and the HTTP Basic of Apache

If you need to connect using OpenID Connect without using the native method (for example for Dolibarr < 18), you can also do it using the following solution:

The idea is to use two elements:

  • The auth_openidc plugin for Apache
  • Dolibarr HTTP authentication.

The procedure will therefore require Dolibarr installed with Apache and the apache module https://github.com/zmartzone/mod_auth_openidc. The latter is often directly available on Linux via a package manager command.

The second part will therefore be to configure this apache module in order to authenticate users with the OpenID Connect protocol. In the general case, you will only need the metadata URL. Here is an example apache configuration for OpenID with AzureAD: 

    ...

    OIDCProviderMetadataURL https://login.microsoftonline.com/your-tenant-id/v2.0/.well-known/openid-configuration
    OIDCClientID youropenidclient
    OIDCClientSecret yoursecret
    OIDCCryptoPassphrase randomstring
    OIDCRedirectURI https://mydolibarr.example.com/sso_redirect
    OIDCScope "openid email profile"
    OIDCRemoteUserClaim email ^(.*)@

    # Disable openid-connect if using DoliDroid
    SetEnvIf User-Agent DoliDroid no-auth

    <Directory /home/.../htdocs>
        # Docroot
        AuthType openid-connect
        Require valid-user
        Require env no-auth
    </Directory>

    # Disallow openid-connect on some public pages or services
    # Leaving /public and /api, /dav, .well_known but also wrappers for document, viewimage and public json/img accessible to everyone
    <Directory /home/admin/wwwroot/dolibarr/htdocs/public/>
        AuthType None
        Satisfy any
        Require all granted
    </Directory>
    <Directory /home/admin/wwwroot/dolibarr/htdocs/api/>
        AuthType None
        Satisfy any
        Require all granted
    </Directory>
    <Directory /home/admin/wwwroot/dolibarr/htdocs/dav/>
        AuthType None
        Satisfy any
        Require all granted
    </Directory>
    <Directory /home/admin/wwwroot/dolibarr/htdocs/.well-known/>
        AuthType None
        Satisfy any
        Require all granted
    </Directory>

    <Files ~ "(document\.php|viewimage\.php|\.js\.php|\.json\.php|\.js|\.css\.php|\.css|\.gif|\.png|\.svg|\.woff2|favicon\.ico)$"> 
        AuthType None 
        Require all granted 
        Satisfy any
    </Files>


    # And to support/manage the disconnetion
    RewriteEngine on
    RewriteCond %{REQUEST_URI} /user/logout.php
    RewriteRule ^ /sso_redirect?logout= [R,L]


In the example above, the information to enter in OIDCProviderMetadataURL, OIDCClientID and OIDCClientSecret is provided by your OpenID Connect provider.

The OIDCRemoteUserClaim variable defines which "claim" will be used for the username. In our configuration example, we consider that the username that will be used in Dolibarr is what precedes the at sign in the email address.

After this manipulation, you should be prompted to log in to your OpenID Connect account to access your Dolibarr installation. However, it remains to indicate to Dolibarr that it must use the username defined by Apache. It is in the conf/conf.php file that we will perform this manipulation. Add the following line at the end of the file: 

$dolibarr_main_authentication='http';

Your OpenID Connect authentication is now fully functional! Be careful however, there may be adjustments to make for this configuration to work with certain modules.

For example, the use of WebDav in Dolibarr (pages /dav/*) is not compatible with this configuration, or access to public pages (pages /public/*) or access to APIs (pages /api/*), will be blocked by the authentication request put in place. To avoid this, you must also exclude the paths which should not be protected by the Apache authentication for OpenID which defines the protected Directory. Here is an example configuration file of your apache virtual host to be able to use "http" authentication without blocking access to public pages (retrieve the exclusion under the line "# Leaving /public and /api, /dav, .well_known..." in this example):

https://github.com/Dolibarr/dolibarr/blob/develop/dev/setup/apache/virtualhost

By further adapting this configuration, it is also possible to use Active Directory authentication and other authentication services.

Retrieved from "https://wiki.dolibarr.org/index.php?title=Authentication,_SSO_and_SSL&oldid=62700"