Настройка аутентификации Convex

Реализация безопасной аутентификации в Convex с управлением пользователями и контролем доступа.

Когда использовать

• Первоначальная настройка аутентификации.
• Реализация управления пользователями (таблица users, маппинг идентификаторов).
• Создание вспомогательных функций аутентификации.
• Настройка провайдеров (Convex Auth, Clerk, WorkOS AuthKit, Auth0, кастомный JWT).

Когда НЕ использовать

• Аутентификация для не-Convex бэкенда.
• Чистая документация OAuth/OIDC без имплементации Convex.
• Провайдер уже настроен, нужен только однострочный фикс.

Первый шаг: выбор провайдера

Convex поддерживает несколько подходов к аутентификации. Не предполагайте провайдер без проверки.

Перед написанием кода: спросите пользователя, какое решение он хочет — если это не очевидно из репозитория. Проверьте сигналы в репозитории:

• Зависимости: @clerk/*, @workos-inc/*, @auth0/* или пакеты Convex Auth.
• Существующие файлы: convex/auth.config.ts, middleware аутентификации, обёртки провайдеров.
• Переменные окружения, явно указывающие на провайдера.

Варианты провайдеров

• Convex Auth — хороший вариант по умолчанию, когда аутентификация обрабатывается прямо в Convex.
• Clerk — когда приложение уже использует Clerk или нужны его hosted auth функции.
• WorkOS AuthKit — когда приложение уже использует WorkOS.
• Auth0 — когда приложение уже использует Auth0.
• Кастомный JWT — при интеграции существующей системы аутентификации.

После выбора провайдера

Прочитайте официальную документацию провайдера и соответствующий локальный справочный файл:

• Convex Auth: официальная документация, затем references/convex-auth.md
• Clerk: официальная документация, затем references/clerk.md
• WorkOS AuthKit: затем references/workos-authkit.md
• Auth0: затем references/auth0.md

Используйте эти источники для: установки пакетов, подключения клиентского провайдера, переменных окружения, настройки convex/auth.config.ts, паттернов UI входа и выхода.

Базовый паттерн: защита бэкенд-функций

Самая распространённая задача аутентификации — проверка идентификатора в функциях Convex.

// Плохо: доверие userId, предоставленному клиентом
export const getMyProfile = query({
  args: { userId: v.id("users") },
  handler: async (ctx, args) => {
    return await ctx.db.get(args.userId);
  },
});

// Хорошо: серверная проверка идентификатора
export const getMyProfile = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    return await ctx.db
      .query("users")
      .withIndex("by_tokenIdentifier", (q) =>
        q.eq("tokenIdentifier", identity.tokenIdentifier),
      )
      .unique();
  },
});

Рабочий процесс

1. Определить провайдера — спросить пользователя или вывести из репозитория.
2. Спросить, нужна ли только локальная настройка или сразу production-ready.
3. Прочитать соответствующий справочный файл провайдера.
4. Следовать официальной документации провайдера для текущих деталей настройки.
5. Следовать официальной документации Convex для общего поведения аутентификации бэкенда.
6. Добавить хранение пользователей на уровне приложения только если это нужно документации и требованиям приложения.
7. Добавить проверки авторизации для владения, ролей или доступа команды только там, где это нужно приложению.

Чек-лист

• Провайдер выбран до написания кода.
• Прочитан соответствующий справочный файл провайдера.
• Используется официальная документация для специфичного подключения провайдера.
• Не изобретена кросс-провайдерная таблица users или флоу storeUser для Convex Auth.
• Добавлены проверки аутентификации в защищённых бэкенд-функциях.
• Чёткие сообщения об ошибках («Not authenticated», «Unauthorized»).