Supabase Authentication — Email, OAuth, SSO, MFA

[Client SDK] --> [Kong API Gateway] --> [GoTrue Auth Service] --> [PostgreSQL]
     |                    |                       |                      |
     |              Rate limiting,          Xác thực user,         Lưu user data
     |              routing, API key        sinh JWT, gửi email    trong auth schema
     |              validation

{
  "sub": "d0d4e701-5a5c-4c8d-b8e7-a1b2c3d4e5f6",
  "email": "user@example.com",
  "phone": "",
  "app_metadata": {
    "provider": "email",
    "providers": ["email", "google"]
  },
  "user_metadata": {
    "full_name": "Nguyen Van A",
    "avatar_url": "https://..."
  },
  "role": "authenticated",
  "aal": "aal1",
  "session_id": "abc123-def456-...",
  "iat": 1715702400,
  "exp": 1715706000
}

User Login thành công
  --> Server trả về access_token (JWT, hết hạn sau 1h)
                    + refresh_token (opaque string, hết hạn sau 7d)
  --> Client SDK lưu cả hai token trong localStorage / cookie

Mỗi API request:
  --> Client gửi access_token trong header Authorization: Bearer <access_token>

Khi access_token hết hạn (sau ~1h):
  --> Client SDK TỰ ĐỘNG gọi POST /auth/v1/token?grant_type=refresh_token
  --> Gửi refresh_token trong body
  --> Server kiểm tra refresh_token còn hợp lệ
  --> Server trả về access_token MỚI (JWT mới, 1h mới)
                    + có thể refresh_token mới (tùy cấu hình)
  --> Client cập nhật token mới, TIẾP TỤC gọi API
  --> USER KHÔNG HỀ BIẾT quá trình này xảy ra

Khi refresh_token hết hạn (sau 7d):
  --> Server từ chối refresh
  --> Client SDK phát hiện lỗi, throw error
  --> User phải login lại từ đầu

// Sign up
const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'secure-password',
  options: {
    data: {
      full_name: 'Nguyen Van A', // user metadata
    }
  }
})

// Email verification được gửi tự động nếu enable trong Dashboard
// Sau khi verify, user có thể sign in

// Sign in
const { data, error } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'secure-password'
})

// data.session chứa access_token (JWT) và refresh_token
// data.user chứa user info (id, email, metadata)

const { data, error } = await supabase.auth.signInWithOtp({
  email: 'user@example.com',
  options: {
    emailRedirectTo: 'https://myapp.com/dashboard',
    shouldCreateUser: true, // Tự động tạo user nếu chưa tồn tại
  }
})

// User nhận email với magic link
// Click link sẽ redirect về app kèm session

const { data, error } = await supabase.auth.signInWithOtp({
  phone: '+84123456789',
  options: {
    channel: 'sms',
  }
})

// User nhận SMS chứa OTP 6 chữ số
// Verify OTP:
const { data, session, error } = await supabase.auth.verifyOtp({
  phone: '+84123456789',
  token: '123456',
  type: 'sms'
})

// Google
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: 'https://myapp.com/auth/callback',
    queryParams: {
      access_type: 'offline',
      prompt: 'consent',
    }
  }
})

// GitHub
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'github',
  options: {
    redirectTo: 'https://myapp.com/auth/callback'
  }
})

// SSO sign in
const { data, error } = await supabase.auth.signInWithSSO({
  domain: 'company.com', // Email domain hoặc organization slug
  options: {
    redirectTo: 'https://myapp.com/dashboard'
  }
})

// Register passkey (Face ID, Touch ID, Windows Hello)
const { data } = await supabase.auth.registerPasskey()

// Sign in với passkey
const { data, error } = await supabase.auth.signInWithPasskey()

// Anonymous sign in
const { data, error } = await supabase.auth.signInAnonymously()

// Sau đó, user có thể link với email/OAuth để trở thành permanent user
const { data, error } = await supabase.auth.linkIdentity({
  provider: 'google'
})

// Link Google identity vào tài khoản hiện tại
// (user đã login bằng email, muốn thêm Google login)
const { data, error } = await supabase.auth.linkIdentity({
  provider: 'google'
})

// Link GitHub identity
const { data, error } = await supabase.auth.linkIdentity({
  provider: 'github'
})

