143 lines
6 KiB
Markdown
143 lines
6 KiB
Markdown
# 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.
|
|
|
|
## 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., "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 `gateway/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 (`gateway/env_dev.env` for development)
|
|
2. Replace the placeholder values with your actual Google OAuth credentials:
|
|
|
|
```env
|
|
# 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)
|