wiki/d-guides/google-oauth-setup.md

Google OAuth 2.0 Setup Guide for Porta

Overview

This guide explains how to set up Google OAuth 2.0 authentication for the Porta application.

Checkliste (Google Cloud + Gateway-Env): google-registration-checklist.md.

Prerequisites

• A Google account
• Access to Google Cloud Console (https://console.cloud.google.com/)

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click on the project dropdown at the top of the page
3. Click "New Project"
4. Enter a project name (e.g., "Porta OAuth")
5. Click "Create"

Step 2: Configure OAuth Consent Screen

1. In your new project, go to "APIs & Services" > "OAuth consent screen"
2. Configure the consent screen (Google+ API is deprecated, use Google Identity Services / OIDC)

Step 3: Create OAuth 2.0 Credentials

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth client ID"
3. If prompted, configure the OAuth consent screen first:
   • Choose "External" user type
   • Fill in the required fields (App name, User support email, Developer contact information)
   • Add scopes (see platform-core/modules/auth/oauthProviderConfig.py -- googleAuthScopes and googleDataScopes are the source of truth):
     • Auth app (login only):
       • openid
       • https://www.googleapis.com/auth/userinfo.profile
       • https://www.googleapis.com/auth/userinfo.email
     • Data app (UDB connectors -- Drive, Gmail, Calendar, Contacts):
       • everything from the Auth app, plus
       • https://www.googleapis.com/auth/gmail.readonly
       • https://www.googleapis.com/auth/drive.readonly
       • https://www.googleapis.com/auth/calendar.readonly
       • https://www.googleapis.com/auth/contacts.readonly
   • Enable the matching Google APIs under "APIs & Services > Library": Gmail API, Google Drive API, Google Calendar API, People API.
   • Add test users if needed
   • Click "Save and Continue" through all sections

Adding new scopes to an existing app? When you broaden the scope list (e.g. when Calendar/Contacts were rolled out on top of the original Drive + Gmail set), every existing UserConnection must go through the Reconnect action in the Connections page (/basedata/connections). The Reconnect button posts {"reauth": true} to the connect endpoint, which drops include_granted_scopes=true from the authorization URL so Google issues a token strictly for the current scope set. Without reconnecting the connection keeps working with the old scopes only -- the new services (Calendar, Contacts) silently return 403/empty.

4. Back to creating OAuth client ID:

   • Application type: "Web application"
   • Name: "Porta Web Client"
   • Authorized redirect URIs: Add two redirect URIs per environment:
     • Login callback: http://localhost:8000/api/google/auth/login/callback
     • Data connect callback: http://localhost:8000/api/google/auth/connect/callback
     • For production: replace localhost:8000 with your domain (HTTPS)

5. Click "Create"

6. Important: Copy the Client ID and Client Secret - you'll need these for the next step

Step 4: Configure Porta Application

1. Open your environment file (platform-core/env_dev.env for development)
2. Replace the placeholder values with your actual Google OAuth credentials:

# Google OAuth -- Auth App (Login)
Service_GOOGLE_AUTH_CLIENT_ID = your-auth-client-id
Service_GOOGLE_AUTH_CLIENT_SECRET = your-auth-client-secret
Service_GOOGLE_AUTH_REDIRECT_URI = http://localhost:8000/api/google/auth/login/callback

# Google OAuth -- Data App (SharePoint/Drive Connection)
Service_GOOGLE_DATA_CLIENT_ID = your-data-client-id
Service_GOOGLE_DATA_CLIENT_SECRET = your-data-client-secret
Service_GOOGLE_DATA_REDIRECT_URI = http://localhost:8000/api/google/auth/connect/callback

Hinweis: Das Gateway unterscheidet zwei OAuth-Apps: eine fuer Login (Auth) und eine fuer Daten-Connections (Data). Details: routeSecurityGoogle.py.

3. Save the file
4. Restart your Porta gateway server

Step 5: Test the Configuration

1. Start your Porta application
2. Go to the Connections module
3. Click "Connect Google"
4. You should be redirected to Google's OAuth consent screen
5. After authorization, you should be redirected back to Porta

Troubleshooting

Common Issues

1. "Missing required parameter: redirect_uri"

• Cause: Google OAuth client is not properly configured with the redirect URI
• Solution: Ensure the redirect URI in Google Cloud Console exactly matches your application's callback URL

2. "Invalid client" error

• Cause: Client ID or Client Secret is incorrect
• Solution: Double-check the credentials in your environment file

3. "Redirect URI mismatch" error

• Cause: The redirect URI in your OAuth request doesn't match what's configured in Google Cloud Console
• Solution: Ensure both URIs are identical (including protocol, domain, port, and path)

Debug Steps

1. Check the Porta gateway logs for OAuth configuration details
2. Verify environment variables are loaded correctly
3. Ensure the Google OAuth client is configured for "Web application" type
4. Check that the redirect URI includes the full path: /api/google/auth/callback

Security Notes

• Never commit your Google OAuth credentials to version control
• Use environment variables or secure configuration management
• Regularly rotate your client secrets
• Monitor OAuth usage in Google Cloud Console

Production Considerations

For production deployment:

1. Use HTTPS for all OAuth redirects
2. Configure proper domain verification in Google Cloud Console
3. Set up monitoring and alerting for OAuth usage
4. Consider implementing additional security measures like PKCE (Proof Key for Code Exchange)

Support

If you continue to experience issues:

1. Check the Porta gateway logs for detailed error messages
2. Verify your Google OAuth configuration in Google Cloud Console
3. Test with a simple OAuth flow to isolate the issue
4. Ensure your Google Cloud project has billing enabled (required for some APIs)