Table of Contents

  1. Introduction

  2. Why Enable Google OAuth in Dolibarr?

  3. Understanding the OAuth 2.0 Protocol

  4. System Requirements and Preparations

  5. Creating Your Google Cloud Project

  6. Configuring the OAuth Consent Screen

  7. Creating OAuth 2.0 Credentials

  8. Preparing Dolibarr for External Authentication

  9. Enabling the OAuth Module in Dolibarr

  10. Registering Google Credentials in Dolibarr

  11. Testing the OAuth Login Workflow

  12. Matching Google Accounts with Dolibarr Users

  13. Managing Application Scopes and Permissions

  14. Ensuring Secure Integration

  15. Troubleshooting Configuration Errors

  16. Recommended Practices for Stable OAuth Integration

  17. Use Case Scenarios and Value-Add Benefits

  18. Final Thoughts

1. Introduction

Dolibarr ERP/CRM is a trusted open-source platform used by organizations to streamline their business operations. With increasing security needs and growing reliance on centralized user identity systems, enabling external authentication via OAuth—especially through Google—is now a strategic choice. This guide provides a step-by-step walkthrough to help you activate Google OAuth in Dolibarr securely and effectively.

2. Why Enable Google OAuth in Dolibarr?

Activating Google OAuth for Dolibarr offers multiple benefits:

  • Ease of use: Users sign in with their familiar Google accounts.

  • Enhanced security: You leverage Google’s infrastructure for robust authentication.

  • Reduced IT overhead: No need to reset or manage additional passwords.

  • SSO readiness: Integrates into your broader authentication strategy, especially if using Google Workspace.

3. Understanding the OAuth 2.0 Protocol

OAuth 2.0 enables secure authorization from third-party services without revealing user credentials. Paired with OpenID Connect (OIDC), it also supports user authentication.

Key OAuth Components:

  • Client ID & Secret: Identifiers for your application

  • Scopes: Requested access levels (e.g., email, profile)

  • Redirect URI: The return endpoint in your application

4. System Requirements and Preparations

Ensure the following before starting:

  • A live Dolibarr instance (v13+ recommended)

  • HTTPS enabled on your domain

  • Administrative access to both Dolibarr and a Google account

  • Access to Google Cloud Console

Create a backup of Dolibarr before configuration to avoid disruptions.

5. Creating Your Google Cloud Project

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

  2. Navigate to IAM & Admin > Create a Project

  3. Give the project a name like "Dolibarr Google OAuth"

  4. Note your Project ID and Project Number for future reference

6. Configuring the OAuth Consent Screen

  1. Navigate to APIs & Services > OAuth Consent Screen

  2. Choose External unless you are restricting access to your Google Workspace domain

  3. Provide:

    • Application name

    • Support email

    • App logo (optional but recommended)

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

  4. Save and continue through the remaining steps

This screen is presented to users during authentication.

7. Creating OAuth 2.0 Credentials

  1. Go to APIs & Services > Credentials

  2. Click Create Credentials > OAuth Client ID

  3. Select Web application

  4. Name it "Dolibarr OAuth Access"

  5. Under Authorized Redirect URIs, add:

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

  1. Click Create

You will receive your Client ID and Client Secret—store them securely.

8. Preparing Dolibarr for External Authentication

Confirm that:

  • The public/oauth2callback.php file exists

  • You are using HTTPS (OAuth requires a secure return path)

  • Your server allows external requests (Google will redirect back to Dolibarr)

  • Apache’s mod_rewrite is enabled if you use friendly URLs

9. Enabling the OAuth Module in Dolibarr

  1. Login to Dolibarr as an administrator

  2. Go to Home > Setup > Modules/Applications

  3. Locate External Authentication (OAuth) module

  4. Click Enable

If not available, you may need to install or update your Dolibarr build.

10. Registering Google Credentials in Dolibarr

  1. Navigate to Setup > Security > Authentication Setup

  2. Select Google OAuth from the authentication method dropdown

  3. Enter:

    • Client ID from Google

    • Client Secret

    • Confirm the Redirect URI matches Google’s configuration

  4. Save changes

After saving, a “Login with Google” button should appear on the login page.

11. Testing the OAuth Login Workflow

  1. Log out of Dolibarr

  2. Click Login with Google

  3. Select a Google account

  4. Accept permission requests

  5. You will be redirected back to Dolibarr and logged in if everything is configured correctly

If errors occur, check logs in documents/admin/system.log and verify URI matches.

12. Matching Google Accounts with Dolibarr Users

Dolibarr uses the Google email to find a matching internal user:

  • Ensure each Dolibarr user has a valid, matching Google account email

  • Auto-user creation must be enabled to allow unknown users (not recommended in all cases)

  • Multi-company configurations require user presence in the active entity

13. Managing Application Scopes and Permissions

By default, Google requests the following scopes:

  • openid

  • email

  • profile

If you wish to expand access (e.g., Google Drive integration), you must:

  • Update scopes in your OAuth config

  • Undergo Google’s verification process for sensitive scopes

14. Ensuring Secure Integration

Best practices include:

  • Keeping the Client Secret hidden and not committed to code

  • Restricting OAuth credentials to specific domains

  • Logging OAuth logins for auditing

  • Using HTTPS for all pages

  • Adding reCAPTCHA or IP-based restrictions for login pages

If there’s any suspicion of compromise, regenerate the OAuth credentials immediately.

15. Troubleshooting Configuration Errors

Symptom Likely Cause Fix
Error 403 disallowed_useragent In-app browser Use standalone browser
redirect_uri_mismatch Mismatched URI Copy exact URI from Google Console
Blank login result PHP or OAuth error Enable debugging and check logs
User not found Email mismatch Match Dolibarr login email with Google

Using browser dev tools (F12 > Network tab) can reveal underlying error codes.

16. Recommended Practices for Stable OAuth Integration

  • Maintain separate Google credentials for staging and production

  • Regularly audit OAuth activity via Google Cloud Console

  • Document configuration for future system admins

  • Inform users of login policy changes

  • Pair OAuth login with Dolibarr’s internal security features like 2FA

17. Use Case Scenarios and Value-Add Benefits

For Enterprises Using Google Workspace:

Centralized login and SSO reduce friction for internal teams.

For Educational Institutions:

Link Dolibarr with student Google accounts to streamline login.

For Customer Portals:

Clients can use Gmail credentials to access secure invoice or service areas.

18. Final Thoughts

Activating the Google OAuth service in Dolibarr is a powerful upgrade. It modernizes the login process, enhances security, and improves user satisfaction. While the setup requires attention to detail—especially in URI matching and credential handling—it pays off with seamless integration into the Google ecosystem.

Use this guide to ensure a complete and secure deployment, and revisit it regularly as both Dolibarr and Google evolve.