Overview

Google SSO Integration allows your users to authenticate to Cloud-PBX using their Google Workspace credentials, providing seamless access without managing separate passwords.

Integration Components:

• Google OAuth 2.0: Secure single sign-on
• Google Contacts API: Contact directory synchronization
• Google Calendar API: Calendar-based availability
• Google Chat: Limited presence sync (beta)

Key Benefits:

• One-click login with corporate Google account
• No separate password management
• Automatic user provisioning
• Calendar-based Do Not Disturb
• Company directory sync
• Click-to-call from Gmail and Contacts

Features

Single Sign-On (SSO)

Authentication Flow:

1. User clicks "Sign in with Google" on Cloud-PBX login
2. Redirected to accounts.google.com
3. Selects Google Workspace account
4. Authenticates (password + 2FA if enabled)
5. Grants permissions to Cloud-PBX (first time)
6. Redirected back and automatically logged in

Auto-Provisioning:

• New users automatically created on first login
• Profile populated from Google Workspace (name, email, photo)
• Extension assigned from available pool
• Permissions based on Google Workspace group membership
• Profile photo synced from Google account

Security Features:

• OAuth 2.0 industry-standard authentication
• 2-Step Verification enforced if enabled in Workspace
• Short-lived access tokens (1 hour)
• Automatic token refresh (no repeated logins)
• Conditional access support
• Session management via Google Workspace admin

Google Calendar Integration

Calendar-Based Availability:

Event Handling:

• Buffer Time: DND enabled 5 minutes before/after events
• All-Day Events: "Out of Office" triggers custom greeting
• Recurring Events: Only active during event times
• Time Zones: Automatic adjustment for user's location
• Private Events: Only free/busy visible (details hidden)
• Multiple Calendars: Monitor primary calendar by default

Working Location Sync: Google Calendar's working location feature:

• Office: Route to desk phone preferred
• Home: Route to softphone or mobile
• Other Location: Follow mobile routing

Pre-Meeting Notifications:

• Alert 5 minutes before scheduled meetings
• Option to enable DND early
• Quick link to join video call
• Automatic status update to "In a meeting"

Google Contacts Sync

Contact Information Synced:

• Full name and nickname
• Email addresses (all types)
• Phone numbers (work, mobile, home, other)
• Company name and job title
• Physical addresses
• Notes and custom fields
• Profile photos
• Contact groups

Sync Options:

Settings → Integrations → Google → Contacts
Sync Mode: Personal Contacts Only
Update Frequency: Every 15 minutes

Sync Mode: Domain Directory
Scope: All Users
Include External: No
Update Frequency: Every 30 minutes

Sync Mode: Shared Contacts
Lists: Select which shared lists
External Contacts: Allow

Sync Mode: Selected Groups
Groups:
  ☑ Sales Team
  ☑ Support Team
  ☑ VIP Customers
  ☐ Personal (excluded)

Contact Display:

• Caller ID shows name and photo from Google Contacts
• Click-to-open contact in Google Contacts
• Call history visible in Cloud-PBX
• Updates synced within 15 minutes

Click-to-Call from Gmail and Contacts

Gmail Integration:

• Click phone numbers in emails to call instantly
• Call contacts from Gmail sidebar
• Browser extension highlights phone numbers
• Call history logged to contact record

Google Contacts Integration:

• Call button appears on contact cards
• Click phone number on contact detail page
• Mobile app: Tap to call from Google Contacts
• Recent call history displayed

Installation:

• Browser: Install Cloud-PBX Chrome extension
• Mobile: Cloud-PBX app integrates with Android dialer
• Desktop: Cloud-PBX desktop client (Windows/Mac)

Call Logging: All calls initiated via click-to-call automatically logged with:

• Contact name and number
• Source (Gmail, Google Contacts, etc.)
• Call duration and outcome
• Recording link if enabled
• Notes and tags

Google Chat Presence (Beta)

Limited Presence Sync:

• Share availability between Cloud-PBX and Google Chat
• On a call → Google Chat shows "Busy"
• DND enabled → Google Chat shows "Do not disturb"
• Away/Idle sync between platforms

Limitations:

• Requires Google Chat enabled (Workspace feature)
• One-way sync: Cloud-PBX → Google Chat (not reverse)
• 1-2 minute delay typical
• Less robust than Microsoft Teams integration
• Beta feature, subject to Google API changes

