Table of Contents

  1. Introduction

  2. Why Use Google OAuth with Dolibarr?

  3. Understanding OAuth 2.0 and OpenID Connect

  4. Prerequisites and Environment Preparation

  5. Step 1: Creating a Google OAuth Project

  6. Step 2: Configuring OAuth Consent Screen

  7. Step 3: Generating Client ID and Client Secret

  8. Step 4: Preparing Dolibarr for OAuth Authentication

  9. Step 5: Installing and Activating the OAuth Module in Dolibarr

  10. Step 6: Entering OAuth Credentials in Dolibarr

  11. Step 7: Testing the Google Login Process

  12. User Account Mapping in Dolibarr

  13. Managing Scopes and Permissions

  14. Securing OAuth Integration

  15. Troubleshooting Common Issues

  16. Best Practices for OAuth Authentication in Production

  17. Real-World Use Cases and Benefits

  18. Conclusion

1. Introduction

Dolibarr ERP/CRM is a powerful and modular open-source platform for managing business operations. However, as systems become increasingly connected and security expectations rise, modern authentication methods such as OAuth 2.0 are becoming essential. One of the most popular OAuth providers is Google. In this article, we will walk through the complete setup to enable Google OAuth login in Dolibarr.

2. Why Use Google OAuth with Dolibarr?

Integrating Google OAuth provides several advantages:

  • Simplified login: Users log in with their existing Google credentials

  • Increased security: Leverages Google’s secure authentication infrastructure

  • Time-saving: No need to remember additional passwords

  • Centralized identity management

This is especially useful for organizations already using Google Workspace (formerly G Suite).

3. Understanding OAuth 2.0 and OpenID Connect

OAuth 2.0 is a protocol for secure authorization. OpenID Connect (OIDC) is an identity layer on top of OAuth 2.0, enabling authentication.

Google supports OIDC, allowing you to authenticate users and retrieve their profile information (email, name, etc.).

Key Concepts:

  • Client ID / Secret: Unique identifiers used by your application

  • Redirect URI: The Dolibarr URL that Google sends users back to after login

  • Scopes: Define which user info you can access

4. Prerequisites and Environment Preparation

Before starting, ensure the following:

  • Dolibarr v13 or newer

  • Administrator access to Dolibarr and a Google account

  • HTTPS-enabled domain (OAuth requires secure redirect URIs)

  • Basic understanding of Google Cloud Console

Optional but recommended:

  • A test Dolibarr instance to validate OAuth without affecting production

5. Step 1: Creating a Google OAuth Project

  1. Visit https://console.cloud.google.com

  2. Click on IAM & Admin > Create a Project

  3. Name your project (e.g., “Dolibarr OAuth Login”)

  4. Note the Project ID

Each OAuth credential is tied to a Google Cloud project.

6. Step 2: Configuring OAuth Consent Screen

  1. Go to APIs & Services > OAuth Consent Screen

  2. Choose Internal (for Google Workspace domains) or External

  3. Fill in required fields:

    • App name

    • Support email

    • Logo (optional)

    • Authorized domains (e.g., mycompany.com)

  4. Save and continue

You must complete this setup to use OAuth credentials.

7. Step 3: Generating Client ID and Client Secret

  1. Go to APIs & Services > Credentials

  2. Click + Create Credentials > OAuth 2.0 Client IDs

  3. Choose Web application

  4. Set a name like "Dolibarr Login"

  5. Under Authorized redirect URIs, add:

https://yourdolibarrdomain.com/public/oauth2callback.php

 

6. Click **Create**

Google will generate your **Client ID** and **Client Secret**.

---

## 8. Step 4: Preparing Dolibarr for OAuth Authentication

Make sure your Dolibarr instance:
- Runs under HTTPS
- Has the `public/oauth2callback.php` file (included in newer versions)
- Is accessible from the internet if Google needs to redirect to it

You may also need to enable Apache `mod_rewrite` if using clean URLs.

---

## 9. Step 5: Installing and Activating the OAuth Module in Dolibarr

1. Log in as administrator
2. Navigate to **Home > Setup > Modules/Applications**
3. Search for **External Authentication** or **OAuth Login**
4. Click **Enable**

Some distributions include the module by default; others may require installation.

---

## 10. Step 6: Entering OAuth Credentials in Dolibarr

1. Go to **Setup > Security > Authentication Setup**
2. Select **Google OAuth** as the method
3. Enter:
   - **Client ID** from Google
   - **Client Secret** from Google
   - **Redirect URI** (auto-filled or must match Google config)
4. Save the configuration

Once saved, Dolibarr shows a **Login with Google** button on the login page.

---

## 11. Step 7: Testing the Google Login Process

1. Log out of Dolibarr
2. Click **Login with Google**
3. Choose your Google account
4. Grant requested permissions
5. If everything works, you’ll be redirected and logged in

If you see an error, review the Google OAuth logs or Dolibarr error logs in `documents/admin/system.log`.

---

## 12. User Account Mapping in Dolibarr

When a user logs in via Google:
- Dolibarr attempts to match the email with an existing user
- If not found, access is denied unless automatic user creation is enabled

To link users:
- Ensure the Dolibarr user has the same email as their Google account
- For multi-entity setups, make sure the user exists in the correct entity

---

## 13. Managing Scopes and Permissions

By default, Dolibarr requests:
- Email address
- Profile info

In most cases, these are sufficient. If your app needs more (e.g., access to Google Drive), you must:
- Add additional scopes
- Undergo Google’s verification process

---

## 14. Securing OAuth Integration

Security is paramount:
- Never expose the **Client Secret** publicly
- Restrict credentials to your domain only
- Monitor OAuth activity in Google Console
- Enable reCAPTCHA on Dolibarr login page for added security

If compromised, immediately revoke the credentials and regenerate them.

---

## 15. Troubleshooting Common Issues

| Issue | Solution |
|-------|----------|
| 403: disallowed_useragent | Test on desktop browser, not in-app web views |
| Error: redirect_uri_mismatch | Ensure URI in Dolibarr and Google match exactly |
| Blank screen after login | Check Dolibarr logs, PHP error logs |
| User not recognized | Match Google email with Dolibarr user email |

Use browser dev tools to trace redirects and error responses.

---

## 16. Best Practices for OAuth Authentication in Production

- Use separate Google projects for staging and production
- Enable logging of OAuth logins for auditing
- Regularly review and update your authorized domains
- Inform users about how their data is used
- Combine OAuth login with 2FA for admin accounts

---

## 17. Real-World Use Cases and Benefits

- **Internal teams using Google Workspace**: seamless login without remembering new credentials
- **Client portals**: external users can access with their Gmail accounts
- **Education institutions**: integrate student accounts via Google SSO

In each case, user adoption and login speed significantly improve.

---

## 18. Conclusion

Integrating Google OAuth with Dolibarr modernizes your login process, boosts security, and improves user experience. With just a few configuration steps, you enable a more streamlined and professional authentication flow. Whether you're an enterprise using Google Workspace or a small business leveraging Gmail accounts, OAuth integration in Dolibarr is a strategic upgrade worth implementing.