# Вход через Яндекс / VK / Bitrix24 — ключи и подключение

**Зачем это.** Чтобы сотрудники входили в портал кнопкой «Войти через Яндекс»
(позже — VK и Bitrix24) без отдельного пароля. Сервис сам подтверждает «это тот
самый человек», а его пароль мы не видим. Это называется OAuth (расшифровка:
стандарт «входа через чужой аккаунт» — сервис подтверждает личность, не
раскрывая нам пароль).

**Главный принцип — «белый список».** Через соцсеть войдёт ТОЛЬКО сотрудник,
чья почта уже добавлена в реестр пользователей (раздел «Пользователи»).
Посторонний человек с любым Яндекс-аккаунтом получит вежливый отказ. Никакой
саморегистрации нет. Система узнаёт сотрудника по ЛЮБОЙ из почт его учётки
(основной или дополнительной).

> Термины простыми словами:
> - **client_id (ClientID)** — открытый «номер» нашего приложения в сервисе.
> - **client_secret (Client secret)** — секретный пароль приложения. Показывать
>   и пересылать нельзя.
> - **Redirect URI** — адрес, куда сервис возвращает пользователя после входа.
>   Должен совпадать символ в символ.
> - **Переменная окружения** — «ячейка с настройкой» на сервере (в Timeweb):
>   имя + значение. Так секреты попадают в приложение, не попадая в код.

---

## 1. Яндекс — ✅ приложение зарегистрировано (2026-07-06)

Приложение в кабинете Яндекса создано владельцем. Проверено:

- Redirect URI: `https://sekta-atlas.ru/api/auth/yandex/callback` — совпадает
  с нашим кодом, менять не нужно.
- Выданные права: почта, логин/имя/фамилия/пол, телефон.

### Осталось одно: внести два ключа в Timeweb (5 минут)

**Шаг 1. Скопировать ключи из кабинета Яндекса.**
Откройте https://oauth.yandex.ru и выберите ваше приложение (SEKTA ATLAS).
На странице приложения есть два поля:

- **ClientID** — длинная строка из букв и цифр;
- **Client secret** — второе поле, справа от него кнопка копирования (значок
  из двух листов) — нажмите её, значение попадёт в буфер обмена.