Configuration:

Settings → Integrations → Google → Presence
Enable Google Chat Sync: Yes (Beta)
Update Frequency: Real-time (webhooks)

Setup Guide

Settings → Integrations → Google → Provisioning

Auto-Create Users: Enabled
Match By: Email Address
Extension Pool: 3000-3999
Default Permissions: Standard User
Create on First Login: Yes

Google → Cloud-PBX
──────────────────────
name.fullName → Full Name
primaryEmail → Email
organizations[0].title → Job Title
organizations[0].department → Department
phones[type=mobile].value → Mobile
relations[type=manager] → Reports To

Subject: New Google Login for Cloud-PBX

We've integrated Cloud-PBX with Google Workspace!

✅ Sign in with your Google account (no new password)
✅ Calendar events automatically enable Do Not Disturb
✅ Click phone numbers in Gmail to call instantly
✅ Your Google contacts synced to phone system

Get Started:
1. Go to admin.voco.us
2. Click "Sign in with Google"
3. Use your @company.com account

Questions? See our guide: [link]

Advanced Configuration

Calendar Event Rules

Customize Calendar Behavior:

Settings → Integrations → Google → Calendar Rules

Event Type Rules:
────────────────────────────────────────────────
Busy Events              → Enable DND
Free Events              → Normal routing
Tentative Events         → Ring but show warning
Out of Office            → Custom greeting + forward
Working Location (Home)  → Route to mobile/softphone
Working Location (Office)→ Route to desk phone

Options:
────────────────────────────────────────────────
Buffer Time: 5 minutes before/after
All-Day Events: Check "Out of Office" only
Private Events: Respect (no DND if private)
Multiple Calendars: Primary only

Advanced Rules:

• VIP callers bypass calendar DND
• Urgent keywords in subject override DND
• Work hours only (ignore evening/weekend events)
• Specific calendar exceptions

Contact Sync Optimization

For Large Organizations (1000+ users):

Selective Sync:

Sync Strategy: Group-Based
Selected Groups:
  ☑ Employees (all staff)
  ☐ Contractors (excluded)
  ☑ Shared Contacts (customers)

Performance Settings:
  Update Frequency: 30 minutes
  Incremental Sync: Yes
  Photo Sync: Thumbnails only
  Cache Duration: 7 days

API Quota Management: Google API quotas:

• People API: 300 requests/minute
• Calendar API: 1,000 requests/100 seconds
• Admin SDK: 2,400 requests/minute

Mitigation:

• Batch requests (up to 100 contacts per call)
• Incremental sync (only changed contacts)
• Cache aggressively
• Off-peak full sync (2 AM)

Working Location Integration

Google Calendar Working Location: New feature in Google Workspace for hybrid work.

How It Works: Users set working location in Google Calendar:

• Office: Physical office location
• Home: Remote work
• Other: Coffee shop, co-working, etc.

Cloud-PBX Routing:

Location    → Preferred Device    → Fallback
──────────────────────────────────────────────
Office      → Desk Phone          → Mobile
Home        → Softphone           → Mobile
Other       → Mobile              → Softphone

Configuration:

Settings → Integrations → Google → Working Location

Enable Working Location Sync: Yes
Update Routing Preferences: Yes
Allow Manual Override: Yes

User Experience:

• User sets location in Google Calendar
• Within 5 minutes, Cloud-PBX updates routing
• No manual configuration needed
• User can always override if needed

Troubleshooting

SSO Login Issues

Problem: "Error 400: redirect_uri_mismatch"

Solution:

• Redirect URI must exactly match Google Cloud Console
• Check for typos, http vs https, trailing slash
• Verify: Google Cloud Console → Credentials → OAuth Client → Authorized redirect URIs

Problem: "Access blocked: Cloud-PBX has not completed the Google verification process"

Solution:

• App not verified by Google (normal for internal apps)
• Click "Advanced" → "Go to Cloud-PBX (unsafe)"
• OR: Set OAuth consent screen to "Internal" (Workspace users only)
• OR: Submit app for Google verification (public apps)

Problem: "Error 403: access_denied"

Solution:

• User doesn't have permission to grant OAuth scopes
• Check Google Workspace Admin → Security → API Controls
• Ensure "Trust internal apps" is enabled
• Verify user's account is in correct Workspace domain

Calendar Sync Issues

