AUTHENTICATION

Authentication Setup Guide

This guide explains how to configure authentication for Supen, including OAuth providers and Cloudflare Turnstile bot protection.

Features

• ✅ Email/Password authentication
• ✅ OAuth providers (Google, GitHub, Microsoft)
• ✅ Cloudflare Turnstile bot protection
• ✅ Modern, clean UI matching Manus design
• ✅ Secure JWT-based authentication with Supabase

Quick Start

1. Email/Password Authentication

Email/password authentication works out of the box with Supabase. No additional configuration needed.

2. OAuth Providers Setup

Enable OAuth in Supabase Dashboard

1. Go to your Supabase project dashboard
2. Navigate to Authentication → Providers
3. Enable the providers you want to use:

Google OAuth

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable Google+ API
4. Go to Credentials → Create Credentials → OAuth 2.0 Client ID
5. Add authorized redirect URI:

   https://your-project-ref.supabase.co/auth/v1/callback

6. Copy Client ID and Client Secret
7. In Supabase dashboard, paste them into Google provider settings

GitHub OAuth

1. Go to GitHub Developer Settings
2. Click New OAuth App
3. Fill in:
   • Application name: Supen
   • Homepage URL: https://yourdomain.com
   • Authorization callback URL: https://your-project-ref.supabase.co/auth/v1/callback
4. Copy Client ID and generate a Client Secret
5. In Supabase dashboard, paste them into GitHub provider settings

Microsoft OAuth

1. Go to Azure Portal
2. Navigate to Azure Active Directory → App registrations
3. Click New registration
4. Add redirect URI:

   https://your-project-ref.supabase.co/auth/v1/callback

5. Go to Certificates & secrets → Create a new client secret
6. Copy Application (client) ID and the secret value
7. In Supabase dashboard, paste them into Microsoft provider settings

3. Cloudflare Turnstile Setup (Optional)

Cloudflare Turnstile provides bot protection for login and registration forms.

1. Go to Cloudflare Dashboard
2. Navigate to Turnstile
3. Click Add Site
4. Configure:
   • Site name: Supen
   • Domain: Your domain (e.g., yourdomain.com)
   • Widget mode: Managed (recommended)
5. Copy both keys:
   • Site Key (public) - Used to render the widget in the browser
   • Secret Key (private) - Used to verify tokens on the server
6. Add to your .env.local:

   NEXT_PUBLIC_TURNSTILE_SITE_KEY=your_site_key_here
   TURNSTILE_SECRET_KEY=your_secret_key_here

Important Notes:

• NEXT_PUBLIC_TURNSTILE_SITE_KEY is public and sent to the client
• TURNSTILE_SECRET_KEY is private and must stay on the server
• If you don’t set these keys, authentication will work without bot protection
• Server-side verification happens automatically via server actions

4. Environment Variables

Update your .env.local file:

# Supabase (Required)
NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key_here

# Cloudflare Turnstile (Optional)
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your_site_key_here  # Public key
TURNSTILE_SECRET_KEY=your_secret_key_here          # Private key

5. Configure Redirect URLs

In your Supabase project settings (Authentication → URL Configuration):

1. Add your site URL:

   https://yourdomain.com

2. Add redirect URLs:

   https://yourdomain.com/auth/callback
   http://localhost:3333/auth/callback  (for development)

Usage

Login Page

Users can:

• Sign in with Google, GitHub, or Microsoft (one click)
• Sign in with email and password
• Protected by Cloudflare Turnstile (if configured)

Route: /[locale]/login (e.g., /en/login, /zh/login)

Register Page

Users can:

• Sign up with Google, GitHub, or Microsoft (one click)
• Sign up with email and password
• Password confirmation validation
• Protected by Cloudflare Turnstile (if configured)

Route: /[locale]/register

OAuth Callback

The OAuth callback handler is at /[locale]/auth/callback and automatically:

• Exchanges the OAuth code for a session
• Redirects to the intended page
• Shows error messages if authentication fails

Security Features

1. JWT Validation

• Uses getClaims() instead of deprecated getUser() for secure authentication
• Prevents CVE-2025-29927 vulnerability (x-middleware-subrequest header bypass)
• Validates JWT signature against Supabase’s published public keys

2. Bot Protection

• Cloudflare Turnstile provides invisible CAPTCHA
• Only activates when suspicious activity is detected
• User-friendly and accessible

3. Row Level Security (RLS)

• All database tables have RLS policies
• Users can only access their own data
• Enforced at the database level

Development

Testing OAuth Locally

1. Update OAuth app redirect URLs to include:

   http://localhost:3333/auth/callback

2. Start the dev server:

   pnpm dev

3. Visit http://localhost:3333/en/login

Testing Without Turnstile

Simply don’t set NEXT_PUBLIC_TURNSTILE_SITE_KEY in your environment. The widget will not render and users can authenticate without CAPTCHA.

Troubleshooting

OAuth Redirect Mismatch

Error: “redirect_uri_mismatch”

Solution: Ensure the redirect URI in your OAuth provider settings exactly matches:

https://your-project-ref.supabase.co/auth/v1/callback

Turnstile Not Showing

Issue: Turnstile widget doesn’t appear

Possible causes:

1. NEXT_PUBLIC_TURNSTILE_SITE_KEY is not set (this is expected)
2. Domain doesn’t match the one configured in Cloudflare
3. Check browser console for errors

Session Not Persisting

Issue: User gets logged out on page refresh

Solution: Check that cookies are being set properly. Ensure your app is served over HTTPS in production.

How Turnstile Verification Works

Client-Side (Browser)

1. User fills out login/register form
2. Turnstile widget challenges the user (if suspicious activity detected)
3. Widget returns a token to the client
4. Token is sent to the server along with credentials

Server-Side (Verification)

1. Server action receives the token from the client
2. Server calls Cloudflare’s verification endpoint with:
   • Secret key (from TURNSTILE_SECRET_KEY)
   • User’s token
   • User’s IP address (optional, for better fraud detection)
3. Cloudflare responds with success/failure
4. If verification fails, authentication is rejected
5. If verification succeeds, authentication proceeds

Security Note: The secret key never leaves the server, preventing token forgery.

Architecture

Components

• oauth-buttons.tsx: OAuth provider buttons
• turnstile-widget.tsx: Cloudflare Turnstile client-side widget
• turnstile/verify.ts: Server-side Turnstile token verification
• actions.ts: Server actions for login/register with Turnstile
• login/page.tsx: Login page
• register/page.tsx: Registration page
• auth/callback/route.ts: OAuth callback handler

Auth Flow

┌─────────────┐
│  User clicks│
│ OAuth button│
└──────┬──────┘
       │
       v
┌─────────────────────┐
│  Supabase redirects │
│   to OAuth provider │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│ User authenticates  │
│  with OAuth provider│
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│ Provider redirects  │
│ to /auth/callback   │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│ Exchange code for   │
│    session token    │
└──────────┬──────────┘
           │
           v
┌─────────────────────┐
│  Redirect to app    │
│   (authenticated)   │
└─────────────────────┘

Design Philosophy

The authentication UI follows the Manus design aesthetic:

• Clean, modern interface
• Centered layout with gradient background
• Card-based form design with rounded corners
• Clear visual hierarchy
• OAuth buttons with brand colors
• Subtle animations and transitions
• Accessible and responsive

Next Steps

• Add password reset functionality
• Add email change functionality
• Add 2FA/MFA support
• Add account deletion
• Add session management (view active sessions)