---
title: "OAuth2/OIDC server"
weight: 35
description: "Configuring and using the OAuth2/OIDC server integrated into SmartAuth for SSO and machine-to-machine authentication."
source_hash: "0ca371c9"
---

# 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](screenshots/configuration-oauth.webp)

## 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:

```apache
<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:

```bash
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:

```bash
# 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:

```bash
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](screenshots/creation-client-oauth.webp)

| 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):

    ```bash
    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:

    ```php
    $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.
