Skip to content

Google Workspace Setup

Jump to bottom
Serge Huijsen edited this page Dec 22, 2025 · 1 revision

Google Workspace / Gmail Email Integration Setup Guide

This guide walks you through setting up Google Workspace or Gmail email integration for FluxDesk. You'll need access to the Google Cloud Console to create OAuth credentials.

Prerequisites

  • A Google account (Gmail or Google Workspace)
  • Access to the Google Cloud Console (https://console.cloud.google.com)
  • For Google Workspace: Admin access may be required depending on your organization's policies

Step 1: Access Google Cloud Console

  1. Go to https://console.cloud.google.com
  2. Sign in with your Google account
  3. If you don't have a project yet, you'll be prompted to create one

Step 2: Create a New Project

  1. Click the project dropdown at the top of the page
  2. Click "New Project"
  3. Fill in the details:
Field Value
Project name FluxDesk (or your preferred name)
Organization Select your organization (if applicable)
Location Select a folder (if applicable)
  1. Click "Create"
  2. Wait for the project to be created, then select it

Step 3: Enable Required APIs

  1. In the left sidebar, navigate to "APIs & Services" → "Library"
  2. Search for and enable the following APIs:
API Purpose
Gmail API Read and send emails
Google People API Get user profile information

How to Enable an API:

  1. Search for the API name
  2. Click on the API card
  3. Click "Enable"
  4. Repeat for each required API

Step 4: Configure OAuth Consent Screen

  1. In the left sidebar, go to "APIs & Services" → "OAuth consent screen"
  2. Select the user type:
Type Description
Internal Only users in your Google Workspace organization (no verification needed)
External Any Google account (requires verification for production)
  1. Click "Create"

Fill in the App Information:

Field Value
App name FluxDesk
User support email Your email address
App logo (Optional) Upload your logo
App domain Your application domain
Developer contact email Your email address
  1. Click "Save and Continue"

Configure Scopes:

  1. Click "Add or Remove Scopes"
  2. Add the following scopes:
Scope Description
openid OpenID Connect
profile User profile information
email User email address
https://www.googleapis.com/auth/gmail.readonly Read emails
https://www.googleapis.com/auth/gmail.send Send emails
https://www.googleapis.com/auth/gmail.modify Modify emails (archive, move)
https://www.googleapis.com/auth/gmail.labels Manage labels
  1. Click "Update"
  2. Click "Save and Continue"

Add Test Users (for External apps in testing mode):

  1. Click "Add Users"
  2. Enter the email addresses of users who will test the integration
  3. Click "Save and Continue"

Step 5: Create OAuth 2.0 Credentials

  1. In the left sidebar, go to "APIs & Services" → "Credentials"
  2. Click "+ Create Credentials" → "OAuth client ID"
  3. Select "Web application" as the application type

Fill in the OAuth Client Details:

Field Value
Name FluxDesk Web Client
Authorized JavaScript origins https://your-domain.com
Authorized redirect URIs https://your-domain.com/organization/email-channels/oauth/callback/google

For Local Development, Also Add:

http://localhost:8000
http://localhost:8000/organization/email-channels/oauth/callback/google
  1. Click "Create"

Copy Your Credentials:

A dialog will appear with your credentials:

Value Description .env Variable
Client ID Ends with .apps.googleusercontent.com GOOGLE_CLIENT_ID
Client Secret A string like GOCSPX-xxxxx GOOGLE_CLIENT_SECRET

Important: Copy both values now! You can view the Client ID later, but the Client Secret can only be viewed once (though you can create a new one).

Step 6: Configure Your .env File

Add the following to your .env file:

# Google Workspace / Gmail OAuth Configuration
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=/organization/email-channels/oauth/callback/google

Step 7: Verify Configuration

Your final configuration should look like this:

GOOGLE_CLIENT_ID=123456789012-abcdefghijklmnopqrstuvwxyz123456.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
GOOGLE_REDIRECT_URI=/organization/email-channels/oauth/callback/google

Step 8: Test the Integration

  1. Go to your FluxDesk application
  2. Navigate to Organization Settings → E-mailaccounts
  3. Click "Account toevoegen" (Add Account)
  4. Enter a name for the email channel
  5. Select Google Workspace as the provider
  6. Click "Account toevoegen"
  7. You'll be redirected to Google's login page
  8. Sign in with your Google account
  9. Review and accept the permissions
  10. You'll be redirected back to FluxDesk
  11. Configure the email channel settings (folder, sync interval, etc.)

If successful, the email channel will show as "Actief" (Active) with your email address.

Publishing Your App (For Production)

For Internal (Google Workspace) Apps:

No additional steps needed. Your app is immediately available to users in your organization.

For External Apps:

External apps start in "Testing" mode with limitations:

  • Maximum 100 test users
  • Refresh tokens expire after 7 days
  • Users see a warning screen during OAuth

To publish for production:

  1. Go to "OAuth consent screen"
  2. Click "Publish App"
  3. Submit for verification

Verification Requirements:

  • Privacy policy URL
  • Terms of service URL (optional but recommended)
  • Justification for each sensitive scope
  • Domain verification

Verification can take several weeks. See Google's verification documentation for details.

Troubleshooting

"Access blocked: This app's request is invalid"

The redirect URI doesn't match exactly. Check:

  • Protocol (http vs https)
  • Domain name (no trailing slash)
  • Path must be exactly /organization/email-channels/oauth/callback/google
  • The redirect URI is added to both "Authorized redirect URIs" in the credential settings

"Error 403: access_denied - The developer hasn't given you access"

For External apps in testing mode:

  1. Go to OAuth consent screen → Test users
  2. Add the email address trying to authenticate
  3. Click "Save"

"This app isn't verified"

This warning appears for External apps that haven't completed Google's verification process. Users can click "Advanced" → "Go to FluxDesk (unsafe)" to proceed during testing.

"Token has been expired or revoked"

The refresh token has expired. This can happen because:

  1. External app in testing mode (tokens expire after 7 days)
  2. User revoked access in their Google account settings
  3. The OAuth credentials were regenerated

Solution: Users need to reconnect:

  1. Go to E-mailaccounts
  2. Click the menu (⋮) → "Opnieuw verbinden" (Reconnect)
  3. Re-authenticate with Google

Emails not syncing

  1. Check if the channel shows any error in "last_sync_error"
  2. Verify the Gmail account has emails in the selected label
  3. Check Laravel logs: storage/logs/laravel.log
  4. Manually trigger sync: php artisan email:sync --channel=1 --force
  5. Ensure the Gmail API is enabled in Google Cloud Console

"Request had insufficient authentication scopes"

The OAuth token doesn't have all required permissions. Users need to:

  1. Disconnect the email channel
  2. Delete and recreate the channel
  3. Re-authenticate to grant all scopes

Gmail vs Google Workspace

Feature Gmail (Personal) Google Workspace
OAuth consent screen External Internal or External
Verification required Yes (for production) No (for Internal)
User limit in testing 100 users Unlimited (Internal)
Token expiration 7 days (testing) No expiration
Admin consent N/A May be required

Recommendation: If you're deploying for a single organization, use Google Workspace with an Internal app for the simplest setup.

Security Best Practices

  1. Keep credentials secure - Never commit .env files to version control
  2. Use HTTPS - Always use HTTPS in production for redirect URIs
  3. Limit test users - Only add necessary users during testing phase
  4. Complete verification - For External apps, complete Google's verification process
  5. Monitor usage - Check the Google Cloud Console for API usage and errors
  6. Rotate credentials - Periodically create new client secrets

API Reference

Google API Endpoints Used

Endpoint Purpose
https://accounts.google.com/o/oauth2/v2/auth OAuth authorization
https://oauth2.googleapis.com/token Token exchange/refresh
https://www.googleapis.com/oauth2/v2/userinfo Get user profile
https://gmail.googleapis.com/gmail/v1/users/me/messages List/read emails
https://gmail.googleapis.com/gmail/v1/users/me/messages/send Send emails
https://gmail.googleapis.com/gmail/v1/users/me/labels List labels

OAuth Scopes Configured

// config/services.php
'scopes' => [
    'openid',
    'profile',
    'email',
    'https://www.googleapis.com/auth/gmail.readonly',
    'https://www.googleapis.com/auth/gmail.send',
    'https://www.googleapis.com/auth/gmail.modify',
    'https://www.googleapis.com/auth/gmail.labels',
],

Key Differences from Microsoft 365

Feature Google Microsoft 365
Folders Labels (can apply multiple) Folders (exclusive)
Thread ID threadId conversationId
Archive Remove INBOX label Move to Archive folder
Message format Base64URL RFC 2822 Structured JSON
Move behavior Message ID unchanged Message ID changes
Admin portal Google Cloud Console Azure Portal

Additional Resources

Support

If you encounter issues not covered in this guide:

  1. Check the Laravel logs at storage/logs/laravel.log
  2. Review API usage in the Google Cloud Console
  3. Test the connection using the "Test verbinding" button in the UI
  4. Check the Gmail API dashboard for errors

Getting Started

Email Integration

Configuration

Clone this wiki locally