Google Workspace Setup

Overview

This guide walks you through connecting Google Workspace to VeloPBX. The integration uses an OAuth 2.0 client created in your Google Cloud project, paired with VeloPBX’s tenant-level configuration.

Setup time: ~15 minutes (the longest of the workspace setups — Google Cloud project creation adds overhead). Tenant admin only.

By the end of this guide, your VeloPBX tenant will be able to:

• Sync users from Google Workspace — auto-create PBX extensions for Workspace users
• Single Sign-On (SSO) — users sign into the VeloPBX Web Portal and PortSIP ONE app with their Google credentials
• Send email notifications via Gmail OAuth — voicemail alerts, password resets, and system notifications go through your Workspace Gmail (replaces “less-secure app passwords” which Google deprecated)

Critical: Sync Mode is permanent

Before you start, decide which Sync Mode you want:

• Manual — administrators trigger user synchronization on demand (clicking a button in the VeloPBX admin)
• Automatic — the system syncs Google Workspace users on a schedule

Important: Once you select a Sync Mode, it cannot be changed later. Choose carefully. Automatic is the right default for most tenants — it keeps the PBX directory current without manual intervention. Manual is for small tenants who want explicit control over who gets a PBX extension.

Prerequisites

Before you start, make sure you have:

• A Google Workspace subscription (any tier — Business Starter and above all work)
• A Google Cloud account linked to your Google Workspace org (you’ll create a Cloud project for the OAuth client)
• Tenant Admin Full Access in VeloPBX
• Your VeloPBX server running on a static public IP
• A configured FQDN for the PBX with a valid SSL certificate from a trusted public CA (DigiCert, Let’s Encrypt, GoDaddy, Sectigo, etc.) — Google rejects self-signed and private-CA certificates
• 2-factor authentication enabled on the Google account that will own the integration (Google requires 2FA for all OAuth client owners)

Why so strict on SSL? Google’s OAuth flow validates your redirect URI’s certificate during every sign-in. If the cert is self-signed or expired, sign-in fails for every user. Verify with curl -v https://your-pbx-host:8887/ before starting.

Step 1 — Create a Google Cloud project

Open https://console.cloud.google.com/ and sign in with the Google account that owns (or admins) your Workspace.

1. Click the project picker dropdown in the top bar.
2. Click New Project.
3. Fill in:

• Project name: VeloPBX Integration (or any name your team will recognize)
• Organization: select your Google Workspace organization

1. Click Create.

Wait ~30 seconds for the project to provision, then select it from the project picker.

Step 2 — Enable the required APIs

Your new Cloud project doesn’t have any APIs enabled by default. Enable the four VeloPBX needs:

1. In the left navigation, click APIs & Services → Library.
2. Search for and Enable each of:

• Admin SDK API (for user directory sync)
• Gmail API (for sending email notifications via OAuth)
• People API (for personal contacts, if you want to sync them)
• Google Calendar API (for calendar-aware call routing, if you want it)

Each enable takes ~10 seconds. The page refreshes after each one.

Step 3 — Configure the OAuth consent screen

Before you can create OAuth credentials, Google requires you to publish a consent screen.

1. In APIs & Services, click OAuth consent screen.
2. Choose Internal user type — only users in your Workspace org will be able to authorize.
3. Click Create.
4. Fill in App information:

• App name: VeloPBX
• User support email: your IT contact email
• App logo: optional

1. App domain — leave defaults unless your IT/legal needs them populated.
2. Authorized domains: add the domain that hosts your VeloPBX FQDN (e.g. pbx.acme.com → add acme.com)
3. Developer contact email: your IT contact email
4. Click Save and Continue.

On the Scopes page:

• Click Add or Remove Scopes
• Search for and tick the following:
• https://www.googleapis.com/auth/admin.directory.user.readonly — read user directory
• https://www.googleapis.com/auth/gmail.send — send Gmail
• https://www.googleapis.com/auth/contacts.readonly — read personal contacts (if syncing)
• https://www.googleapis.com/auth/calendar.readonly — read calendar (if syncing)
• openid, email, profile — for SSO
• Click Update → Save and Continue.

