Способы входа
Minishop поддерживает семь способов входа:
- Email-код — одноразовый код или magic link из письма.
- Email и пароль — пароль, заданный после подтверждения email.
- Telegram — Mini Apps
initDataвнутри Telegram и OAuth / OpenID Connect в браузере. - Google — серверный OAuth 2.0 / OpenID Connect flow.
- Yandex ID — OAuth-приложение Яндекса.
- Discord — OAuth2-приложение Discord.
- Passkey — ключ доступа WebAuthn.
В админке способы собраны в Система → Настройки → Способы входа. Пользователь управляет паролем, passkey, привязанными провайдерами и адресом для уведомлений в Настройки → Безопасность.
| Способ | Когда доступен | Что нужно настроить |
|---|---|---|
| Email-код | Включён EMAIL_LOGIN_ENABLED и готов SMTP |
SMTP, адрес отправителя и публичный URL Mini App |
| Email и пароль | Пользователь подтвердил email и задал пароль | Те же SMTP-настройки для подтверждения и восстановления |
| Telegram | Включён TELEGRAM_LOGIN_ENABLED |
BotFather и BOT_TOKEN; для браузера также Telegram OAuth |
Включён GOOGLE_OIDC_ENABLED |
OAuth client ID, secret и callback | |
| Yandex ID | Включён YANDEX_OIDC_ENABLED |
OAuth client ID, secret и callback |
| Discord | Включён DISCORD_OIDC_ENABLED |
OAuth2 application ID, secret и callback |
| Ключи доступа (passkey) | Включён PASSKEY_LOGIN_ENABLED |
HTTPS, RP ID и разрешённые origins |
У каждого доступного провайдера есть отдельный переключатель Рекомендуемый способ входа. Если он включён, Minishop показывает красный индикатор внимания в настройках, пока пользователь не привяжет этот способ. Если выключен, способ остаётся доступным для входа и привязки, но его отсутствие само по себе не включает индикатор. По умолчанию рекомендации включены, чтобы обновление сохраняло прежнее поведение; администратор может оставить только нужные способы.
В разделе Внешний вид переключатель Компактные способы входа заменяет широкие кнопки значками провайдеров. Режим включён по умолчанию, но применяется только при наличии более одного доступного способа входа: единственный способ остаётся широкой кнопкой или формой. В разделе Способы входа для каждого провайдера есть переключатель Широкая кнопка входа: он оставляет этот способ широким при включённом компактном режиме. Для email он сразу показывает форму входа и включён по умолчанию; если его выключить, форма открывается нажатием на значок почты. В стандартной теме компактные способы входа отображаются без круглой подложки. Настройка рекомендуемого способа входа продолжает отдельно управлять индикатором внимания.
Доступ к админке определяется ролью внутреннего аккаунта и не зависит от способа входа. Первый владелец назначается серверной командой после подтверждения email.
На этой странице
Заголовок раздела «На этой странице»- Модель аккаунта и защита от дублей
- Общие требования
- Общая настройка email
- Email-код
- Email и пароль
- Telegram
- Yandex ID
- Discord
- Ключи доступа (passkey)
- Привязка способов и адрес для уведомлений
- Общая проверка
- Настройка локального SMTP-сервера
- Рекламные источники
Модель аккаунта и защита от дублей
Заголовок раздела «Модель аккаунта и защита от дублей»Один пользователь Minishop может иметь несколько способов входа и несколько подтверждённых email-адресов. Роли адресов разделены:
- основной email используется для входа по коду/паролю, восстановления доступа и синхронизации поля email в Remnawave Panel;
- email для уведомлений явно выбирается пользователем из подтверждённых адресов;
- Google и Yandex ID идентифицируются стабильной парой
provider + subject, а не адресом почты; - дополнительный адрес OIDC не становится логином по email и не меняет запись в Remnawave Panel сам по себе.
Если новый вход Google или Yandex ID возвращает email, уже занятый существующим аккаунтом, backend не создаёт второго пользователя и не связывает аккаунты только по совпавшей строке. После успешного OAuth backend отправляет одноразовый код на уже подтверждённый адрес. OAuth подтверждает доступ к аккаунту провайдера, а код — владение существующим аккаунтом Minishop. Только после обеих проверок identity привязывается к исходной записи и пользователь входит в неё. Основной email, адрес уведомлений и поле email в Remnawave Panel при этом не меняются.
Контекст незавершённой привязки хранится в короткоживущей подписанной HttpOnly-cookie. Клиент
отправляет обратно только код: provider, стабильный subject, точный email и ID целевого
пользователя нельзя подменить в браузере. Перед повторной отправкой и подтверждением backend снова
проверяет владельца email, существующие identity и включённость провайдера. Истёкший контекст,
сменившийся владелец адреса и параллельная привязка завершаются ошибкой без создания пользователя.
При объединении сохраняются подтверждённые адреса обеих записей, но основной адрес целевого аккаунта не меняется автоматически. Подписки, платежи, реферальные ограничения и другие сущности проходят существующие проверки конфликтов. Если безопасное объединение невозможно, операция останавливается без частичных изменений.
Общие требования
Заголовок раздела «Общие требования»Укажите публичный HTTPS URL Mini App и стабильный секрет сессий:
Маршруты /auth/* должны попадать в Web App API. В штатном Docker Compose они проходят через
frontend nginx. Для собственного reverse proxy не отправляйте callback в webhook-сервер на порту
8080 — Web App backend слушает внутренний порт 8081.
Для production используйте отдельные OAuth-приложения и секреты. Не помещайте client secret в frontend, публичные JSON-конфиги или URL.
Общая настройка email
Заголовок раздела «Общая настройка email»Email-код и вход по паролю используют один SMTP-контур. Включите способ входа и заполните все обязательные параметры:
Если хотя бы одно SMTP-поле пустое, backend возвращает email_auth_enabled=false в bootstrap, а
frontend скрывает email-вход. Для magic link также нужен корректный
SUBSCRIPTION_MINI_APP_URL, потому что ссылка в письме строится на его основе.
Типовой расширенный SMTP-конфиг:
Для Brevo обычно подходит порт 587 с STARTTLS. Если основной порт недоступен, приложение
пробует порты из SMTP_FALLBACK_PORTS; порт 465 используется через SSL wrapper автоматически.
SMTP_FROM_EMAIL должен быть подтверждён у SMTP-провайдера, иначе письмо часто отклоняется или
попадает в спам. SMTP_FROM_NAME можно оставить пустым — тогда используется название Web App.
HTML-письма используют бренд Mini App: название из WEBAPP_TITLE, accent из внешнего вида и
логотип из раздела Внешний вид. Загруженный через админку файл backend прикладывает как inline
image (cid:webapp-logo), поэтому получателю не нужен доступ к внутреннему
/webapp-uploaded-logo/.... Публичный https:// URL используется как внешний <img> и может
быть скрыт почтовым клиентом до разрешения загрузки изображений.
Полный справочник переменных: SMTP и вход по email.
Email-код
Заголовок раздела «Email-код»Email-код позволяет зарегистрироваться или войти без Telegram:
- Пользователь вводит email.
- Backend проверяет rate limit и создаёт одноразовый код.
- Письмо отправляется через SMTP. При валидном
SUBSCRIPTION_MINI_APP_URLоно также содержит magic link. - Пользователь вводит код в Mini App или открывает magic link.
- Backend создаёт нового email-пользователя или находит существующего.
- Referral-параметр из URL применяется к новой или существующей записи.
- Пользователь получает Web App-сессию.
Коды хранятся в базе в хешированном виде, устаревают по EMAIL_CODE_TTL_SECONDS, повторная
отправка ограничена EMAIL_CODE_RESEND_SECONDS, а число попыток — EMAIL_CODE_MAX_ATTEMPTS и
общими brute-force настройками.
После входа пользователь может привязать email к Telegram-аккаунту через код или привязать
Telegram к email-аккаунту через Mini Apps initData либо Telegram OAuth.
Проверка email-кода
Заголовок раздела «Проверка email-кода»- Перезапустите backend и frontend после изменения
.env. - Откройте
https://app.domain.com/вне Telegram и убедитесь, что email-вход виден. - Запросите код на тестовый адрес.
- Проверьте письмо, magic link и ручной ввод шестизначного кода.
- Если письмо не пришло, проверьте backend:
Частые причины:
- форма скрыта — не заполнено обязательное SMTP-поле или выключен
EMAIL_LOGIN_ENABLED; - письмо не отправляется — неверен порт, STARTTLS/SSL, SMTP login/API key или отправитель;
- magic link ведёт не туда —
SUBSCRIPTION_MINI_APP_URLне является публичным HTTPS URL Mini App; - код сразу устаревает — неверен
EMAIL_CODE_TTL_SECONDSили время на сервере; rate_limited— ещё не прошёлEMAIL_CODE_RESEND_SECONDSлибо сработала brute-force защита.
Email и пароль
Заголовок раздела «Email и пароль»После подтверждения email пользователь может задать или изменить пароль в настройках профиля. Пароль хранится как PBKDF2-SHA256 hash с солью. После установки доступен путь:
При неудачном входе frontend предлагает перейти к обычному email-коду. Установка, изменение и восстановление пароля также подтверждаются email-кодом, поэтому рабочий SMTP остаётся обязательным.
Telegram
Заголовок раздела «Telegram»Telegram-вход работает двумя способами:
- внутри Telegram Mini App backend проверяет Telegram Mini Apps
initData; - в обычном браузере используется Telegram OAuth / OpenID Connect Authorization Code Flow с
PKCE,
nonce, callback/auth/telegram/callbackи серверной проверкойid_tokenпо JWKS.
initData не требует отдельного OAuth-секрета, но требует корректного BOT_TOKEN, публичного
HTTPS Mini App URL и настройки Mini Apps в BotFather. OAuth нужен для кнопки Telegram вне клиента
Telegram и для привязки Telegram к email-аккаунту.
Переменные Telegram
Заголовок раздела «Переменные Telegram»TELEGRAM_OAUTH_CLIENT_ID можно не задавать, если client ID совпадает с bot ID: приложение
возьмёт его из префикса BOT_TOKEN. TELEGRAM_OAUTH_CLIENT_SECRET для браузерного OAuth
обязателен.
TELEGRAM_OAUTH_REQUEST_ACCESS=write добавляет scope telegram:bot_access, чтобы бот мог
написать пользователю после входа. Если это не нужно, оставьте переменную пустой. Также
поддерживается phone, если вы осознанно запрашиваете телефон.
WEBAPP_AUTH_MAX_AGE_SECONDS ограничивает возраст initData и OAuth id_token, а
WEBAPP_LOGIN_TOKEN_TTL_SECONDS — TTL OAuth state, nonce и login-token.
Полный справочник: Веб-приложение, внешний вид и Telegram Login.
Настройка Telegram в BotFather
Заголовок раздела «Настройка Telegram в BotFather»- Откройте
@BotFather→/mybots→ выберите бота. - В Bot Settings → Domain укажите домен без протокола и пути, например
app.domain.com. - В Bot Settings → Mini Apps укажите
https://app.domain.com/. - В Bot Settings → Web Login включите OpenID Connect Login, если переключатель доступен.
- Скопируйте client ID и secret в
TELEGRAM_OAUTH_CLIENT_IDиTELEGRAM_OAUTH_CLIENT_SECRET. - В Web Login → Allowed URLs добавьте:
После изменения .env пересоздайте backend и frontend:
Проксирование Telegram OAuth
Заголовок раздела «Проксирование Telegram OAuth»Публичный домен SUBSCRIPTION_MINI_APP_URL должен идти в frontend:80. Frontend nginx сам
проксирует /api/* и /auth/* во внутренний Web App server на backend:8081. Готовые схемы
Caddy, Angie, Nginx, Newt и прямой публикации описаны в
развертывании.
Если backend не может напрямую открыть oauth.telegram.org, задайте SOCKS5 endpoint:
Через proxy пойдут обмен authorization code на token и загрузка JWKS. Страница /auth
по-прежнему открывается через сеть пользователя, входящий Telegram webhook приходит на публичный
WEBHOOK_BASE_URL, а initData и legacy Login Widget проверяются локально. Чтобы Bot API
продолжал использовать proxy, а OAuth ходил напрямую, задайте
TELEGRAM_OAUTH_USE_BOT_PROXY=False.
Проверка Telegram
Заголовок раздела «Проверка Telegram»Внутри Telegram:
- Откройте Mini App кнопкой бота или URL из BotFather.
- Убедитесь, что вход проходит без OAuth redirect.
- При ошибке проверьте URL Mini App, домен BotFather и возраст
initData.
В обычном браузере:
- Откройте
https://app.domain.com/и нажмите вход через Telegram. - Проверьте redirect на Telegram OAuth и возврат на
https://app.domain.com/auth/telegram/callback. - После callback пользователь должен вернуться на
/со статусомtelegram_auth=success, который frontend удалит из URL.
При привязке к email-аккаунту из «Настройки → Безопасность» возврат идёт на
/settings/security. Успех обновляет профиль и показывает «Привязано»; отмена,
ошибка конфигурации или проверки подтверждения показываются в этом же аккаунте.
Если окно Telegram закрылось без продолжения, вернитесь в исходную вкладку сайта
и проверьте состояние привязки. Само закрытие окна не подтверждает её завершение.
Для диагностики сохраните статус telegram_auth из адреса возврата, клиент Telegram,
ОС и браузер; не публикуйте OAuth code, cookies или токены.
Для диагностики:
Частые причины:
telegram_oauth_not_configured— не задан secret или client ID не получен из настройки/токена;Telegram OAuth nonce mismatch— устарели session/state, изменилсяWEBAPP_SESSION_SECRETлибо callback пришёл с другого домена;Telegram OAuth ID token is stale— слишком малWEBAPP_AUTH_MAX_AGE_SECONDSили сбито время;- callback не проходит — Allowed URL не совпадает либо
/auth/*не доходит до Web App API; invalid_token— backend не имеет доступа к token endpoint/JWKS или неверно настроен proxy;- Mini App не открывается — домен BotFather не совпадает с
SUBSCRIPTION_MINI_APP_URL.
Общие логи: авторизация Mini App и Telegram OAuth.
- Откройте Google Cloud Console и выберите отдельный production-проект.
- Настройте OAuth consent screen: название сервиса, контакты, домен, privacy policy и terms.
- Создайте OAuth 2.0 Client ID типа Web application.
- Authorized JavaScript origins оставьте пустым. Minishop использует серверный Authorization Code Flow с PKCE и не загружает Google Identity Services JavaScript SDK.
- В Authorized redirect URIs добавьте точный адрес:
- Сохраните настройки и включите способ:
Minishop запрашивает только openid email profile, проверяет подпись и стандартные OIDC claims
(iss, aud, exp, nonce) и принимает email только при email_verified=true.
Google требует точного совпадения redirect URI, включая схему, регистр, порт, путь и слеш. Подробности: OAuth 2.0 for Web Server Applications.
Yandex ID
Заголовок раздела «Yandex ID»- Откройте Yandex OAuth и создайте приложение для авторизации пользователей.
- Добавьте платформу Веб-сервисы.
- Укажите Redirect URI:
- Разрешите минимальные права
login:email,login:infoиlogin:avatar. - Сохраните настройки и включите способ:
Для контакта Minishop использует default_email, возвращённый Yandex ID. Адрес добавляется как
подтверждённый адрес провайдера, но не заменяет основной email существующего аккаунта.
Пошаговая регистрация: официальная документация Yandex ID.
Discord
Заголовок раздела «Discord»- Откройте Discord Developer Portal и создайте приложение.
- В разделе OAuth2 добавьте Redirect URL:
- Скопируйте Application ID и Client Secret и включите способ:
Minishop использует серверный Authorization Code Flow и запрашивает только identify email.
Профиль загружается через Discord API /users/@me; email принимается как подтверждённый только
при verified=true. Для уже существующего аккаунта совпадение email подтверждается кодом так же,
как для Yandex ID.
Официальный справочник: Discord OAuth2.
Настройки Google, Yandex ID и Discord, сохранённые в админке, применяются к следующим запросам
/auth/{provider}/start и /auth/{provider}/callback без перезапуска backend. Экран входа и
кешированные данные кабинета также обновляются после сохранения. Если админка сообщает, что ключ
«сохранён, но не применён», он не считается активным до перезапуска.
Ключи доступа (passkey)
Заголовок раздела «Ключи доступа (passkey)»Passkey работает через WebAuthn и требует HTTPS. Исключение браузеров для локального localhost
не следует использовать как production-настройку.
PASSKEY_RP_ID— домен без протокола, порта и пути;PASSKEY_RP_NAME— имя сервиса, которое устройство показывает при создании ключа;PASSKEY_ORIGINS— полный origin сhttps://; несколько origins разделяются запятыми;- после смены RP ID старые ключи перестанут работать для нового домена;
- не отключайте остальные способы, пока не проверили passkey на втором устройстве.
Подробнее: Passkeys на MDN.
Привязка способов и адрес для уведомлений
Заголовок раздела «Привязка способов и адрес для уведомлений»В настройках профиля пользователь может:
- привязать email к Telegram-аккаунту через код;
- привязать Telegram через Mini Apps
initDataили Telegram OAuth; - задать или изменить пароль;
- привязать Google, Yandex ID, Discord и passkey;
- выбрать email для уведомлений из подтверждённых адресов.
Если привязываемый способ уже принадлежит другому аккаунту, появляется общий диалог объединения: Telegram, Google, Yandex ID, Discord и email используют один сценарий. Свежая авторизация привязываемого способа подтверждает второй аккаунт; текущий аккаунт подтверждается повторным входом через уже привязанного провайдера, passkey или кодом email. SMTP и email-вход не обязательны при подтверждении через провайдера или passkey. После явного согласия сохраняются текущий Minishop ID, основной адрес и настройки, переносятся доступные способы входа и связанные данные, а старые Web App-кеши сбрасываются. Новые зарегистрированные провайдеры используют тот же механизм без правил для каждой пары.
Если новый OAuth-профиль ещё не привязан к аккаунту, а его email занят другой записью, привязка из настроек сохраняет только доказанную identity провайдера: чужой email и его аккаунт остаются без изменений. Для объединения с владельцем email требуется подтверждение адреса кодом. Две разные identity одного провайдера, административная история второго аккаунта и другие несовместимые данные отклоняются без частичного переноса. Подробности протокола — в описании независимых аккаунтов.
Основной email меняется отдельным двухэтапным сценарием: код сначала отправляется на текущий адрес, затем второй код — на новый. После подтверждения новый адрес становится основным и адресом уведомлений, а Minishop синхронизирует его в Remnawave Panel. Привязка или отвязка OIDC-провайдера сама по себе поле email в Panel не меняет.
Смену основного адреса можно отключить независимо от email-входа:
При отключении кнопка в кабинете становится неактивной, а backend отклоняет все этапы уже начатого сценария. Это не мешает впервые привязать email, войти по коду/паролю или выбрать другой подтверждённый OIDC-адрес для уведомлений.
Смена адреса проходит так:
- Код отправляется на текущий основной адрес.
- После проверки пользователь вводит новый адрес; занятый адрес отклоняется до создания записей.
- Второй код отправляется на новый адрес и привязан к пользователю и точному адресу.
- После подтверждения обновляются основной email, адрес уведомлений и email в Remnawave Panel. На старый адрес приходит уведомление безопасности, на новый — подтверждение смены.
Уникальность проверяется до отправки кода и повторно в транзакции. Ограничения базы закрывают гонку параллельных запросов. Коды входа, восстановления и подтверждения основного email идут на адрес соответствующей операции; автоматические уведомления — на выбранный адрес уведомлений.
Общая проверка
Заголовок раздела «Общая проверка»- Проверьте каждый включённый способ на экране входа.
- Войдите по email-коду, задайте пароль, выйдите и войдите по паролю.
- Проверьте Telegram внутри Mini App и отдельно в обычном браузере.
- Войдите новыми Google, Yandex ID и Discord аккаунтами; для совпавшего email подтвердите связывание кодом и убедитесь, что дубль пользователя не создан.
- Добавьте passkey, выйдите, войдите с ним и проверьте удаление ключа при наличии другого способа.
- В Настройки → Безопасность проверьте список identity, основной email и адрес уведомлений.
- Убедитесь, что подписка и email в Remnawave Panel не меняются от простой привязки OAuth.
Общие причины ошибок:
- кнопка скрыта — способ выключен или заполнены не все обязательные параметры;
redirect_uri_mismatch— callback отличается схемой, доменом, портом, путём или слешем;account_exists— совпавший основной email ещё не подтверждён для автоматической привязки;- OIDC-контекст устарел — повторите вход через провайдера;
- passkey недоступен — нет HTTPS, RP ID не соответствует домену или origin не разрешён;
- уведомления идут не туда — проверьте выбранный адрес, способ последнего входа его не меняет.
Email-уведомления поддержки, платежей и жизненного цикла подписки используют тот же SMTP-контур. См. также уведомления и поддержку пользователей.
Настройка локального SMTP-сервера
Заголовок раздела «Настройка локального SMTP-сервера»Перед запуском настройте DNS-записи домена:
- A —
mail.example.comс IP сервера; - MX —
mail.example.comс приоритетом 10; - PTR —
mail.example.comу хостера VPS; - TXT —
v=spf1 ip4:1.2.3.4 ~all, где1.2.3.4— реальный IPv4 сервера.
Изменения DNS могут применяться от нескольких часов до суток. Для STARTTLS нужен сертификат
домена mail.example.com. Например, в Caddy:
Установка:
- Подготовьте Compose:
- Запустите:
- Создайте пользователя:
Созданный адрес и пароль можно использовать в почтовом клиенте и SMTP-настройках Minishop.
Рекламные источники
Заголовок раздела «Рекламные источники»Кампании, ссылки, предложения и проверка источника покупки описаны в разделе рекламы.