Table of Contents
-
Introduction
-
Why Enable Google OAuth in Dolibarr?
-
Understanding the OAuth 2.0 Protocol
-
System Requirements and Preparations
-
Creating Your Google Cloud Project
-
Configuring the OAuth Consent Screen
-
Creating OAuth 2.0 Credentials
-
Preparing Dolibarr for External Authentication
-
Enabling the OAuth Module in Dolibarr
-
Registering Google Credentials in Dolibarr
-
Testing the OAuth Login Workflow
-
Matching Google Accounts with Dolibarr Users
-
Managing Application Scopes and Permissions
-
Ensuring Secure Integration
-
Troubleshooting Configuration Errors
-
Recommended Practices for Stable OAuth Integration
-
Use Case Scenarios and Value-Add Benefits
-
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
-
Navigate to IAM & Admin > Create a Project
-
Give the project a name like "Dolibarr Google OAuth"
-
Note your Project ID and Project Number for future reference
6. Configuring the OAuth Consent Screen
-
Navigate to APIs & Services > OAuth Consent Screen
-
Choose External unless you are restricting access to your Google Workspace domain
-
Provide:
-
Application name
-
Support email
-
App logo (optional but recommended)
-
Authorized domains (e.g., yourdolibarrdomain.com)
-
-
Save and continue through the remaining steps
This screen is presented to users during authentication.
7. Creating OAuth 2.0 Credentials
-
Go to APIs & Services > Credentials
-
Click Create Credentials > OAuth Client ID
-
Select Web application
-
Name it "Dolibarr OAuth Access"
-
Under Authorized Redirect URIs, add:
https://yourdolibarrdomain.com/public/oauth2callback.php
-
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
-
Login to Dolibarr as an administrator
-
Go to Home > Setup > Modules/Applications
-
Locate External Authentication (OAuth) module
-
Click Enable
If not available, you may need to install or update your Dolibarr build.
10. Registering Google Credentials in Dolibarr
-
Navigate to Setup > Security > Authentication Setup
-
Select Google OAuth from the authentication method dropdown
-
Enter:
-
Client ID from Google
-
Client Secret
-
Confirm the Redirect URI matches Google’s configuration
-
-
Save changes
After saving, a “Login with Google” button should appear on the login page.
11. Testing the OAuth Login Workflow
-
Log out of Dolibarr
-
Click Login with Google
-
Select a Google account
-
Accept permission requests
-
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.