Skip to content

SETUP_GMAIL_API.md

Latest commit

 

History

History
163 lines (125 loc) · 5.19 KB

SETUP_GMAIL_API.md

File metadata and controls

163 lines (125 loc) · 5.19 KB

Gmail API Setup Guide for PhishGuard

Overview

PhishGuard requires Gmail API credentials to access and analyze your emails. Follow these steps to set up the Gmail API and generate the required Gmail_Credentials.json file.

Step 1: Create a Google Cloud Project

  1. Go to Google Cloud Console
  2. Click on the project dropdown at the top
  3. Click "NEW PROJECT"
  4. Enter a project name (e.g., "PhishGuard")
  5. Click "CREATE"
  6. Wait for the project to be created and make sure it's selected

Step 2: Enable Gmail API

  1. In the Google Cloud Console, go to APIs & Services > Library
  2. Search for "Gmail API"
  3. Click on Gmail API from the results
  4. Click "ENABLE"
  5. Wait for the API to be enabled

Step 3: Configure OAuth Consent Screen

  1. Go to APIs & Services > OAuth consent screen
  2. Select "External" user type
  3. Click "CREATE"
  4. Fill in the required fields:
    • App name: PhishGuard (or any name you prefer)
    • User support email: Your email address
    • Developer contact information: Your email address
  5. Click "SAVE AND CONTINUE"
  6. On the Scopes page, click "ADD OR REMOVE SCOPES"
    • Search for and add: https://www.googleapis.com/auth/gmail.readonly
    • This allows read-only access to your Gmail
  7. Click "UPDATE" and then "SAVE AND CONTINUE"
  8. On the Test users page, click "ADD USERS"
    • Add your Gmail address that you want to scan
  9. Click "SAVE AND CONTINUE"
  10. Review the summary and click "BACK TO DASHBOARD"

Step 4: Create OAuth 2.0 Credentials

  1. Go to APIs & Services > Credentials
  2. Click "+ CREATE CREDENTIALS" at the top
  3. Select "OAuth client ID"
  4. Choose Application type: Desktop app
  5. Enter a name: PhishGuard Desktop Client
  6. Click "CREATE"
  7. A dialog will appear with your credentials
  8. Click "DOWNLOAD JSON"
  9. Save the downloaded file

Step 5: Rename and Place the Credentials File

  1. Locate the downloaded JSON file (usually in your Downloads folder)
    • It will have a name like: client_secret_XXXXX.apps.googleusercontent.com.json
  2. Rename this file to: Gmail_Credentials.json
  3. Move it to your PhishGuard project root folder: 
    c:\Users\Sanjay\Downloads\PhishGuard-main\PhishGuard-main\Gmail_Credentials.json

Step 6: Run PhishGuard

  1. Make sure you're in the project directory and the virtual environment is activated
  2. Run the Streamlit app: 
    .\.venv\Scripts\streamlit run app.py
  3. Click the "Fetch & Scan Emails" button in the sidebar
  4. A browser window will open asking you to authorize the app
  5. Select your Google account
  6. You may see a warning "Google hasn't verified this app" - this is normal for development
    • Click "Advanced"
    • Click "Go to PhishGuard (unsafe)"
  7. Review the permissions and click "Continue"
  8. The authorization is complete! The app will now fetch your emails

Troubleshooting

Error: "Access blocked: This app's request is invalid"

  • Make sure you added your email as a test user in the OAuth consent screen (Step 3.8)

Error: "The OAuth client was not found"

  • Make sure you downloaded the correct credentials file
  • Verify the file is named exactly Gmail_Credentials.json

Error: "redirect_uri_mismatch"

  • Make sure you selected "Desktop app" as the application type
  • The app uses http://localhost:8080/ as the redirect URI

Authentication window doesn't open

  • Check if a browser window opened in the background
  • Look for a URL in the terminal output that you can manually visit

Security Notes

  1. Keep Gmail_Credentials.json private - Never commit it to Git or share it publicly
  2. Token storage - After first authentication, a token.pickle file is created to store your access token
  3. Read-only access - The app only has permission to read emails, not send or delete
  4. Revoke access - You can revoke access anytime at https://myaccount.google.com/permissions

File Structure After Setup

Your project should look like this:

PhishGuard-main/
├── app.py
├── gmail_client.py
├── main.py
├── parser_heuristics.py
├── pyproject.toml
├── README.md
├── SETUP_GMAIL_API.md
├── Gmail_Credentials.json  ← Your credentials file (don't commit!)
└── token.pickle             ← Created after first auth (don't commit!)

Quick Reference - Commands

# Activate virtual environment
. .\.venv\Scripts\Activate.ps1

# Run the app
streamlit run app.py

# Or use the venv directly
.\.venv\Scripts\streamlit run app.py

Need Help? If you encounter any issues, make sure:

  1. Gmail API is enabled in your Google Cloud project
  2. OAuth consent screen is configured with your email as a test user
  3. Credentials are downloaded as Desktop app type
  4. The file is named exactly Gmail_Credentials.json (case-sensitive)
  5. The file is in the project root directory
⚡