gateway/GOOGLE_OAUTH_SETUP.md

Google OAuth 2.0 Setup Guide for PowerOn

Overview

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

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., "PowerOn OAuth")
5. Click "Create"

Step 2: Enable Google+ API

1. In your new project, go to "APIs & Services" > "Library"
2. Search for "Google+ API" or "Google Identity"
3. Click on "Google+ API" and click "Enable"

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: https://www.googleapis.com/auth/userinfo.profile, https://www.googleapis.com/auth/userinfo.email
   • Add test users if needed
   • Click "Save and Continue" through all sections

4. Back to creating OAuth client ID:

   • Application type: "Web application"
   • Name: "PowerOn Web Client"
   • Authorized redirect URIs: Add your redirect URI
     • For development: http://localhost:8000/api/google/auth/callback
     • For production: https://yourdomain.com/api/google/auth/callback

5. Click "Create"

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

Step 4: Configure PowerOn Application

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

# Google OAuth Configuration
Service_GOOGLE_CLIENT_ID = your-actual-client-id-from-google-console
Service_GOOGLE_CLIENT_SECRET = your-actual-client-secret-from-google-console
Service_GOOGLE_REDIRECT_URI = http://localhost:8000/api/google/auth/callback

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

Step 5: Test the Configuration

1. Start your PowerOn 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 PowerOn

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 PowerOn 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 PowerOn 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)