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
- Go to Home > Setup > Modules > SmartAuth
- Open the OAuth server tab
- Check Enable the OAuth/OIDC server
- Click Save

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 Allis required so that the.htaccessprovided by the module (public/.htaccess) is taken into account (rewrites toindex.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:
- Go to Home > Setup > Other
- Add/modify the
SMARTAUTH_APP_URLconstant with the root URL of the portal as its value (example:https://auth.example.com) - 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
- From the OAuth server tab, click OAuth clients or go directly to the client list
- Click New client
- Fill in the client information:

| 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
- Create an OAuth client of type confidential
- Enable the Client Credentials grant type
- 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
- The client sends
grant_type=client_credentialswith itsclient_idandclient_secret - SmartAuth validates the credentials and the requested scopes
- SmartAuth returns an
access_tokenJWT (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
- Go to the OAuth server tab
- In the Dolibarr integration section, click Create the Dolibarr client
- Indicate the redirect URI of your target Dolibarr instance, in the form
https://your-dolibarr/index.php?afteroauthloginreturn=1: it is theafteroauthloginreturnparameter that makes Dolibarr handle the SSO return. When the module is re-enabled, this variant is automatically added alongside each.../index.phpURI already registered on thedolibarr-erpclient.
Configuring the target Dolibarr instance
After creating the client, the tab displays the configuration instructions:
-
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/ -
Edit the
conf.phpfile of the target instance:$dolibarr_main_authentication = 'smartauthoauth,dolibarr'; -
Configure the Dolibarr constants on the target instance:
Constant Value SMARTAUTH_OAUTH_ISSUERURL of your SmartAuth server SMARTAUTH_OAUTH_CLIENT_IDdolibarr-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.