Генерация
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/ (Интернационализация).
Вход и выход
module Authentication
extend ActiveSupport::Concern
included do
before_action :resume_session
before_action :require_authentication
helper_method :authenticated?
end
С этого момента каждое действие требует вошедшего пользователя, а посетитель отправляется на /session/new (303; GET запоминается и возвращается после входа, если это локальный путь). Контроллер открывает действия посетителям, как в Rails:
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 пишется в обоих режимах:
./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, если вошедший пользователь не администратор:
module AdminGate
extend ActiveSupport::Concern
included do
before_action :require_admin
end
end
Генератор рисует за ним страницу заданий вместо комментария, который пишет cybertrain new:
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:
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она также считает уже существующих пользователей подтверждёнными (с момента создания), иначе ни один из них не смог бы войти. - С
--confirmablediff-ы контроллеров 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, не подтверждён и не может войти (сброс пароля подтверждает его).