165 lines
7.1 KiB
Markdown
165 lines
7.1 KiB
Markdown
# Gmail Integration Setup Guide
|
|
|
|
This guide explains how to set up Gmail integration so that **every vendor can connect their own Gmail account** to receive and send customer emails.
|
|
|
|
## How It Works
|
|
|
|
- **One OAuth App**: You create ONE Google OAuth application in Google Cloud Console
|
|
- **Shared Credentials**: All vendors use the same `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`
|
|
- **Individual Authorization**: Each vendor authorizes their own Gmail account when connecting
|
|
- **Separate Tokens**: Each vendor's Gmail tokens are stored separately in the database
|
|
|
|
## Login Method vs Gmail Integration
|
|
|
|
**IMPORTANT**: These are TWO separate things:
|
|
|
|
1. **Login Method** (How vendor logs into YOUR app):
|
|
- Email/Password login ✅
|
|
- Google OAuth login ✅
|
|
- Both work independently
|
|
|
|
2. **Gmail Integration** (Authorizing Gmail API access):
|
|
- Separate OAuth flow
|
|
- Works regardless of login method
|
|
- Vendor can connect ANY Gmail account (doesn't need to match login email)
|
|
|
|
### Example Scenarios:
|
|
|
|
**Scenario 1**: Vendor logs in with email/password (`talatfaheem2@gmail.com`)
|
|
- ✅ Can connect Gmail integration
|
|
- When clicking "Connect Gmail", they'll be redirected to Google OAuth
|
|
- Can authorize the same Gmail (`talatfaheem2@gmail.com`) OR a different one (`business@gmail.com`)
|
|
|
|
**Scenario 2**: Vendor logs in with Google OAuth (`talatfaheem2@gmail.com`)
|
|
- ✅ Can connect Gmail integration
|
|
- When clicking "Connect Gmail", they'll be redirected to Google OAuth again
|
|
- Can authorize the same Gmail (`talatfaheem2@gmail.com`) OR a different one (`business@gmail.com`)
|
|
|
|
**Key Point**: The Gmail account they authorize doesn't need to match their login email!
|
|
|
|
## Step-by-Step Setup
|
|
|
|
### 1. Create Google Cloud Project (One Time Setup)
|
|
|
|
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
|
|
2. Create a new project (or select existing)
|
|
3. Enable **Gmail API**:
|
|
- Go to [APIs & Services > Library](https://console.cloud.google.com/apis/library)
|
|
- Search for "Gmail API"
|
|
- Click "Enable"
|
|
|
|
### 2. Create OAuth 2.0 Credentials
|
|
|
|
1. Go to [APIs & Services > Credentials](https://console.cloud.google.com/apis/credentials)
|
|
2. Click "Create Credentials" > "OAuth client ID"
|
|
3. **If prompted**, configure OAuth consent screen (Google will prompt you the first time):
|
|
- Choose "External" (unless you have Google Workspace)
|
|
- Fill in app name, support email, developer contact
|
|
- **Note**: You don't need to manually add scopes here - they're automatically requested when vendors connect
|
|
- **IMPORTANT**: Add test users - Add ALL Gmail addresses that will connect (e.g., `krypttech4@gmail.com`, `talatfaheem2@gmail.com`, etc.)
|
|
- Click "Save and Continue" through the steps
|
|
|
|
**OR if consent screen is already configured:**
|
|
- Go to [APIs & Services > OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent)
|
|
- Scroll down to "Test users" section
|
|
- Click "+ ADD USERS"
|
|
- Add the Gmail addresses that will connect (one per line or comma-separated)
|
|
- Click "Add"
|
|
4. Create OAuth client:
|
|
- Application type: "Web application"
|
|
- Name: "JunoHub Gmail Integration" (or your choice)
|
|
- **Authorized redirect URIs** (CRITICAL - must match exactly):
|
|
```
|
|
http://localhost:3000/api/integrations/gmail/callback
|
|
https://your-production-domain.com/api/integrations/gmail/callback
|
|
```
|
|
- If using ngrok: `https://your-ngrok-url.ngrok-free.dev/api/integrations/gmail/callback`
|
|
- **Important**: Add ALL environments you'll use (dev, staging, production, ngrok URLs)
|
|
|
|
### 3. Configure Environment Variables
|
|
|
|
Add to your `.env` file:
|
|
|
|
```env
|
|
# Your Google Cloud OAuth credentials (shared for all vendors)
|
|
GOOGLE_CLIENT_ID="your-client-id-here.apps.googleusercontent.com"
|
|
GOOGLE_CLIENT_SECRET="your-client-secret-here"
|
|
|
|
# Your app URL (used for OAuth redirects)
|
|
NEXTAUTH_URL="http://localhost:3000" # or your production URL
|
|
```
|
|
|
|
### 4. Test the Integration
|
|
|
|
1. Start your application
|
|
2. Log in as a vendor
|
|
3. Go to Juno Engine > Gmail Connect
|
|
4. Click "Connect Gmail Account"
|
|
5. Sign in with **any Gmail account** (doesn't need to match the OAuth app owner)
|
|
6. Authorize the requested permissions
|
|
7. You should be redirected back and see "Gmail Connected"
|
|
|
|
## Troubleshooting
|
|
|
|
### Error: `redirect_uri_mismatch`
|
|
|
|
**Problem**: The redirect URI in your code doesn't match what's configured in Google Cloud Console.
|
|
|
|
**Solution**:
|
|
1. Check the error message - it will show the redirect URI being used
|
|
2. Go to Google Cloud Console > Credentials > Your OAuth Client
|
|
3. Add the exact redirect URI shown in the error to "Authorized redirect URIs"
|
|
4. Wait a few minutes for changes to propagate
|
|
5. Try again
|
|
|
|
### Error: `invalid_client`
|
|
|
|
**Problem**: The `GOOGLE_CLIENT_ID` or `GOOGLE_CLIENT_SECRET` is incorrect.
|
|
|
|
**Solution**:
|
|
1. Double-check your `.env` file
|
|
2. Make sure there are no extra spaces or quotes
|
|
3. Restart your application after changing `.env`
|
|
|
|
### Error: `access_denied` or "Access blocked: has not completed the Google verification process"
|
|
|
|
**Problem**: The OAuth app is in "Testing" mode and the user's Gmail address is not added as a test user.
|
|
|
|
**Solution**:
|
|
1. Go to [APIs & Services > OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent)
|
|
2. Scroll down to "Test users" section
|
|
3. Click "+ ADD USERS"
|
|
4. Add the Gmail address that's trying to connect (e.g., `krypttech4@gmail.com`)
|
|
5. Click "Add"
|
|
6. Wait a few minutes for changes to propagate
|
|
7. Try connecting again
|
|
|
|
**Note**: In testing mode, you must add each Gmail address as a test user. For production, you'll need to publish your app (requires Google verification).
|
|
|
|
## Important Notes
|
|
|
|
- **OAuth Consent Screen**: Google will prompt you to configure this the FIRST time you create OAuth credentials. After that, you can skip it. The scopes are automatically requested in the OAuth flow - you don't need to manually add them in the consent screen.
|
|
- **OAuth App Owner**: The email that created the OAuth app (`i221735@nu.edu.pk`) doesn't matter. Any Gmail account can authorize access.
|
|
- **Vendor Gmail**: Each vendor connects their own Gmail account (`talatfaheem2@gmail.com`, etc.). They don't need their own OAuth credentials.
|
|
- **Redirect URI**: Must match EXACTLY (including protocol, domain, port, path). No trailing slashes.
|
|
- **Multiple Environments**: Add redirect URIs for all environments (localhost, staging, production, ngrok).
|
|
|
|
## Security Considerations
|
|
|
|
- OAuth tokens are stored securely in the database
|
|
- Each vendor's tokens are isolated (can't access each other's emails)
|
|
- Tokens are automatically refreshed when expired
|
|
- Vendors can disconnect their Gmail at any time
|
|
|
|
## Production Checklist
|
|
|
|
- [ ] Gmail API enabled in Google Cloud Console
|
|
- [ ] OAuth consent screen configured
|
|
- [ ] **Test users added** (for testing mode) - Add all Gmail addresses that will connect
|
|
- [ ] OAuth client created with correct redirect URIs
|
|
- [ ] Environment variables set (`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `NEXTAUTH_URL`)
|
|
- [ ] Database migration run (`prisma db push`)
|
|
- [ ] Tested with at least one vendor account
|
|
- [ ] Production redirect URI added to Google Cloud Console
|
|
- [ ] **For production**: Publish your app (requires Google verification) OR keep adding test users as needed
|