Cette traduction est en retard : la version française a été modifiée depuis. Voir la version française

OAuth2/OIDC server

SmartAuth integrates an OpenID Connect compatible OAuth2 server. It allows using Dolibarr as a central identity provider (Identity Provider) for Single Sign-On (SSO) with third-party applications.

Activation

  1. Go to Home > Setup > Modules > SmartAuth
  2. Open the OAuth server tab
  3. Check Enable the OAuth/OIDC server
  4. Click Save

OAuth2/OIDC server configuration page in SmartAuth

Server settings

Issuer URL

The issuer URL identifies your OAuth server. If you leave this field empty, SmartAuth uses the auto-detected URL of your Dolibarr installation.

Token durations

Parameter Description Default value
Access token duration Validity period of an OAuth access token, in seconds 3600 (1 hour)
Refresh token duration Validity period of an OAuth refresh token, in seconds 2592000 (30 days)
Authorization code duration Validity period of an authorization code, in seconds 600 (10 minutes)

Security

Parameter Description
PKCE required for public clients Recommended for mobile applications and Single Page Applications (SPA). Enabled by default.
Remember consents Avoids asking for consent again at each login for the same user and the same client.

OIDC endpoints

When the OAuth server is enabled, the following endpoints are available:

Endpoint URL
Discovery /.well-known/openid-configuration
JWKS /.well-known/jwks.json
Authorization /oauth/authorize
Token /oauth/token
Userinfo /oauth/userinfo
Revocation /oauth/revoke
End Session /oauth/logout

These URLs are displayed directly in the OAuth server configuration tab after activation.

Internal API: authorizing a client

The routes that the instance's modules expose in oauth2 (the internal API, called first-party) are closed by default. Without this, any OAuth client of the instance could call any route of any module with the rights of its service user.

An OAuth client's record therefore displays its status and carries the two corresponding buttons:

Status What it means
Authorized The client can call the oauth2 routes of the instance's modules
Not authorized The client does get a token, but each call returns 401

This is the symptom to know: the credentials are good, the token is issued, the route is found, and the call is still refused. The Dolibarr log names it: SMARTAUTH_API_AUDIENCE not set - refusing <client_id>.

The buttons write the SMARTAUTH_API_AUDIENCE constant, which is a list: authorizing a client does not affect the others, and removing one doesn't either. Removal asks for a confirmation, the calls of the product concerned stopping immediately.

Public SSO portal