**Шаг 2. Внести их в Timeweb.**
Timeweb Cloud (https://timeweb.cloud) → раздел **«Приложения»** → приложение
**SEKTA ATLAS** → **«Настройки»** → блок **«Переменные окружения»** → кнопка
добавления переменной. Добавить ровно две (имена — точно как написано,
заглавными, без пробелов):

| Имя переменной | Что вставить в значение |
| --- | --- |
| `OAUTH_YANDEX_CLIENT_ID` | ClientID из кабинета Яндекса |
| `OAUTH_YANDEX_SECRET` | Client secret (скопированный кнопкой) |

Нажать **«Сохранить»**.

**Шаг 3. Передеплой (перезапуск приложения).**
Там же в Timeweb нажать кнопку передеплоя (кнопка со стрелками «по кругу»).
Без этого шага новые переменные НЕ подхватятся — сайт продолжит работать со
старыми настройками. Сборка занимает ~5–8 минут.

**Шаг 4. Проверка.**
Открыть https://sekta-atlas.ru/login — под формой появится кнопка
**«Войти через Яндекс»** (она появляется автоматически, как только сервер
видит оба ключа; отдельно ничего включать не нужно). Нажмите её и войдите
своим Яндекс-аккаунтом: ваша почта уже в реестре, поэтому вход пройдёт как
обычный. Если кнопки нет через 10 минут после передеплоя — проверьте имена
переменных (опечатка в имени = ключ «не виден»).

### Какие права запрашиваем и зачем

- **Почта** — по ней узнаём сотрудника: сверяем с реестром пользователей
  («белый список»). Без почты вход невозможен.
- **Имя** — подпись в журнале «История действий» («Вход через Яндекс: Иван
  Петров»).
- **Телефон и пол** — Яндекс их может передавать (права выданы при
  регистрации), но приложение их **НЕ сохраняет**: для входа они не нужны.

### Где смотреть входы

Каждый вход через Яндекс пишется в журнал «История действий»:
https://tech.sekta-atlas.ru/audit (техническая панель → «История действий»).
Видно, кто вошёл, когда и с какого адреса.

### Безопасность ключей — важно

- **Не отправляйте ключи в чат, почту или мессенджер** — они вносятся только
  в Timeweb (как выше). Всё правильно, что вы их не присылали.
- **Если секрет случайно «засветился»** (переслали, показали экран): в
  кабинете Яндекса (https://oauth.yandex.ru → ваше приложение) есть кнопка
  перевыпуска Client secret. Нажать её → скопировать НОВЫЙ секрет → обновить
  значение переменной `OAUTH_YANDEX_SECRET` в Timeweb → передеплой. Старый
  секрет перестанет действовать.

---

## 2. VK — шаг регистрации (ещё не сделан)

1. Откройте https://id.vk.com/about/business/go (кабинет «VK ID для бизнеса»)
   либо старый кабинет приложений: https://vk.com/apps?act=manage
2. Создайте новое приложение, тип — **«Веб-сайт»** (Web).
3. Базовый адрес сайта: `https://sekta-atlas.ru`
4. **Redirect URI / Доверенный redirect:** `https://sekta-atlas.ru/api/auth/vk/callback`
5. Включите доступ к **почте** (email) — по ней узнаём сотрудника.
6. После создания в настройках будут **ID приложения** и **Защищённый ключ**
   (это client_id и client_secret).

Затем — та же схема внесения в Timeweb, что и для Яндекса (Приложения →
SEKTA ATLAS → Настройки → Переменные окружения → Сохранить → передеплой):

| Имя переменной | Что вставить в значение |
| --- | --- |
| `OAUTH_VK_CLIENT_ID` | ID приложения VK |
| `OAUTH_VK_SECRET` | Защищённый ключ VK |

Кнопка «Войти через VK» появится на странице входа **автоматически** после
внесения переменных и передеплоя.

## 3. Bitrix24 — шаг регистрации (ещё не сделан)

1. Зайдите в ваш Bitrix24 под администратором.
2. Слева: **«Приложения»** → **«Разработчикам»** (Developer resources).
3. Выберите **«Другое»** → **«Локальное приложение»** (Local application),
   тип с OAuth 2.0 (серверное, «Backend»).
4. В поле **Redirect URI (URL перенаправления)** вставьте:
   `https://sekta-atlas.ru/api/auth/bitrix/callback`
5. Права (scope): достаточно **user** (профиль пользователя).
6. Сохраните. Появятся **Код приложения (client_id)** и **Ключ (client_secret)**.

Затем — та же схема внесения в Timeweb; для Bitrix24 переменных ТРИ:

| Имя переменной | Что вставить в значение |
| --- | --- |
| `OAUTH_BITRIX_CLIENT_ID` | Код приложения из Bitrix24 |
| `OAUTH_BITRIX_SECRET` | Ключ приложения из Bitrix24 |
| `OAUTH_BITRIX_PORTAL` | Домен вашего портала, например `hairsekta.bitrix24.ru` |

Кнопка «Войти через Bitrix24» появится **автоматически** после внесения
переменных и передеплоя.

---

## Как устроен вход (для понимания)

1. Сотрудник нажимает «Войти через Яндекс» → попадает на страницу Яндекса и
   подтверждает вход (пароль вводится на стороне Яндекса, мы его не видим).
2. Яндекс возвращает его на наш сайт и сообщает почту и имя.
3. Мы ищем почту в реестре пользователей (проверяются и основная, и
   дополнительные почты учётки). Нашли и учётка активна → полноценный вход,
   как по логину/паролю, с записью в «Историю действий». Не нашли → отказ
   с подсказкой «попросите владельца добавить вашу почту».
4. Защита от подделки: каждая попытка входа помечена одноразовой подписанной
   меткой со сроком годности 10 минут — чужой или «протухший» возврат
   отклоняется.

**Важно про Redirect URI:** он должен совпадать с указанным здесь символ в
символ (включая `https://` и без слэша на конце). Если сервис просит «домен
приложения» — это `sekta-atlas.ru`.