Problem: Calendar events not triggering DND

Checklist:

• ✅ Calendar integration enabled in Cloud-PBX settings
• ✅ User granted calendar.readonly scope during OAuth
• ✅ Event marked "Busy" (not Free)
• ✅ Event on primary calendar
• ✅ Time zone set correctly in both systems
• ✅ Calendar sync status shows "Active"

Check OAuth Scopes:

Settings → Integrations → Google → User: [username]
→ View Granted Permissions
→ Should include: "https://www.googleapis.com/auth/calendar.readonly"

If missing, user must re-authorize:

1. User signs out of Cloud-PBX
2. Admin: Reset user consent (Settings → Integrations → Google)
3. User signs in again and grants calendar permission

Manual Sync:

Settings → Integrations → Google → Calendar
→ Select user → Click "Force Sync"
→ Check last sync time updates

Contact Sync Issues

Problem: Contacts not syncing

Diagnostic Steps:

1. Check integration status: Settings → Integrations → Google
2. Status should be "Connected" (green)
3. Last sync time: Should be <30 minutes ago
4. Check logs for errors

Common Issues:

Force Full Resync:

Settings → Integrations → Google → Contacts
→ Click "Clear Cache and Resync All"
→ Wait 5-10 minutes
→ Check contacts reappear

Domain Directory Not Syncing:

• Verify domain-wide delegation configured
• Check service account has correct scopes
• Ensure Admin SDK API enabled in Google Cloud
• Confirm service account JSON uploaded to Cloud-PBX

Click-to-Call Issues

Problem: Phone numbers not highlighted in Gmail

Browser Extension Check:

1. Check extension installed: chrome://extensions
2. Verify "Cloud-PBX Click-to-Call" is enabled
3. Permissions granted: "Read and change all your data on the websites you visit"
4. Extension icon shows as logged in (green)

Reload Gmail:

• Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
• Clear browser cache
• Disable/re-enable extension

Phone Number Format: Extension detects these formats:

+1 (555) 123-4567
555-123-4567
555.123.4567
(555) 123-4567
+44 20 1234 5678

If number not detected, format may be non-standard.

Mobile App:

• Cloud-PBX app must be installed
• Set as default dialer (Android settings)
• Grant phone permissions
• Sign in to app with Google SSO

Google Chat Presence Issues

Problem: Presence not syncing with Google Chat

Known Limitations:

• Beta feature, may be unstable
• Requires Google Chat enabled (Workspace setting)
• One-way sync only (Cloud-PBX → Google Chat)
• 1-2 minute delay expected
• Google Chat API changes may break sync

Troubleshooting:

1. Verify Google Chat enabled:
   • Google Admin → Apps → Google Workspace → Google Chat → Enable
2. Check API enabled:
   • Google Cloud Console → APIs → Google Chat API → Enabled
3. OAuth scope granted:
   • https://www.googleapis.com/auth/chat.users.readonly
4. Re-authorize integration if needed

Alternative: If presence sync unreliable, consider disabling:

Settings → Integrations → Google → Presence
Enable Google Chat Sync: No

Google Calendar's working location and busy/free status provide sufficient availability info without Chat presence.

Security Best Practices

OAuth Security

Scope Minimization: Only request scopes you actually use:

• ✅ Required: email, profile, calendar.readonly, contacts.readonly
• ⚠️ Optional: admin.directory.user.readonly (only if using domain directory)
• ⚠️ Beta: chat.users.readonly (only if using presence)
• ❌ Avoid: calendar, contacts (write access not needed)

Token Management:

• Access tokens valid 1 hour
• Refresh tokens valid until revoked
• Tokens stored encrypted (AES-256)
• Auto-refresh without user interaction
• Revoke immediately on user removal

User Consent:

• Users explicitly grant permissions
• Consent screen shows exact data accessed
• Users can revoke anytime: Google Account → Security → Third-party apps
• Admin can revoke org-wide: Admin Console → Security → API Controls

Google Workspace Security Controls

Admin Security Settings:

API Access Controls:

Google Admin → Security → API Controls

Settings:
  Trust internal, domain-owned apps: Enabled
  API access: Unrestricted (or whitelist Cloud-PBX)
  2-Step Verification: Enforced
  OAuth 2.0 apps: Monitor usage

Context-Aware Access (Enterprise Plus):