Skip the Test users page (Internal apps don’t need them).

Click Back to Dashboard.

Step 4 — Create the OAuth Client ID

1. In APIs & Services, click Credentials.
2. Click + Create Credentials → OAuth client ID.
3. Application type: Web application.
4. Name: VeloPBX Integration
5. Authorized redirect URIs: click + Add URI and paste:

https://pbx.fortis-tele.com:8887/api/auth/callback/google

Replace https://pbx.fortis-tele.com:8887 with your actual VeloPBX admin URL.

Important: The URI must match exactly — protocol, host, port (:8887 for self-hosted), path. No trailing slash.

1. Click Create.

Google generates a Client ID and Client Secret. Copy both immediately to a secure location.

Important: Treat these as production credentials. The Client ID is technically public, but the Client Secret must stay secret. Anyone with both + the redirect URI can impersonate the integration.

Step 5 — Open the integration page in VeloPBX

In a new browser tab, sign into the VeloPBX Web Portal as a tenant administrator at:

https://pbx.fortis-tele.com:8887

In the left navigation, click Integrations, then Google Workspace.

Note: Google Workspace integration is available at both the System Admin level (email-only) and the Tenant level (full features including SSO and user sync). This guide covers the Tenant level. If you only see the System Admin variant, ask your VeloPBX system administrator to enable Workspace at the tenant level.

Step 6 — Paste credentials and complete authorization

1. Paste the Client ID and Client Secret from Step 4 into the corresponding fields.
2. Click Save. VeloPBX stores the credentials but the integration is not active yet.
3. Click the Complete the authorization hyperlink.
4. A new browser tab opens with Google’s sign-in screen.
5. Sign in with the Google account that should own the integration (typically a service account on your Workspace, not a personal admin).
6. Review the requested scopes on Google’s consent screen. They should match what you ticked in Step 3.
7. Click Allow.
8. Google redirects back to VeloPBX. The integration becomes active immediately.

Step 7 — Choose Sync Mode (permanent decision)

After authorization, VeloPBX displays the User Sync tab.

1. Click Sync Mode.
2. Select Manual or Automatic.

Reminder: This decision cannot be changed later. To switch sync modes you’d have to disconnect and re-authorize the entire integration.

For most tenants, choose Automatic.

Step 8 — Configure user sync

Click Save. If you chose Automatic, the first sync runs immediately. If Manual, click Sync now to trigger.

Step 9 — Configure SSO (optional but recommended)

1. In VeloPBX, click the Sign In tab.
2. Toggle Enable SSO On.
3. Choose how SSO applies:

• Sign in as Administrator — admins use Google SSO
• Sign in as Standard User — end users use Google SSO

1. Click Save.

After saving, a Google icon appears on the login pages of:

• The VeloPBX Web Portal
• The PortSIP ONE desktop and mobile apps

Users click the Google icon to sign in with their Workspace credentials.

Step 10 — (Optional) Enable Gmail email notifications

If you want VeloPBX to send voicemail alerts, password-reset emails, and other system notifications through your Workspace Gmail instead of through the default SMTP path:

1. Stay on Integrations → Google Workspace in VeloPBX.
2. Click the Email tab.
3. Toggle Use Gmail for outgoing notifications On.
4. Pick the sender — typically a Workspace mailbox like [email protected] (must exist as a real Gmail account in your Workspace).
5. Click Save.

VeloPBX now uses the OAuth token from Step 6 to send mail through Gmail. No SMTP password needed.

Why this matters: Google deprecated “Less Secure App” passwords in 2022. If your old SMTP setup used a Gmail app password, it has stopped working or will stop soon. OAuth-based Gmail sending is the only supported path.

Verify it works

1. User sync: open the Users & Extensions page in VeloPBX. New extensions should appear matching your Workspace user list.
2. SSO: sign out of VeloPBX. On the Web Portal sign-in page, click the Google icon. Sign in with your Google credentials. You should land back in the VeloPBX dashboard.
3. Gmail email: trigger a system email by, e.g., requesting a password reset for a synced user. Check the recipient inbox — the email should arrive from your configured Workspace mailbox (not from the PBX’s default SMTP).

