Google OAuth

Google OAuth Setup

Google OAuth is the most popular authentication method for web applications. This guide walks you through setting up Google OAuth with @warpy-auth-sdk/core.

Google Cloud Console Setup

Before you can use Google OAuth, you need to set up a project in Google Cloud Console:

Step 1: Create a Google Cloud Project

1. Go to the Google Cloud Console
2. Click "Select a project" → "New Project"
3. Enter a project name (e.g., "My Auth App")
4. Click "Create"

Step 2: Enable Required APIs

1. In your project, go to "APIs & Services" → "Library"
2. Enable "People API" (and any other APIs you need)

Step 3: Create OAuth 2.0 Credentials

1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "OAuth 2.0 Client IDs"
3. If prompted, configure the OAuth consent screen:
   • Choose "External" for public apps
   • Fill in the required fields (App name, User support email, Developer contact)
   • Add your domain to authorized domains
4. Select "Web application" as the application type
5. Add authorized redirect URIs:
   • Development: http://localhost:3000/api/auth/callback/google
   • Production: https://yourdomain.com/api/auth/callback/google
6. Click "Create"
7. Copy the Client ID and Client Secret

Environment Variables

Add the Google OAuth credentials to your environment variables:

# .env.local
AUTH_SECRET=your-secret-key-min-32-chars-long
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/api/auth/callback/google

Using Google OAuth Provider

Import and configure the Google OAuth provider:

import { google } from '@warpy-auth-sdk/core';

const googleProvider = google({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  redirectUri: process.env.GOOGLE_REDIRECT_URI!,
});

Advanced Configuration

Google OAuth provider supports additional configuration options. PKCE (S256) is enabled by default.

import { google } from '@warpy-auth-sdk/core';

const googleProvider = google({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  redirectUri: process.env.GOOGLE_REDIRECT_URI!,
  scope: [
    'openid',
    'email', 
    'profile',
    'https://www.googleapis.com/auth/userinfo.email',
    'https://www.googleapis.com/auth/userinfo.profile'
  ],
});

Google OAuth Scopes

Google OAuth supports various scopes for different permissions:

Basic Scopes

• openid - OpenID Connect authentication
• email - Access to user's email address
• profile - Access to user's basic profile information

Extended Scopes

• https://www.googleapis.com/auth/userinfo.email - Detailed email access
• https://www.googleapis.com/auth/userinfo.profile - Detailed profile access
• https://www.googleapis.com/auth/calendar - Google Calendar access
• https://www.googleapis.com/auth/drive - Google Drive access

User Data Structure

Google OAuth returns user data in this format:

interface GoogleUser {
  id: string;           // Google user ID
  email: string;        // User's email address
  name: string;         // User's full name
  picture: string;      // User's profile picture URL
  verified_email: boolean; // Email verification status
  locale: string;       // User's locale
}

Complete Implementation

Here's a complete example of Google OAuth integration:

import { authMiddleware } from '@warpy-auth-sdk/core/next';
import { google } from '@warpy-auth-sdk/core';

const handler = authMiddleware(
  {
    secret: process.env.AUTH_SECRET!,
    provider: google({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      redirectUri: process.env.GOOGLE_REDIRECT_URI!,
      scope: ['openid', 'email', 'profile'],
    }),
    callbacks: {
      async user(u) {
        // Save user to your database
        // Return the user object that will be stored in the session
        return {
          id: u.id,
          email: u.email,
          name: u.name,
          picture: u.picture,
        };
      },
      jwt: (token) => {
        // Add any custom claims to the JWT
        return token;
      },
      session: (session) => {
        // Customize the session object
        return session;
      },
    },
  },
  {
    basePath: '/api/auth',
    successRedirect: '/dashboard',
    errorRedirect: '/login',
  }
);

export function proxy(request: NextRequest) {
  const p = request.nextUrl.pathname;
  if (p.startsWith('/api/auth')) return handler(request);
  return NextResponse.next();
}

Testing Google OAuth

Test your Google OAuth integration:

1. Start your development server: npm run dev
2. Visit http://localhost:3000/api/auth/signin/google
3. Complete the Google OAuth flow
4. Verify you're redirected to your success page
5. Check that user data is correctly stored in the session

Common Issues

Here are solutions to common Google OAuth issues:

Redirect URI Mismatch

Error: "redirect_uri_mismatch"
Solution: Ensure the redirect URI in your Google Cloud Console exactly matches the one in your environment variables.

Invalid Client

Error: "invalid_client"
Solution: Check that your Client ID and Client Secret are correct and not expired.

Access Blocked

Error: "access_denied"
Solution: Make sure your OAuth consent screen is properly configured and published.

Production Deployment

For production deployment:

1. Create a separate OAuth application for production
2. Add your production domain to authorized domains
3. Update redirect URIs to use HTTPS
4. Set production environment variables
5. Test the OAuth flow in production

Next Steps

Now that you have Google OAuth working, you can:

• Add Email Magic Links for passwordless authentication
• Implement Database Adapters for session persistence
• Add Security Best Practices for production