// Unlink — gỡ bỏ một identity khỏi tài khoản
// (chỉ hoạt động khi user còn ít nhất 1 identity khác)
const { data, error } = await supabase.auth.unlinkIdentity({
  identity_id: 'd0d4e701-5a5c-4c8d-b8e7-a1b2c3d4e5f6'
})

// Lấy danh sách tất cả identities của user hiện tại
const { data, error } = await supabase.auth.getUserIdentities()
// data.identities = [
//   { id: '...', provider: 'email', identity_data: { email: '...' } },
//   { id: '...', provider: 'google', identity_data: { email: '...' } },
// ]

const { data } = await supabase.auth.signInWithWeb3({
  provider: 'ethereum'
})

// Lấy session hiện tại
const { data: { session } } = await supabase.auth.getSession()

// Lấy user hiện tại
const { data: { user } } = await supabase.auth.getUser()

// Refresh session (access token hết hạn -> dùng refresh token lấy mới)
const { data, error } = await supabase.auth.refreshSession()

// Sign out
const { error } = await supabase.auth.signOut()

// Listen auth state changes
supabase.auth.onAuthStateChange((event, session) => {
  switch (event) {
    case 'INITIAL_SESSION':
      console.log('Initial session loaded:', session)
      break
    case 'SIGNED_IN':
      console.log('User signed in:', session.user)
      break
    case 'SIGNED_OUT':
      console.log('User signed out')
      break
    case 'TOKEN_REFRESHED':
      console.log('Token refreshed')
      break
    case 'USER_UPDATED':
      console.log('User updated:', session.user)
      break
    case 'USER_DELETED':
      console.log('User deleted')
      break
    case 'PASSWORD_RECOVERY':
      console.log('Password recovery event')
      break
    case 'MFA_CHALLENGE_VERIFIED':
      console.log('MFA verified')
      break
  }
})

// app/api/protected/route.ts (Next.js App Router)
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'
import { NextResponse } from 'next/server'