Settings reference

Once connected, all settings can be edited any time on Integrations → Google Workspace at https://pbx.fortis-tele.com:8887.

Troubleshooting

“Error 400: redirect_uri_mismatch”

The Authorized Redirect URI in your Google Cloud OAuth client doesn’t match what VeloPBX sends. Common causes:

• Trailing slash mismatch (/callback/google/ vs /callback/google)
• HTTP vs HTTPS
• Wrong port
• Different host

Fix: edit APIs & Services → Credentials → your OAuth client → Authorized redirect URIs in Google Cloud and re-authorize.

“This app isn’t verified” warning

Internal-type OAuth apps don’t show this warning to users in your org. If you see it, you accidentally configured the consent screen as External in Step 3. Fix: change User Type to Internal under APIs & Services → OAuth consent screen → Edit App.

“Access blocked: VeloPBX has not completed Google verification”

Same root cause as above — External app type triggers Google’s verification flow which takes weeks. Switch to Internal user type and re-authorize.

Users aren’t syncing

• Confirm the Admin SDK API is enabled (Step 2). Without it, the user-list call returns 403.
• Confirm the user who authorized in Step 6 has Workspace admin privileges (or at minimum the User Management Admin role) — directory reads require it.
• Check your Sync Mode — if Manual, you must click Sync now explicitly.

“Sync Mode cannot be changed”

Confirmed Google Workspace behavior in PortSIP. Once set, the mode is permanent for the lifetime of this integration. To change: disconnect the integration in VeloPBX, then re-authorize from Step 6 (you’ll be prompted to pick Sync Mode again).

Gmail emails aren’t sending

• Confirm the Gmail API is enabled (Step 2).
• Confirm the email.sender_address is a real Gmail mailbox in your Workspace — not an alias, not a group address.
• Refresh tokens expire if the integration owner is deactivated. Re-authorize from a different active admin if needed.

SSL certificate errors during authorization

Google validates your redirect URI’s SSL certificate at every OAuth round-trip. Verify with:

curl -v https://your-pbx-host:8887/api/auth/callback/google 2>&1 | grep -i 'subject|issuer|expir'

The certificate must be issued by a public CA. Self-signed and private-CA certs will fail.

National-cloud / region issues

Unlike Microsoft 365 (which has a separate Azure China endpoint), Google Workspace is a single global service. There’s no national-cloud setting to misconfigure here.

FAQ

Do I need a specific Google Workspace tier? Business Starter and above all work. Business Starter does include the Admin SDK API needed for user sync. Free Gmail (@gmail.com) accounts are not Workspace and cannot be used as the integration owner.

Can multiple VeloPBX tenants connect to the same Workspace org? Yes — each VeloPBX tenant creates its own Google Cloud OAuth client (a separate project, ideally) with its own Client ID/Secret. Sync runs independently per VeloPBX tenant.

Does this integration support Google Voice? No — Google Voice is a separate Google product with its own API. This integration is for Workspace (Gmail / Calendar / Contacts / Directory). For Google Voice integration, contact us — we’ll flag the request for the PortSIP roadmap.

What permissions does VeloPBX request? The minimum for the configured features:

• admin.directory.user.readonly — read all Workspace users in the org
• gmail.send — send mail through the integration mailbox
• contacts.readonly — read users’ personal contacts (if syncing)
• calendar.readonly — read users’ calendars (if syncing)
• openid, email, profile — for SSO

What happens if 2FA is disabled on the integration owner? Google revokes OAuth tokens for accounts that drop below the org’s 2FA requirement. The integration breaks until 2FA is re-enabled or a different admin re-authorizes.

Can I rotate the Client Secret without losing data? Yes. Generate a new secret in Google Cloud Console (delete the old one), paste it into VeloPBX, click Save + Complete the authorization to refresh the OAuth token. Existing synced users and their extensions are not affected.

Need help?

If you get stuck (especially on Google Cloud project setup or OAuth consent screen configuration), talk to a routing engineer — we can pair on the Google Cloud flow live and have your first synced user running within 24 hours.