FAQ

General questions

What is SmartAuth for?

SmartAuth manages authentication and authorization for SmartMaker mobile applications and third-party services that connect to your Dolibarr. It provides JWT tokens for mobile applications and an OAuth2/OIDC server for Single Sign-On.

Does SmartAuth replace Dolibarr's native authentication?

No. SmartAuth works alongside native authentication. Access to the Dolibarr web interface continues to use the standard login system. SmartAuth only manages the authentication of external applications (mobile, API, third-party services).

Which Dolibarr versions are compatible?

SmartAuth requires Dolibarr 18.0 or higher and PHP 7.4 or higher.

Tokens and devices

What is a token family?

Each device that connects via SmartAuth creates a token family. This family groups the device's access token and refresh token. Revoking a family logs out only that device, without affecting the others.

Why was a token automatically revoked?

SmartAuth detects replay attacks. If an already used refresh token is presented a second time, the whole token family is immediately revoked. This mechanism protects against token theft.

How do I revoke all of a user's tokens?

Go to the Dolibarr user record, SmartAuth tab. You will see all active tokens and can revoke them individually. For a bulk revocation, use the token list from Tools > SmartAuth > Tokens.

What is the lifetime of a token?

By default, tokens expire after 30 days. This duration is configurable in the module settings (10, 20, 30 or 90 days).

OAuth2/OIDC server

Do I need to enable the OAuth server to use SmartMaker mobile applications?

No. SmartMaker mobile applications use JWT authentication, which works independently of the OAuth server. The OAuth server is only needed for SSO with third-party applications or for machine-to-machine authentication.

What is the difference between a confidential client and a public client?

A confidential client is a server application able to protect a secret (example: WordPress, Nextcloud). A public client is a mobile application or a Single Page Application (SPA) that cannot store a secret securely and uses PKCE instead.

How do I connect WordPress or Nextcloud to Dolibarr via SmartAuth?

  1. Enable the OAuth server in the SmartAuth configuration
  2. Create a confidential OAuth client with the redirect URIs of your application
  3. Configure the OAuth/OIDC plugin of your application with the endpoints and the client secret provided by SmartAuth

What is Client Credentials mode?

Client Credentials mode allows a server to authenticate to Dolibarr without human intervention. It is used for machine-to-machine exchanges (automatic synchronization, imports, exports). A service user must be defined on the OAuth client to determine permissions.

Rate limiting and security

How many login attempts are allowed?

SmartAuth applies two levels of rate limiting:

  • Per IP address: 10 attempts allowed over a 5-minute window
  • Per user: 5 attempts allowed over a 15-minute window

Beyond these thresholds, attempts are blocked.

How do I unblock a blocked IP address?

The block is temporary and lifts automatically after the time window expires (5 minutes for the IP block). If you need to intervene immediately, empty the llx_smartauth_ratelimit table in the database.

Do logs consume a lot of space?

Yes, if log collection is enabled and your API receives a high volume of requests. Enable automatic cleanup in the configuration and set a retention period suited to your needs.

Common problems

The SmartAuth menu does not appear

Check that the module is enabled and that the user has the "Read objects of SmartAuth" permission.

The logs remain empty

Log collection is disabled by default. Enable the SMARTAUTH_COLLECT_LOGS option in the configuration.

The OAuth connection test fails

Check that the issuer URL is reachable from the server itself (no loopback firewall blocking). Also check that the SSL certificate is valid if you use HTTPS.

I get "Forbidden" on /.well-known/openid-configuration

The default Apache configuration on Debian/Ubuntu contains a global <DirectoryMatch "(^|/)\\."> rule that forbids access to any path starting with a dot. This rule is evaluated before the module's .htaccess, which therefore cannot lift it from the inside.

Add the exception in the vhost of your SSO portal:

<LocationMatch "^/\\.well-known/">
    Require all granted
</LocationMatch>

Then sudo systemctl reload apache2. See the Public SSO portal section of the OAuth chapter for the complete vhost configuration.

The link generated in the email uses SMARTAUTH_APP_URL as its base, or DOL_MAIN_URL_ROOT by default. Define the Dolibarr constant SMARTAUTH_APP_URL with the root URL of your SSO portal (example: https://auth.example.com) so that the reset-password?token=... link opens the form directly on the portal instead of the Dolibarr admin.