---
title: "Аутентификация"
description: "Конечные точки сессий Auth.js v5, провайдеры (Telegram OIDC + Mini App initData), и иерархия ролей для платформы Ring"
locale: "ru"
---
# API аутентификации

> **Info**
> Используйте вкладки **Founder** / **Developer** в боковом меню документации для фильтрации этой страницы.

Ring использует **Auth.js v5** для сессий и входа через несколько провайдеров. Обзор продукта: [Аутентификация](/ru/docs/features/authentication). Архитектура: [Архитектура аутентификации](/ru/docs/architecture/authentication).

## Поддерживаемые (готовые) провайдеры

| Провайдер | Примечания |
|-----------|------------|
| Google | OAuth redirect + One Tap |
| Telegram (web) | OIDC через `oauth.telegram.org` при наличии `AUTH_TELEGRAM_*` |
| Telegram Mini App | Учетные данные `telegram-miniapp` — WebAppData HMAC на `initData` |
| Apple | Вход с помощью Apple |
| Ring Mailer | OTP / магическая ссылка / пароль |
| Криптокошелек | Nonce + подпись через Credentials |

```mermaid
sequenceDiagram

    participant User as Пользователь
    participant UI as UI входа
    participant Auth as Auth.js
    participant IdP as Google / Telegram / Apple
    participant DB as БД-адаптер

    User->>UI: Вход
    UI->>Auth: signIn(провайдер)

    Auth->>IdP: OAuth / OIDC redirect

    IdP->>Auth: Авторизационный код

    Auth->>DB: Связать пользователя и аккаунты

    Auth->>UI: JWT session cookie

    UI->>User: Аутентифицировано
```

### For founders

## Что это API значит для операторов

- Пользователи проходят аутентификацию через UI входа; вы настраиваете секреты провайдеров, а не кастомные REST-запросы для входа.
- Сессионные куки **httpOnly**; браузеры не хранят `AUTH_SECRET` Auth.js.
- Для авторизации через Telegram Login требуется настройка **Web Login** URL-адресов у BotFather — см. чеклист на [Аутентификация](/ru/docs/features/authentication).
- Для Mini App-аутентификации нужен токен API-бота (`TELEGRAM_MINI_APP_BOT_TOKEN` предпочтительно); стандартной платформенной Mini App-оболочки нет.
- Управление Telegram-чатом администратора — **другая** область: [Управление через Telegram](/ru/docs/features/manage-via-telegram).

### For developers

## Конечные точки Auth.js

Обработчики: `app/api/auth/[...nextauth]/route.ts`.

| Метод / путь                   | Роль                                |
|-------------------------------|--------------------------------------|
| Auth.js sign-in / callback / CSRF | Редиректы провайдера и обмен токенами |
| `GET /api/auth/session`        | Текущая сессия JSON для `useSession`/клиента |
| `POST /api/auth/signout`       | Аннулирование сессионной куки        |
| `GET /api/auth/callback/telegram`     | Telegram OIDC callback (Auth.js)         |
| `GET /api/auth/telegram/callback`     | **Привязка профиля** Login Widget (требует сессию) |

### Серверный контроллер доступа

{`import { auth } from '@/auth'

export default async function ProtectedPage() {
  const session = await auth()

  if (!session) return Пожалуйста, войдите в систему

  return Добро пожаловать, {session.user.name}!
}`}

### Сессия на клиенте

{`import { useSession } from 'next-auth/react'

export default function UserProfile() {
  const { data: session, status } = useSession()

  if (status === 'loading') return Загрузка...

  if (!session) return Не аутентифицирован

  return Привет, {session.user.name}!
}`}

### Триггеры для клиентов Telegram

{`import { signIn } from 'next-auth/react'

// Веб OIDC (браузер):
await signIn('telegram', { callbackUrl })

// Mini App (внутри Telegram WebApp):
await signIn('telegram-miniapp', { initData, redirect: false })`}

Используйте `features/auth/components/telegram-signin-button.tsx` для безопасных OIDC-редиректов с учетом локали.

### Иерархия ролей

Канонические ярлыки определены в `features/auth/user-role.ts` (visitor → subscriber → member → confidential → admin → superadmin). Используйте помощники `useAuth()` / `hasRole` вместо ручного сравнения строк в UI.

### Заметки по безопасности

- JWT сессионная стратегия; суффикс куки `__Secure-` в проде
- Защита от CSRF через Auth.js
- Telegram OIDC: PKCE + state; привязка виджета: HMAC от `SHA256(bot_token)`; Mini App: **WebAppData** HMAC — не смешивайте эти методы
- Не логируйте токены бота, client secret, "сырые" `id_token` или `initData`

## Связанная документация

  
- [features/authentication](/docs/features/authentication.md) — Предпосылка: какие провайдеры доступны и как настроить Telegram Login + Mini App.

  
- [architecture/authentication](/docs/architecture/authentication.md) — Подробнее: адаптеры, OIDC и Mini App модули, переменные окружения.

  
- [examples/authentication](/docs/examples/authentication.md) — Следующий шаг: примеры кода signIn и SessionProvider.

  
- [features/subscriptions](/docs/features/subscriptions.md) — См. также: счета участника telegram_stars используют тот же бот-токен Mini App.

  
- [features/manage-via-telegram](/docs/features/manage-via-telegram.md) — См. также: админ-бот — не член OIDC и не Mini App Credentials.

  
- [api/admin](/docs/api/admin.md) — См. также: админ HTTP-интерфейсы после проверки сессии и роли.