🔐 Implementation Guide

🔧 Problem This Solves

Vercel preview deployments have dynamic URLs (e.g., my-app-git-feature-username.vercel.app) but OAuth providers require static redirect URIs. This proxy acts as a bridge.

🔄 How It Works

1. Your preview app redirects user to: https://oauth.agens.io/start/google?target=https://my-app-git-feature-me.vercel.app
2. Proxy redirects to Google OAuth with static callback URL: https://oauth.agens.io/callback/google
3. Google returns authorization code to proxy
4. Proxy forwards code back to your original preview app: https://my-app-git-feature-me.vercel.app/api/auth/callback/google

💻 Client-Side Implementation

JavaScript/TypeScript:


      // Redirect to OAuth proxy instead of direct OAuth
      const targetUrl = encodeURIComponent(window.location.origin);
      window.location.href = "https://oauth.agens.io/start/google?target=" + targetUrl;

⚙️ OAuth App Configuration

Google OAuth App (console.cloud.google.com)

Authorized redirect URI:
https://oauth.agens.io/callback/google

GitHub OAuth App (github.com/settings/developers)

Authorization callback URL:
https://oauth.agens.io/callback/github

🔧 Server-Side Callback Handler

Your app needs an endpoint at /api/auth/callback/:provider that:

Receives code and state query parameters
Exchanges code for access token with OAuth provider
Creates user session and redirects to app

🚀 Next.js + NextAuth.js Integration

1. Configure providers normally:

// pages/api/auth/[...nextauth].js or app/api/auth/[...nextauth]/route.js
import GoogleProvider from "next-auth/providers/google"

export const authOptions = {
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    })
  ]
}

2. Use proxy for sign-in redirect:

// Instead of: signIn('google')
// Use:
const targetUrl = encodeURIComponent(window.location.origin);
window.location.href = "https://oauth.agens.io/start/google?target=" + targetUrl;

🔒 Environment Variables

Required:

PUBLIC_URL=https://oauth.agens.io
ALLOWED_HOSTS=^https://.*\.vercel\.app$
GOOGLE_CLIENT_ID=your_google_client_id
GITHUB_CLIENT_ID=your_github_client_id

Optional:

RATE_LIMIT_MAX=10 (requests per window)
RATE_LIMIT_WINDOW_MINUTES=15 (window duration in minutes)

📋 Complete Implementation Checklist

✅ Setup Steps:
1. Configure OAuth apps with proxy callback URLs
2. Update client-side login to redirect to proxy
3. Ensure your app has /api/auth/callback/:provider endpoint
4. Test with preview deployments

⚠️ Common Issues:
• Forgot to add proxy URLs to OAuth app settings
• Target URL not matching ALLOWED_HOSTS pattern
• Missing callback handler in your app

🔐 Security Note: Only domains matching the ALLOWED_HOSTS environment variable can use this proxy. Configure this carefully to prevent unauthorized access.