• Restrict Cloud-PBX access by location
• Require corporate devices only
• Block risky sign-ins
• IP allowlisting

Session Management:

Admin → Security → Session Control

Google session length: 8 hours
Reauthentication: Required every 24 hours
Device approval: Require approved devices

Audit and Compliance

Audit Logging: All Google SSO events logged:

• OAuth authentication attempts
• Permission grants and denials
• Calendar sync events
• Contact access
• API errors and rate limits

Export Audit Logs:

Settings → System → Audit Logs
Filter: Google Integration
Date Range: Last 90 days
Export: CSV or JSON

Google Workspace Logs: Also check Google Admin audit logs:

Admin Console → Reporting → Audit → OAuth Token
Shows: Which apps accessed what data, when

Data Privacy:

• Only free/busy calendar info accessed (not event details)
• Contact data cached encrypted
• Profile photos cached 7 days
• User can export/delete their data
• GDPR-compliant data processing

Performance Optimization

Reducing API Usage

For Large Organizations:

Contact Sync Optimization:

Strategy: Incremental Sync
Full Sync: Daily at 2 AM
Incremental: Every 30 minutes (only changes)
Photos: Thumbnails only
Cache: 7 days

API Calls Reduced:
  Before: 10,000 calls/hour
  After: 500 calls/hour (95% reduction)

Calendar Sync Optimization:

• Use push notifications (webhooks) instead of polling
• Query only free/busy (not full event details)
• Cache calendar data 5 minutes
• Skip weekends/holidays for work calendars

Batch Operations:

• Fetch 100 contacts per API call (not 1 at a time)
• Use batch endpoints where available
• Parallel requests (up to 10 concurrent)

Monitoring Integration Health

Key Metrics:

• OAuth success rate: >99%
• Calendar sync lag: <5 minutes
• Contact sync duration: <10 minutes (full), <2 minutes (incremental)
• API error rate: <1%
• Quota usage: <80% of limits

Health Dashboard:

Settings → Integrations → Google → Health

Status: Connected ✅
Last Sync: 2 minutes ago
Active Users: 87 / 100
API Quota: 45% used
Errors (24h): 3 (0.1%)

Alerts:

Alert Conditions:
  ☑ OAuth failure rate > 5%
  ☑ Sync fails 3 times in a row
  ☑ API quota > 90%
  ☑ Last sync > 1 hour ago
  ☑ Error rate > 5%

Notification: Email IT team

Frequently Asked Questions

Q: Do users need Google Workspace or can they use personal Gmail? A: Google Workspace required for SSO and directory features. Personal Gmail accounts can authenticate but won't have domain directory or advanced features.

Q: Can we use multiple Google Workspace domains? A: Yes, Enterprise plan supports multi-domain. Each domain requires separate OAuth configuration.

Q: What happens if Google API is down? A: Cloud-PBX continues working normally. SSO may fallback to password login. Cached contact/calendar data used until API recovers. Phone calls unaffected.

Q: Can we sync only specific Google Groups? A: Yes, configure selective sync: Settings → Integrations → Google → Contacts → Sync Mode: Selected Groups

Q: How do we handle external/guest users? A: Guest users (non-Workspace) cannot use SSO. They need separate Cloud-PBX accounts with password login.

Q: Can users have different email formats? A: Yes, if you have multiple verified domains in Workspace. All verified domains can use SSO.

Q: Does this work with Google Workspace for Education? A: Yes, full support for Education plans. Same OAuth setup process.

Q: Can we force 2-Step Verification for Cloud-PBX only? A: Configure via Google Workspace Admin → Security → 2-Step Verification. Can enforce for specific organizational units.

Q: What if user changes their Google password? A: OAuth tokens remain valid. User doesn't need to re-authenticate in Cloud-PBX.

Q: Can we customize the SSO button? A: Yes, Settings → Integrations → Google → Branding

• Button text customization
• Logo upload
• Brand colors

Comparison: Google vs Microsoft 365

Recommendation:

• Microsoft 365: Better for Teams-centric organizations, richer presence sync
• Google Workspace: Better working location support, simpler setup
• Both: Can enable both integrations for hybrid environments

Getting Help

Resources:

• Video Tutorial: Google SSO setup walkthrough (15 minutes)
• OAuth Setup Checklist: Step-by-step guide
• Troubleshooting Flowchart: Diagnose common issues
• API Reference: Google API documentation

Next Steps