CyberTrainРуководстваАутентификация

Аутентификация

cybertrain generate authentication пишет вход по адресу электронной почты и паролю так же, как генератор Rails 8, — кодом, которым владеет приложение, — вместе с тем, что добавляет Devise: сбросом пароля по почте, необязательным подтверждением адреса, блокировкой, «оставаться в системе», страницей учётной записи и администраторами.

Генерация

терминал — blog/shell
cybertrain generate authentication                  # публичная страница регистрации
cybertrain generate authentication --invite-only    # без регистрации: пользователи из командной строки или /setup
cybertrain generate authentication --confirmable    # (в любом режиме) новые адреса подтверждаются по почте
cybertrain db migrate

В приложении он пишет:

Файлы Что это
db/migrate/*_create_users.rb, *_create_sessions.rb users (email_address, password_digest, admin, failed_attempts, locked_until; с --confirmable ещё confirmed_at, unconfirmed_email) и sessions (строка на каждый вошедший браузер, с remember и last_active_at)
app/models/user.rb, session.rb password=, authenticate, User.authenticate_by, токены, блокировка
app/controllers/concerns/authentication.rb concern Authentication, включённый в ApplicationController
sessions_controller.rb, registrations_controller.rb (или setup_controller.rb), passwords_controller.rb, accounts_controller.rb, confirmations_controller.rb вход, регистрация (или страница первого пользователя), сброс пароля, страница учётной записи, подтверждение
app/mailers/passwords_mailer.rb, confirmations_mailer.rb письма
app/commands/user_command.rb ./<app> user ..., подключается из bin/<app>.rb
app/views/... экраны, каждый текст через t(), и partial sessions/_nav
test/fixtures/users.yml, test/support/session_test_helper.rb, test/models/, test/controllers/, test/integration/ пользователи из фикстур, sign_in_as и тесты каждой части (Тестирование)

и правки, каждую один раз: include Authentication в ApplicationController, маршруты, строку страницы заданий (Администраторы), partial навигации в макете, команду пользователя в bin/<app>.rb, настройку base_url в config/app.rb (Ссылки в письмах), а в bin/<app>.rb и bin/db.rb — строки подсистем, которые использует код, если require "cybertrain" ещё не загружает их все: cybertrain/jobs, cybertrain/mailer, cybertrain/mailer/later и cybertrain/rate_limit (Подсистемы). Повторный запуск с теми же опциями ничего не меняет: уже сделанная правка находится и пропускается, а файл, который уже таков, каким генератор его напишет, остаётся. Файл, который он написал бы иначе (отредактированный вами, или написанный более старым генератором или с другими опциями), без --force никогда не перезаписывается: вместо этого печатается его diff (Обновление с 0.4, Подтверждение адресов позже).

Тексты сгенерированных экранов лежат в английском и японском словарях фреймворка под своими ключами ленивого поиска (sessions.new.title, passwords.create.sent); приложение переопределяет их или добавляет язык в config/locales/ (Интернационализация).

Вход и выход

app/controllers/concerns/authentication.rb (фрагмент)ruby
module Authentication
  extend ActiveSupport::Concern

  included do
    before_action :resume_session
    before_action :require_authentication
    helper_method :authenticated?
  end

С этого момента каждое действие требует вошедшего пользователя, а посетитель отправляется на /session/new (303; GET запоминается и возвращается после входа, если это локальный путь). Контроллер открывает действия посетителям, как в Rails:

app/controllers/articles_controller.rb (фрагмент)ruby
class ArticlesController < ApplicationController
  allow_unauthenticated_access only: [:index, :show]

allow_unauthenticated_access(only:, except:) — метод Cybertrain::Controller, это skip_before_action :require_authentication. На открытых страницах resume_session всё равно выполняется, так что шаблон читает @current_user (и @current_session) или вызывает authenticated?. Объекта Current нет.

  • SessionsController (resource :session): GET /session/new, POST /session, DELETE /session. Попытки входа ограничены десятью на адрес клиента каждые три минуты и считаются в кэше, так что все процессы считают вместе; за прокси настройте доверенные прокси.
  • Неверный пароль, неизвестный адрес и заблокированная учётная запись получают одно и то же сообщение после одной и той же проверки пароля (по фиктивному дайджесту, если учётной записи нет).
  • resume_session завершает вход (и удаляет его строку Session), если пароль с тех пор сменился, по истечении его срока или после auth_idle_timeout без запросов (Оставаться в системе).
  • Выход удаляет строку Session и очищает сессию в cookie.

Регистрация или только по приглашению

По умолчанию генератор пишет RegistrationsController (/sign_up), который создаёт пользователя и выполняет его вход. У генератора Rails нет страницы регистрации, и первого пользователя он оставляет консоли; у CyberTrain нет консоли Ruby, поэтому он пишет такую страницу. Регистрации ограничены, как и входы, десятью каждые три минуты на адрес клиента: каждая хэширует пароль, может отправить письмо со ссылкой, а её "has already been taken" сообщает, зарегистрирован ли адрес.

Каждый адрес, который сохраняет сгенерированный код, со страницы регистрации, /setup, страницы учётной записи или из команды пользователя, должен быть одним адресом: User.email_address_format? требует ровно одного @ с текстом по обе стороны и ни одной запятой, пробельного символа, угловой скобки или управляющего символа. Почтовый модуль читает ann@example.com,eve@evil.example как двух получателей, так что без этой проверки одна учётная запись могла бы иметь два почтовых ящика, получать ссылку сброса в оба, а с --confirmable подтверждаться любым из них. Адрес должен пройти и собственную проверку почтового модуля (Cybertrain::Mailer.address_problem): только ASCII (значит, и без пробельных или управляющих символов Unicode), ни одного из ( ) [ ] ; : \ ", локальная часть не длиннее 64 байт, весь адрес не длиннее 254 байт. Адрес, который почтовый модуль отверг бы, можно было бы сохранить, но письмо на него не ушло бы никогда, поэтому он отвергается уже при вводе. Некоторые адреса, которые допускают почтовые стандарты, тоже отвергаются (локальная часть в кавычках с пробелом или запятой, адрес не в ASCII); метод приложение может изменить. Адрес, сохранённый до появления проверки, повторно не проверяется, так что его учётную запись по-прежнему можно сбросить и войти в неё.

--invite-only не пишет страницу регистрации — правильное значение по умолчанию для внутреннего инструмента, где иначе учётную запись получит тот, кто первым доберётся до сервера. Первый пользователь создаётся командой пользователя или в SetupController (GET и POST /setup), который создаёт пользователя и выполняет его вход:

  • Он отвечает, только пока нет ни одного пользователя, только с одноразовым токеном и только соединению, у которого сокет-собеседник — адрес loopback и нет заголовка X-Forwarded-For (прокси на том же хосте делает каждый запрос loopback-запросом и добавляет этот заголовок). Все остальные получают 404.
  • Токен — 32 случайных шестнадцатеричных символа, созданных при запуске программы (SetupController.setup_token), сравниваемых за постоянное время. Он держит страницу закрытой там, где проверка адреса бессильна, — за прокси, не добавляющим X-Forwarded-For. В журнале запросов он показан как [FILTERED].
  • Пока нет ни одного пользователя, сервер перед загрузкой пишет в журнал WARN no user exists yet: run ./<app> user EMAIL, or open /setup?token=<token> from this machine; это единственное место, где печатается токен.
  • <APP>_SETUP_OPEN=1 (настройка setup_open в config/app.rb) снимает проверку адреса, но никогда не снимает проверку токена, — для первого запуска за прокси на другом хосте. Уберите её, когда пользователь появится.

Команда пользователя

./<app> user пишется в обоих режимах:

терминал — рабочий серверshell
./blog user ann@example.com                       # создать или задать пароль; он читается из stdin
printf '%s' "$PASSWORD" | ./blog user ann@example.com
./blog user admin ann@example.com                 # сделать администратором
./blog user unadmin ann@example.com

Без аргумента-пароля команда читает одну строку стандартного ввода (на терминале выводит приглашение; ввод отображается), так что пароль не попадает в ps и историю оболочки. Смена пароля завершает сеансы браузеров этого пользователя и снимает блокировку. С --confirmable создаваемые ею пользователи считаются подтверждёнными. Она печатает created, updated, admin или unadmin и адрес и завершается с кодом 0 либо печатает справку или ошибку и завершается с кодом 1.

Оставаться в системе и сроки сессий

В форме входа есть флажок «Keep me signed in» (check_box_tag :remember_me). Вход длится:

  Отмечен Не отмечен
Строка Session и cookie заканчиваются через auth_remember_for (30 дней) session_absolute_max_age (две недели)
Cookie Max-Age на оставшееся время ни Max-Age, ни Expires: заканчивается вместе с браузером
Не используется в течение auth_idle_timeout (7 дней; 0 отключает) заканчивается заканчивается

last_active_at записывается не чаще раза в минуту. Сгенерированный start_new_session_for(user, remember:) вызывает session.restart_lifetime!, затем session.stamp_lifetime!(seconds, persistent), именно в таком порядке: перезапуск стирает отметку. Срок, который он отмечает, никогда не равен 0: при session_absolute_max_age = 0 вход без флажка длится session_max_age или две недели. Настройки — в разделе Конфигурация.

Блокировка

auth_lockout_attempts (10) неверных паролей блокируют учётную запись на auth_lockout_period (час). Заблокированная учётная запись отвечает сообщением о неверном пароле, каким бы ни был пароль. Успешный вход, сброс пароля и ./<app> user EMAIL обнуляют счётчик; auth_lockout_attempts = 0 отключает блокировку и перестаёт применять уже наложенную. Счёт ведёт один UPDATE, читающий строку как она есть (Relation#update_all_sql), так что одновременные попытки входа учитываются все. Ограничение частоты по адресу клиента остаётся.

Сброс пароля

Страница входа ссылается на /passwords/new. Форма адреса всегда отвечает "If that address is registered, a link to reset the password was sent to it." и для неизвестного адреса выполняет ту же работу, кроме отправки. Письмо (PasswordsMailer.reset(user, url).deliver_later, на языке запроса) содержит /passwords/<token>/edit; токен действует 15 минут и только пока пароль и адрес остаются прежними, поэтому срабатывает один раз. Установка нового пароля снимает блокировку и завершает все сессии пользователя; с --confirmable она также отзывает ожидающий новый адрес (Подтверждение адресов).

  • Письмо отправляет поток заданий с настройками CYBERTRAIN_SMTP_* (Отправка электронной почты): нужны процесс, выполняющий задания, и база данных.
  • Страница ссылки отвечает с Referrer-Policy: no-referrer, а журнал запросов фреймворка пишет токен как [FILTERED].
  • Десять запросов на адрес клиента каждые три минуты.

Ссылка начинается с настройки base_url, которую генератор объявляет в config/app.rb, из <APP>_BASE_URL (BLOG_BASE_URL=https://blog.example.com). Задайте её с https везде, где работает приложение. Если она не задана, ссылка берёт адрес, на который пришёл запрос, только когда заголовок Host проверяется (в разработке или при заданном CYBERTRAIN_HOSTS) или в тестах; в остальных случаях письмо не отправляется, журнал пишет ERROR [<request id>] password reset mail not sent: set <APP>_BASE_URL (or CYBERTRAIN_HOSTS), а страница отвечает как обычно. Поддельный Host никогда не попадает в ссылку.

Подтверждение адресов

С --confirmable регистрация отправляет на адрес письмо со ссылкой и никого не впускает. Верный пароль для ещё не подтверждённого адреса отвергается своим сообщением (неверный получает обычное), а страница входа ссылается на форму, которая отправляет ссылку повторно. Открытие ссылки (/confirmations/<token>, действует три дня, один раз) подтверждает адрес; затем пользователь входит. start_new_session_for в concern тоже отказывает неподтверждённому пользователю, какой бы контроллер его ни вызвал, и пишет в журнал WARN [<request id>] no session started: user <id> has not confirmed its address. Эта проверка находится в concern, который генератор пишет с --confirmable: в новом приложении и при обновлении с 0.4, где concern — новый файл. Приложение, в котором concern уже есть, получает проверку в виде diff (Подтверждение адресов позже).

Новый адрес на странице учётной записи ждёт в unconfirmed_email и занимает место старого, когда открывают его собственную ссылку; страница может отозвать его (DELETE /account/pending_email), и эта ссылка перестаёт работать. Пользователи, созданные командой пользователя и через /setup, подтверждены. Сброс пароля подтверждает учётную запись, которая никогда не была подтверждена (ссылка доказала доступ к почтовому ящику), но никогда — ожидающий новый адрес: он отзывает этот адрес, и его ссылка перестаёт работать, ведь тот, кто его запросил, может оказаться тем, у кого владелец возвращает учётную запись. Владелец затем запрашивает его снова. Новый пароль на странице учётной записи оставляет ожидающий адрес (пользователь там и видит его).

Страница учётной записи

/account/edit («Account» в навигации) меняет адрес или пароль, каждое только с текущим паролем, и удаляет учётную запись (вместе с её сессиями, в одной транзакции) только с паролем. Новый пароль завершает все сессии пользователя и снова впускает этот браузер, с прежним выбором «оставаться в системе». Изменения и удаление учётной записи (а значит, и неверные текущие пароли) ограничены десятью каждые три минуты на адрес клиента и на пользователя, а неверный текущий пароль не учитывается в блокировке.

Администраторы и страница заданий

users.admin (false) задаётся командой ./<app> user admin EMAIL. require_admin из concern отвечает 404, если вошедший пользователь не администратор:

app/controllers/concerns/admin_gate.rb (фрагмент, examples/blog)ruby
module AdminGate
  extend ActiveSupport::Concern

  included do
    before_action :require_admin
  end
end

Генератор рисует за ним страницу заданий вместо комментария, который пишет cybertrain new:

config/routes.rb (фрагмент)ruby
jobs_page "/admin/jobs", before_action: :require_admin, skip_before_action: :require_authentication
  • На странице заданий require_admin выполняется один, так что посетитель получает 404, будто страницы нет. В контроллере, который сам объявляет before_action :require_admin, первым выполняется require_authentication (порядок Rails), так что посетитель отправляется входить (303), а вошедший не-администратор получает 404.
  • gen отвергает skip_before_action: без before_action: и такой, что называет сам before_action:: и то и другое открыло бы страницу всем.
  • Строка jobs_page, которую приложение написало само, остаётся как есть. Строка, в которой уже есть skip_before_action: :require_authentication, считается нарисованной; для любой другой генератор подскажет добавить его. Чтобы получить 404, сделайте строку такой: jobs_page "...", before_action: :require_admin, skip_before_action: :require_authentication (gen отвергает пропуск без before_action:).
  • Когда ApplicationController сам определяет require_admin, этот метод занимает место метода concern во всех контроллерах. Генератор сообщает об этом, вставляя include Authentication (warn app/controllers/application_controller.rb defines require_admin itself: ...), и рисует страницу заданий без пропуска (jobs_page "/admin/jobs", before_action: :require_admin), так что и там require_authentication выполняется перед ним. Удалите метод, чтобы использовать метод concern.
  • Упавшее или отброшенное почтовое задание хранит письмо в своей строке, а страница заданий показывает аргументы строки: администратор может прочитать там ссылку сброса или подтверждения, пока она действует. Страница только для администраторов, которые и так могут действовать с любой учётной записью.
  • /setup и команда пользователя создают обычных пользователей; сделайте первого администратором командой ./<app> user admin EMAIL.

Что остаётся приложению

Это выборы, которые делает сгенерированный код, у каждого своя причина:

  • Неверный пароль для существующей незаблокированной учётной записи один раз записывает её строку (счётчик); неизвестный адрес и заблокированная учётная запись — нет. Эта одна запись даёт разницу во времени, принятую, как в lockable из Devise: такие же записи для неизвестных адресов добавили бы нагрузку ради сигнала, который уже ограничивает лимит частоты. У формы сброса пароля такая же разница: известный адрес ставит письмо в очередь — на одну строку больше.
  • Письма регистрации, сброса и подтверждения ограничены только по адресу клиента, а не по адресу получателя: кто-то может слать письма на адрес с этой частотой. Вход ограничен десятью попытками каждые три минуты на адрес клиента — это порог блокировки, — так что один клиент может держать известную учётную запись заблокированной. Ограничение по адресу (rate_limit ... by:) и более длинное окно добавляет приложение.
  • Старый адрес не уведомляется о смене адреса, ожидающий новый адрес никогда не истекает (его ссылка истекает, а сброс пароля отзывает его), а никогда не подтверждённая учётная запись никогда не удаляется.
  • "has already been taken" на странице учётной записи сообщает вошедшему пользователю, указавшему текущий пароль, что адрес зарегистрирован (как в Devise), в пределах ограничения частоты этой страницы.

Детали, которые даёт фреймворк

Сгенерированный код собран из API фреймворка, которым можно пользоваться и отдельно:

API Что делает
Cybertrain::Password дайджесты PBKDF2-HMAC-SHA256: hash, verify?, verify_serialized, dummy_digest, needs_rehash?, session_key, session_key_matches? (docs/design.md D25)
Cybertrain::Token issue(purpose, id, expires_in, bound_to) даёт "<id>--<expires>--<hmac>"; id_from(token); valid?(token, purpose, bound_to)
Cybertrain::MailMessage то, что возвращает метод почтовика: deliver_later (задание) или deliver_now
Session#restart_lifetime!, stamp_lifetime!(seconds, persistent) собственный срок входа и cookie на сеанс браузера
Relation#update_all_sql(sql, binds) UPDATE ... SET <sql> для подходящих строк
Controller.allow_unauthenticated_access, skip_before_action открыть действия посетителям
Controller#safe_redirect_path(text, fallback) локальный путь из запроса или запасной
ParameterFilter.filter_path(path) путь, в котором сегменты в форме токена записаны как [FILTERED]
check_box_tag(name, value = "1", checked = false) флажок без скрытого поля

Вход, написанный вручную, использует Password, как сгенерированный User: Cybertrain::Password.verify_serialized(password, user.nil? ? Cybertrain::Password.dummy_digest : user.password_digest) проверяет в процессе по одному паролю за раз (проверка занимает около 0,2 с процессорного времени) и для неизвестного адреса длится столько же; session[:password_key] = Cybertrain::Password.session_key(user.password_digest) при входе, проверяемый через session_key_matches? в каждом запросе, завершает сеанс браузера после смены пароля.

Token.valid? проверяет токен по переданному bound_to, поэтому сначала найдите запись по Token.id_from и проверяйте по её собственному значению, как это делает User.find_by_password_reset_token.

Тестирование

Генератор записывает тестовые классы в духе Rails, которые запускает cybertrain test (Тестирование приложения):

Файл Что проверяет
test/fixtures/users.yml one (администратор) и two, пароль которых "password" (с --confirmable оба подтверждены)
test/support/session_test_helper.rb sign_in_as(user, remember: false), sign_out, open_session (второй браузер) и authenticity_token_in(body) (токен первой формы страницы, для запросов внутри with_forgery_protection), которые test/test_helper.rb включает в каждый интеграционный тест
test/models/user_test.rb формат адреса
test/controllers/sessions_controller_test.rb вход и выход
test/controllers/registrations_controller_test.rb регистрацию (не с --invite-only)
test/integration/first_run_test.rb /setup и команду user (с --invite-only)
test/controllers/passwords_controller_test.rb сброс, его письмо и ссылку
test/controllers/accounts_controller_test.rb страницу аккаунта
test/controllers/confirmations_controller_test.rb подтверждение (с --confirmable)
test/integration/remember_me_test.rb 15-й и 30-й день, предел бездействия
test/integration/lockout_test.rb блокировку и её час
test/integration/admin_test.rb require_admin, user admin

Время сдвигается через travel_to и travel (никакие строки не переносятся назад во времени), а письма читаются из Cybertrain::Mailer.deliveries через assert_emails и perform_enqueued_jobs. Скаффолд, сгенерированный после аутентификации, выполняет вход users(:one) в начале своего теста контроллера; сгенерированный до неё — нет, поэтому добавьте в его setup sign_in_as users(:one). При повторном запуске в приложении, тесты которого написал прежний генератор (test/authentication.rb, admin.rb, remember_me.rb, lockout.rb, passwords.rb, accounts.rb, confirmations.rb, test/support/app_test.rb, test/support/authentication_helpers.rb), генератор называет каждый вместе с файлом, который его заменяет; --force их удаляет.

script/auth-e2e signup invite confirmable upgrade04 в этом репозитории собирает приложения генератором и прогоняет их от начала до конца.

Обновление с 0.4

Запустите генератор ещё раз в приложении, сгенерированном 0.4. Он пишет недостающие файлы, миграцию со столбцами, которых нет в существующих миграциях, и правки; для каждого файла, который он записал бы целиком, но который существует с другим содержимым, он ничего не меняет и печатает diff:

вывод — cybertrain generate authentication (фрагмент)text
exist db/migrate/20260925120000_create_users.rb
create db/migrate/20260925120002_add_authentication_columns.rb
manual  app/models/user.rb (diff below)
create app/controllers/concerns/authentication.rb
manual  app/controllers/sessions_controller.rb (diff below)
create app/controllers/passwords_controller.rb
...
manual  app/controllers/application_controller.rb (diff below)
...
manual  app/controllers/application_controller.rb: apply this diff by hand, or re-run with --force to overwrite the file
--- a/app/controllers/application_controller.rb
+++ b/app/controllers/application_controller.rb
@@ -1,95 +1,5 @@
 class ApplicationController < Cybertrain::Controller
-  # ---- Authentication (cybertrain generate authentication) -------------
-  # Every action needs a signed-in user unless its controller opens it:
...
-  # ---- end of authentication ------------------------------------------
+  include Authentication

test/fixtures/auth_04_app.upgrade.diff — полный вывод для приложения с регистрацией, сгенерированного 0.4.

  • Сохраните вывод и примените его командой patch -p1 из каталога приложения (patch пропускает строки, не входящие в diff), или примените каждый diff вручную там, где вы меняли файл. Пока они не применены, приложение может не собираться: новые файлы вызывают то, что добавляют diff-ы.
  • --force вместо этого записывает новые файлы поверх старых — для файлов, которые вы никогда не правили; блок 0.4 в ApplicationController заменяется, только если он ровно такой, каким его написал 0.4.
  • Новая миграция добавляет только недостающие столбцы; выполните cybertrain db migrate. С --confirmable она также считает уже существующих пользователей подтверждёнными (с момента создания), иначе ни один из них не смог бы войти.
  • С --confirmable diff-ы контроллеров sessions и registrations несут строку IMPORTANT:: пока они не применены, неподтверждённой учётной записи не объясняют, почему она не может войти, а при регистрации ссылка не отправляется. В приложении 0.4 concern — новый файл, записанный вместе с проверкой подтверждения, так что он по-прежнему не начинает сессию для неподтверждённой учётной записи (и пишет в журнал WARN [<request id>] no session started: user <id> has not confirmed its address), даже если эти diff-ы так и не применят.
  • При обновлении каждая сессия один раз заканчивается (cookie теперь зашифрован), и остальное из Обновления приложения с 0.4 тоже применимо.

Подтверждение адресов позже

Запустите cybertrain generate authentication --confirmable (с --invite-only, если оно есть у приложения) в приложении, сгенерированном без него. Он пишет файлы подтверждения и миграцию с добавлением столбцов, которая считает уже существующих пользователей подтверждёнными, и печатает diff для каждого файла, написанного им раньше. Здесь concern уже есть, поэтому его проверка подтверждения приходит одним из этих diff-ов, и вывод помечает его IMPORTANT:: пока diff concern не применён, неподтверждённые учётные записи входят, что бы ни говорили остальные diff-ы. Примените его и diff контроллера sessions до развёртывания. С --invite-only помечен и diff контроллера setup: пока он не применён, первый пользователь, которого создаёт /setup, не подтверждён и не может войти (сброс пароля подтверждает его).