From 5233b71703c52a94e32d9144ee347e2c02b1c074 Mon Sep 17 00:00:00 2001
From: ValueOn AG <p.motsch@valueon.ch>
Date: Mon, 18 Aug 2025 21:28:37 +0200
Subject: [PATCH] doc upd

---
 poweron/GOOGLE_OAUTH_SETUP.md | 114 ++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 poweron/GOOGLE_OAUTH_SETUP.md

diff --git a/poweron/GOOGLE_OAUTH_SETUP.md b/poweron/GOOGLE_OAUTH_SETUP.md
new file mode 100644
index 0000000..85d4500
--- /dev/null
+++ b/poweron/GOOGLE_OAUTH_SETUP.md
@@ -0,0 +1,114 @@
+# 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](https://console.cloud.google.com/)
+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:
+
+```env
+# 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)