export async function GET() {
  const cookieStore = await cookies()
  const supabase = createServerClient(
    process.env.SUPABASE_URL!,
    process.env.SUPABASE_ANON_KEY!,
    {
      cookies: {
        get(name) { return cookieStore.get(name)?.value },
        set(name, value, options) { cookieStore.set({ name, value, ...options }) },
        remove(name, options) { cookieStore.set({ name, value: '', ...options }) },
      },
    }
  )

  const { data: { user } } = await supabase.auth.getUser()
  if (!user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  return NextResponse.json({ user })
}

// server/api/protected.get.ts (Nuxt 3)
import { serverSupabaseUser } from '#supabase/server'

export default defineEventHandler(async (event) => {
  const user = await serverSupabaseUser(event)
  if (!user) {
    throw createError({ statusCode: 401, message: 'Unauthorized' })
  }
  return { user }
})

// src/routes/api/protected/+server.ts (SvelteKit)
import { createServerClient } from '@supabase/ssr'
import type { RequestHandler } from './$types'

export const GET: RequestHandler = async ({ cookies }) => {
  const supabase = createServerClient(
    process.env.SUPABASE_URL!,
    process.env.SUPABASE_ANON_KEY!,
    { cookies: { /* ... */ } }
  )

  const { data: { user } } = await supabase.auth.getUser()
  if (!user) return new Response('Unauthorized', { status: 401 })
  return new Response(JSON.stringify({ user }))
}

// Dùng service role key cho admin operations (backend only)
const supabaseAdmin = createClient(url, serviceRoleKey)

// Verify user từ JWT gửi từ client
const { data: user, error } = await supabaseAdmin.auth.admin.getUser(jwt)

// Decode JWT không verify (chỉ đọc claims, không kiểm tra chữ ký)
const claims = supabaseAdmin.auth.getClaims(jwt)
// { sub: '...', email: '...', role: 'authenticated', ... }

// List tất cả users với pagination
const { data: { users, total } } = await supabaseAdmin.auth.admin.listUsers({
  page: 1,
  perPage: 100
})

// Bắt đầu enroll MFA (TOTP)
const { data, error } = await supabase.auth.mfa.enroll({
  factorType: 'totp',
  issuer: 'My App',
  friendlyName: 'user@example.com'
})

// Trả về QR code URL để user scan với Authenticator app
const { qr_code } = data.totp

// Challenge sau khi user đã enroll
const { data, error } = await supabase.auth.mfa.challenge({
  factorId: factorId
})

// Verify TOTP code
const { data, error } = await supabase.auth.mfa.verify({
  factorId: factorId,
  code: '123456', // 6-digit code từ Authenticator app
  challengeId: challengeId
})

// Unenroll
const { data, error } = await supabase.auth.mfa.unenroll({
  factorId: factorId
})

// Lấy danh sách các factor đã enroll
const { data } = await supabase.auth.mfa.listFactors()

-- Custom Access Token Hook: thêm custom claims vào JWT
-- Hook này được gọi mỗi khi JWT được tạo hoặc refresh
CREATE OR REPLACE FUNCTION public.custom_access_token_hook(event jsonb)
RETURNS jsonb AS $$
DECLARE
  claims jsonb := event->'claims';
  user_data jsonb;
BEGIN
  -- Lấy thông tin từ bảng profiles
  SELECT jsonb_build_object(
    'plan', plan,
    'role', role,
    'tenant_id', tenant_id
  )
  INTO user_data
  FROM public.profiles
  WHERE user_id = (event->>'user_id')::uuid;

  -- Merge thông tin vào claims
  -- user_metadata sẽ xuất hiện trong JWT và có thể dùng trong RLS policy
  claims := claims || jsonb_build_object('user_metadata', user_data);

  -- Set lại claims trong event
  RETURN jsonb_set(event, '{claims}', claims);
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

-- Sau đó enable hook trong Dashboard > Authentication > Hooks
-- Chọn "Custom Access Token" và chọn function public.custom_access_token_hook

-- Send Email Hook: tùy chỉnh gửi email qua Resend/SendGrid
CREATE OR REPLACE FUNCTION public.custom_send_email_hook(event jsonb)
RETURNS jsonb AS $$
DECLARE
  response jsonb;
BEGIN
  -- Gọi external email API (Resend, SendGrid, v.v.)
  SELECT content::jsonb INTO response
  FROM http((
    'POST',
    'https://api.resend.com/emails',
    ARRAY[http_header('Authorization', 'Bearer re_xxxxx')],
    'application/json',
    jsonb_build_object(
      'from', 'My App <noreply@myapp.com>',
      'to', ARRAY[event->>'email'],
      'subject', event->>'email_action_type',
      'html', event->>'redirect_to'
    )::text
  ));

  RETURN event;
END;
$$ LANGUAGE plpgsql;

npm install @supabase/supabase-js @supabase/ssr

# Auth UI (React)
npm install @supabase/auth-ui-react @supabase/auth-ui-shared

# Auth UI (Vue)
npm install @supabase/auth-ui-vue

<!-- Vue example -->
<script setup>
import { Auth } from '@supabase/auth-ui-vue'
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(url, anonKey)
</script>

<template>
  <Auth :supabase-client="supabase" />
</template>

// Khởi tạo admin client (backend only)
const supabaseAdmin = createClient(url, serviceRoleKey)

// Lấy user theo ID
const { data, error } = await supabaseAdmin.auth.admin.getUserById(userId)

// Liệt kê tất cả users
const { data, error } = await supabaseAdmin.auth.admin.listUsers({
  page: 1,
  perPage: 100
})

// Tạo user (không gửi email xác nhận)
const { data, error } = await supabaseAdmin.auth.admin.createUser({
  email: 'user@example.com',
  password: 'password123',
  email_confirm: true, // Bypass email verification
  user_metadata: { full_name: 'Nguyen Van A' }
})

// Cập nhật user
const { data, error } = await supabaseAdmin.auth.admin.updateUserById(userId, {
  email: 'newemail@example.com',
  user_metadata: { role: 'admin' }
})

// Xóa user
const { data, error } = await supabaseAdmin.auth.admin.deleteUser(userId)

// Khi enable CAPTCHA, client SDK tự động lấy token
const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'password123',
  options: {
    captchaToken: token // Từ Turnstile/hCaptcha widget
  }
})

-- Xem audit logs (Team plan trở lên)
SELECT
  created_at,
  ip_address,
  payload->>'action' as action,
  payload->>'actor_username' as user_email,
  payload->>'traits' as details
FROM auth.audit_log_entries
WHERE created_at > now() - interval '7 days'
ORDER BY created_at DESC
LIMIT 100;

-- Các action được log:
-- 'user_signedup', 'user_confirmed', 'user_repeated_signup',
-- 'login', 'token_refreshed', 'user_modified',
-- 'user_deleted', 'user_recovery_requested'