Impersonation Setup

This document explains how the user impersonation feature works and how to configure it.

How It Works

1. Super Admin Initiates Impersonation: A super admin clicks "Impersonate" on a user in the admin panel
2. Magic Link Generation: The backend generates a Supabase magic link for the target user
3. Callback Handling: The frontend callback page (/auth/impersonate-callback) processes the magic link and sets the session
4. Session Switch: The admin is now signed in as the target user
5. Switch Back: The admin can click "Switch Back" to return to their own account

Supabase Configuration

1. Add Redirect URL

You need to add the impersonation callback URL to Supabase's allowed redirect URLs:

1. Go to Supabase Dashboard → Authentication → URL Configuration
2. Add to "Redirect URLs":
   • For local development: http://localhost:3000/auth/impersonate-callback
   • For production: https://yourdomain.com/auth/impersonate-callback

2. Verify Email Settings

For impersonation to work smoothly, ensure:

• Email confirmations are disabled for development (or users must have confirmed emails)
• Magic links are enabled in Authentication → Settings

Troubleshooting

Issue: "Just logged me out" / Redirects to sign-in

Possible causes:

1. Redirect URL not added to Supabase allowed URLs
2. Magic link expired (they expire after a short time)
3. Session not being set properly

Solutions:

1. Verify the redirect URL is in Supabase's allowed list
2. Try impersonating again (generate a fresh magic link)
3. Check browser console for errors
4. Verify the callback page is accessible at /auth/impersonate-callback

Issue: Session not persisting

Possible causes:

1. Cookie/Session storage issues
2. CORS configuration
3. SameSite cookie warnings

Solutions:

1. Check browser console for cookie warnings
2. Verify NEXT_PUBLIC_SUPABASE_URL is correct
3. Clear browser cookies and try again
4. Check that cookies are being set (in DevTools → Application → Cookies)

Testing Impersonation

1. Sign in as a super admin
2. Go to /dashboard/admin
3. Click "Impersonate" on any user
4. You should be redirected and signed in as that user
5. You should see a yellow banner indicating impersonation mode
6. Click "Switch Back" to return to your admin account

Security Notes

• Only super admins can impersonate users
• All impersonation actions are logged in the admin_impersonations table
• The original admin email is stored in localStorage for easy switch-back
• Impersonation sessions are clearly marked in the UI