🔐Gmail OAuth Setup
This guide will walk you through creating a Google Cloud application for OAuth authentication with Gmail. OAuth provides a more secure way to access your Gmail account compared to traditional password authentication.
📋 Prerequisites
A Google account (personal or Google Workspace)
Access to Google Cloud Console
Your Perfex CRM installation URL (for redirect URI configuration)
🚀 Step-by-Step Setup
Step 1: Create a Google Cloud Project
Go to Google Cloud Console
Click on the project dropdown at the top of the page
Click "New Project"
Enter a project name (e.g., "Perfex Mailbox OAuth")
Click "Create"
Wait for the project to be created and select it
Step 2: Enable Gmail API
In the Google Cloud Console, navigate to "APIs & Services" > "Library"
Search for "Gmail API"
Click on "Gmail API" from the results
Click "Enable"
Wait for the API to be enabled
Step 3: Configure OAuth Consent Screen
Navigate to "APIs & Services" > "OAuth consent screen"
Select "External" user type (unless you have a Google Workspace account, then you can choose "Internal")
Click "Create"
Fill in the required information:
App name: Enter your application name (e.g., "Perfex CRM Mailbox")
User support email: Your email address
Developer contact information: Your email address
Click "Save and Continue"
On the "Scopes" page, click "Add or Remove Scopes"
Add the following scopes:
https://www.googleapis.com/auth/gmail.readonlyhttps://www.googleapis.com/auth/gmail.sendhttps://www.googleapis.com/auth/gmail.modify
Click "Update", then "Save and Continue"
On the "Test users" page (if using External app type):
Add your Gmail address as a test user
Click "Save and Continue"
Review and click "Back to Dashboard"
Step 4: Create OAuth 2.0 Credentials
Navigate to "APIs & Services" > "Credentials"
Click "Create Credentials" > "OAuth client ID"
Select "Web application" as the application type
Enter a name for your OAuth client (e.g., "Perfex Mailbox Client")
Under "Authorized redirect URIs", click "Add URI"
Add your redirect URI in the format:
Replace
your-domain.comwith your actual Perfex CRM domainClick "Create"
IMPORTANT: Copy and save both:
Client ID (you'll need this)
Client Secret (you'll need this - click "Show" to reveal it)
Step 5: Configure in Perfex CRM
Go to your Perfex CRM admin area
Navigate to Mailbox > Configuration
Select "OAuth2" as your authentication method
Select "Gmail" as your provider
Enter your Client ID in the "Gmail Client ID" field
Enter your Client Secret in the "Gmail Client Secret" field
Click "Save Configuration"
Click the "Connect Gmail" button
Authorize the application in the Google popup window
You should see a success message confirming the connection
⚠️ Important Limitations & Considerations
Google Test App Limitations
These limitations are imposed by Google, not by our software:
Token Expiry (7 Days)
Unverified apps (apps in testing mode) have OAuth tokens that expire after 7 days
After 7 days, users must re-authorize the connection
This is a Google security policy for unverified applications
Test User Restrictions
Only users added to the "Test users" list can use the OAuth app
Maximum of 100 test users allowed
This restriction applies until the app is verified and published
App Verification Process
To remove the 7-day token expiry, you must submit your app for Google verification
Verification can take several weeks (typically 4-8 weeks)
Google reviews your app for security and compliance
This is a Google requirement, not a limitation of our module
App Verification & Publishing
To remove limitations:
Submit for Verification
Go to "OAuth consent screen" in Google Cloud Console
Click "PUBLISH APP" button
Fill out the verification form with:
App purpose and functionality
Privacy policy URL
Terms of service URL
Video demonstration (optional but recommended)
Submit for review
Verification Timeline
Initial review: 1-2 weeks
Additional information requests: Variable (if Google needs clarification)
Final approval: 4-8 weeks total (typical)
This timeline is set by Google, not our software
After Verification
Tokens no longer expire after 7 days
No test user restrictions
App can be used by any Gmail user
This is a Google policy, not controlled by our module
Production vs Testing
Testing Mode: Quick setup, but tokens expire every 7 days
Production Mode: Requires verification, but tokens don't expire
The choice is yours - our software works with both modes
🔄 Token Refresh
Our module automatically handles token refresh when possible. However:
Unverified apps: Tokens expire after 7 days and require manual re-authorization
Verified apps: Tokens refresh automatically without user intervention
This behavior is controlled by Google's policies, not our software
📝 Notes
The redirect URI must match exactly what you configured in Google Cloud Console
Keep your Client Secret secure - never share it publicly
If you change your domain, update the redirect URI in Google Cloud Console
The OAuth flow is handled entirely by Google - our module only initiates and receives the callback
🆘 Troubleshooting
"Redirect URI mismatch" error:
Ensure the redirect URI in Google Cloud Console matches exactly:
https://your-domain.com/admin/mailbox/oauth/callback?provider=gmailCheck for trailing slashes or HTTP vs HTTPS mismatches
"Token expired" after 7 days:
This is expected for unverified apps (Google's policy)
Re-authorize by clicking "Connect Gmail" again
To avoid this, submit your app for Google verification
"Access blocked" error:
Ensure your email is added to the "Test users" list (for unverified apps)
Check that Gmail API is enabled in your Google Cloud project
Can't find Gmail API:
Make sure you're in the correct Google Cloud project
Try searching for "Gmail" in the API Library
🔗 Additional Resources
Remember: The 7-day token expiry and test user restrictions are Google's security policies for unverified applications. These limitations are not imposed by our software. Once your app is verified by Google, these restrictions are removed.
Last updated