Google OAuth Setup Guide for Kemma

This guide explains how to configure Google OAuth for the Kemma mindmap application.

---

Part 1: OAuth Fundamentals

What is OAuth 2.0?

OAuth 2.0 is an authorization framework that allows applications to access user data without exposing passwords. Instead of sharing credentials, users grant limited access via tokens.

Key Concepts

Term	Description
Client ID	Public identifier for your app registered with Google
ID Token	JWT containing user info (email, name, picture)
JWT	JSON Web Token - encoded payload signed by Google
Consent Screen	Google UI where users approve access

How Kemma Uses OAuth

Kemma uses Google Identity Services (the "Sign in with Google" button) which returns an ID Token. This token contains user profile information encoded as a JWT:

{
  "email": "user@gmail.com",
  "name": "John Doe",
  "picture": "https://...",
  "sub": "unique-google-user-id"
}

Kemma decodes this token client-side and stores it in localStorage for session persistence.

---

Part 2: Google Cloud Console Setup

Step 1: Create a Project

1. Go to Google Cloud Console
2. Click Select a project → New Project
3. Name it (e.g., "Kemma Local Dev") and create

Step 2: Configure OAuth Consent Screen

1. Navigate to APIs & Services → OAuth consent screen
2. Select External (allows any Google account)
3. Fill in:
   • App name: Kemma
   • User support email: Your email
   • Developer contact: Your email
4. Click Save and Continue through remaining steps
5. Add yourself as a test user (required for external apps in testing mode)

Step 3: Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Select Web application
4. Configure:
   • Name: Kemma Web Client
   • Authorized JavaScript origins:
     • http://localhost:5173 (Vite dev server)
   • Authorized redirect URIs:
     • http://localhost:5173 (for implicit flow)
5. Click Create
6. Copy the Client ID - you'll need this

Step 4: Configure Environment

Create .env.local in apps/web-client/:

VITE_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com

IMPORTANT

Never commit .env.local to git. It's already in .gitignore.

---

Part 3: Verification

Test the Sign-In Flow

1. Start the dev server:

   cd apps/web-client && npm run dev

2. Navigate to http://localhost:5173

3. Click Get Started → Should redirect to /login

4. Click Sign in with Google

5. Select your test user account

6. You should be redirected to /home with your session active

Verify Token Storage

Open browser DevTools → Application → Local Storage:

Key	Value
google_token	eyJhbGciOiJSUzI1NiIsInR5cCI... (JWT)

---

Part 4: Production Considerations

WARNING

This implementation stores the Google ID token in localStorage. For production, consider:

Security Improvements

1. Token validation: Verify JWT signature server-side
2. Session management: Use HTTP-only cookies instead of localStorage
3. Token refresh: ID tokens expire after 1 hour
4. Backend integration: Send token to your API for server-side validation

Publishing the App

To allow any Google user (not just test users):

1. Go to OAuth consent screen
2. Click Publish App
3. Complete Google's verification process (required for "Sign in with Google")

---

Troubleshooting

Issue	Solution
"Sign in with Google" button missing	Check VITE_GOOGLE_CLIENT_ID is set and not empty
"Error 400: redirect_uri_mismatch"	Add http://localhost:5173 to Authorized JavaScript origins
Sign-in popup blocked	Browser blocking popups - check popup blocker settings
"Access blocked: This app has not been verified"	Add yourself as test user in OAuth consent screen