SmartAuth provides a public web portal (htdocs/custom/smartauth/public/) meant to be exposed on a dedicated subdomain (for example https://auth.example.com). This portal serves:

URL Role
/ Brand homepage with 3 cards (Log in, Create an account, My account)
/login Login form (used by the OAuth2 flows and in direct access)
/register Registration form (if enabled): email address and name, no password
/register/confirm Link received by email: the person chooses their password, which activates the account
/account User account management page (post-login)
/forgot-password Password reset request form
/reset-password New password form (link received by email)
/oauth/* OAuth2 endpoints (authorize, token, userinfo, revoke, logout)
/.well-known/* OIDC discovery + JWKS

All visuals (CSS, logo, fonts) are loaded same-origin from /assets/.

Apache vhost configuration

Create a dedicated vhost pointing to htdocs/custom/smartauth/public/ as DocumentRoot. Minimal example:

<VirtualHost *:443>
    ServerName auth.example.com
    DocumentRoot /var/www/dolibarr/htdocs/custom/smartauth/public

    SSLEngine on
    SSLCertificateFile      /etc/letsencrypt/live/auth.example.com/fullchain.pem
    SSLCertificateKeyFile   /etc/letsencrypt/live/auth.example.com/privkey.pem

    <Directory /var/www/dolibarr/htdocs/custom/smartauth/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    # RFC 8615 reserves /.well-known/ for service discovery (OIDC, ACME...).
    # The default Apache config on Debian/Ubuntu globally forbids
    # paths starting with a dot ; this exception is mandatory
    # for the OIDC discovery endpoints to be accessible.
    <LocationMatch "^/\\.well-known/">
        Require all granted
    </LocationMatch>

    ErrorLog  ${APACHE_LOG_DIR}/auth.example.com-error.log
    CustomLog ${APACHE_LOG_DIR}/auth.example.com-access.log combined
</VirtualHost>

Validate the configuration and reload Apache:

sudo apache2ctl configtest
sudo systemctl reload apache2

Key point: AllowOverride All is required so that the .htaccess provided by the module (public/.htaccess) is taken into account (rewrites to index.php, security headers, MIME types of assets).

Fixing "Forbidden" on /.well-known/

If the request https://auth.example.com/.well-known/openid-configuration returns 403 Forbidden, it is because the global Apache rule <DirectoryMatch "(^|/)\\."> (common on Debian/Ubuntu) blocks the path before the module's .htaccess even runs. The <LocationMatch> indicated above fixes the problem by explicitly allowing /.well-known/.

Diagnosis on the server:

# Find the rule that blocks
sudo grep -rni "well-known\\|directorymatch" /etc/apache2/ | head

# Confirm in the error log
sudo tail -30 /var/log/apache2/error.log | grep -i "denied\\|forbid\\|well-known"

Test after applying the fix:

curl -i https://auth.example.com/.well-known/openid-configuration

It must return HTTP/1.1 200 and a JSON body containing "issuer", "authorization_endpoint", etc.

SMARTAUTH_APP_URL constant

The link sent by email to reset a password defaults to DOL_MAIN_URL_ROOT (the main URL of Dolibarr). For this link to land on the SSO portal and not on the Dolibarr admin, define the SMARTAUTH_APP_URL constant:

  1. Go to Home > Setup > Other
  2. Add/modify the SMARTAUTH_APP_URL constant with the root URL of the portal as its value (example: https://auth.example.com)
  3. Save

The reset email will then contain a https://auth.example.com/reset-password?token=...&email=... link that opens the form directly on the SSO portal.

Enabling / disabling self-service flows

Two Dolibarr constants control the display of the "Create an account" and "My account" cards on the portal's homepage:

Constant Default value Effect
SMARTAUTH_REGISTRATION_ENABLED 1 The "Create an account" card is displayed and the /register route is accessible
SMARTAUTH_ACCOUNT_ENABLED 1 The "My account" card is displayed and the /account route is accessible

Set them to 0 to hide the corresponding flows if your deployment does not allow them (example: registrations reserved for an external workflow).

OAuth client management

Creating a client

  1. From the OAuth server tab, click OAuth clients or go directly to the client list
  2. Click New client
  3. Fill in the client information:

OAuth client creation form with the main fields

Field Description
Name Client name (example: "My WordPress application")
Redirect URIs One URI per line. Must be a valid HTTPS URL.
Allowed scopes Scopes the client can request (openid, profile, email, groups, offline_access)
Allowed grant types Authorization types: Authorization Code (web apps), Refresh Token, Client Credentials (machine-to-machine)
Client type Confidential (server application with a secret) or Public (mobile application/SPA with PKCE)
PKCE required Recommended for all clients

Available scopes

Scope Description
openid Required for OpenID Connect
profile User profile (name, etc.)
email Email address
groups User groups
offline_access Offline access (refresh token)

Custom scopes can be registered by external modules.

Confidential or public client

  • Confidential client -- Server application able to protect a secret (example: WordPress backend, Nextcloud). A secret is generated and displayed only once at creation.
  • Public client (PKCE) -- Mobile application or SPA that cannot store a secret securely. Authentication uses PKCE (Proof Key for Code Exchange) instead.

Warning: The client secret is displayed only once at creation. Copy it and keep it in a secure place. It cannot be retrieved later. You can however regenerate it if needed.

Managing an existing client

From the OAuth client list, you can:

  • View -- See the client details, its active tokens and the last issued token
  • Edit -- Update the redirect URIs, scopes and allowed grants
  • Enable/Disable -- Temporarily enable or disable a client
  • Regenerate the secret -- Generate a new secret (the old one is immediately invalidated)
  • Delete -- Delete the client and revoke all its tokens

Client Credentials (machine-to-machine)

The client_credentials grant type allows server-to-server authentication without user interaction.

Configuration

  1. Create an OAuth client of type confidential
  2. Enable the Client Credentials grant type
  3. Define a service user on the client record

The service user determines the permissions and the entity for the operations performed by the client. If no service user is defined on the client, SmartAuth uses the global default user (constant SMARTAUTH_DEFAULT_USER).

How it works

  1. The client sends grant_type=client_credentials with its client_id and client_secret
  2. SmartAuth validates the credentials and the requested scopes
  3. SmartAuth returns an access_token JWT (no refresh token or id_token in client credentials mode)

Dolibarr integration (SSO)

SmartAuth can serve as an authentication provider for another Dolibarr instance.

Creating the Dolibarr client

  1. Go to the OAuth server tab
  2. In the Dolibarr integration section, click Create the Dolibarr client
  3. Indicate the redirect URI of your target Dolibarr instance, in the form https://your-dolibarr/index.php?afteroauthloginreturn=1: it is the afteroauthloginreturn parameter that makes Dolibarr handle the SSO return. When the module is re-enabled, this variant is automatically added alongside each .../index.php URI already registered on the dolibarr-erp client.

Configuring the target Dolibarr instance

After creating the client, the tab displays the configuration instructions:

  1. If SmartAuth is not enabled on the target instance, copy the authentication file there (if it is, Dolibarr finds it in the module):

     cp htdocs/custom/smartauth/core/login/functions_smartauthoauth.php \
        /path/to/dolibarr/htdocs/core/login/
  2. Edit the conf.php file of the target instance:

     $dolibarr_main_authentication = 'smartauthoauth,dolibarr';
  3. Configure the Dolibarr constants on the target instance:

    Constant Value
    SMARTAUTH_OAUTH_ISSUER URL of your SmartAuth server
    SMARTAUTH_OAUTH_CLIENT_ID dolibarr-erp

Connection test

From the OAuth server tab, use the Test connection button to check that the SmartAuth server is reachable via the discovery endpoint.