Generating it
cybertrain generate authentication # a public sign-up page
cybertrain generate authentication --invite-only # no sign-up: users come from the command line or /setup
cybertrain generate authentication --confirmable # (either mode) new addresses confirm by mail
cybertrain db migrate
It writes, in the application:
| Files | What they are |
|---|---|
db/migrate/*_create_users.rb, *_create_sessions.rb |
users (email_address, password_digest, admin, failed_attempts, locked_until; with --confirmable confirmed_at, unconfirmed_email) and sessions (one row per signed-in browser, with remember and last_active_at) |
app/models/user.rb, session.rb |
password=, authenticate, User.authenticate_by, the tokens, the lockout |
app/controllers/concerns/authentication.rb |
the Authentication concern, included into ApplicationController |
sessions_controller.rb, registrations_controller.rb (or setup_controller.rb), passwords_controller.rb, accounts_controller.rb, confirmations_controller.rb |
sign-in, sign-up (or the first user's page), password reset, the account page, confirmation |
app/mailers/passwords_mailer.rb, confirmations_mailer.rb |
the mails |
app/commands/user_command.rb |
./<app> user ..., required from bin/<app>.rb |
app/views/... |
the screens, every text through t(), and the sessions/_nav partial |
test/fixtures/users.yml, test/support/session_test_helper.rb, test/models/, test/controllers/, test/integration/ |
the fixture users, sign_in_as, and tests for each part (Testing) |
and edits, once each: include Authentication in ApplicationController,
the routes, the jobs page's line (Admin users),
the nav partial in the layout, the user command in bin/<app>.rb, the
base_url setting in config/app.rb (Links in mails),
and in bin/<app>.rb and bin/db.rb the lines of the subsystems the code
uses, unless require "cybertrain" loads them all already:
cybertrain/jobs, cybertrain/mailer, cybertrain/mailer/later and
cybertrain/rate_limit (Subsystems).
Running it again with the same options changes nothing: an edit already
made is found and skipped, and a file already as it would write it is
left. A file it would write differently (one you edited, or one an older
generator or other options wrote) is never overwritten without --force:
its diff is printed instead (Upgrading from 0.4,
Turning on confirmation later).
The texts of the generated screens are in the framework's English and
Japanese dictionaries, under their lazy keys (sessions.new.title,
passwords.create.sent); an application overrides them, or adds a
language, in config/locales/ (Internationalization).
Signing in and out
module Authentication
extend ActiveSupport::Concern
included do
before_action :resume_session
before_action :require_authentication
helper_method :authenticated?
end
From then on every action needs a signed-in user, and a visitor is sent to
/session/new (a 303; a GET is remembered and returned to after sign-in,
if it is a local path). A controller opens actions to visitors as in Rails:
class ArticlesController < ApplicationController
allow_unauthenticated_access only: [:index, :show]
allow_unauthenticated_access(only:, except:) is a method of
Cybertrain::Controller, a skip_before_action :require_authentication.
resume_session still runs on open pages, so a template reads
@current_user (and @current_session), or calls authenticated?. There
is no Current object.
SessionsController(resource :session):GET /session/new,POST /session,DELETE /session. Sign-in attempts are limited to ten per client address every three minutes, counted in the cache, so every process counts together; behind a proxy, set trusted proxies.- A wrong password, an unknown address and a locked account get the same message after the same password check (against a dummy digest when there is no account).
resume_sessionends a sign-in (and deletes its Session row) once the password changed since, after its lifetime, or afterauth_idle_timeoutwithout a request (Remember me).- Signing out deletes the Session row and empties the cookie session.
Sign-up, or invite-only
By default the generator writes RegistrationsController (/sign_up),
which creates a user and signs them in. Rails' generator has no sign-up
page and leaves the first user to the console; CyberTrain has no Ruby
console, so it writes one. Sign-ups are limited to ten per client address
every three minutes, as sign-ins are: each one hashes a password, may mail
a link, and its "has already been taken" tells whether an address is
registered.
Every address the generated code saves, from the sign-up page, /setup,
the account page and the user command, must be one address:
User.email_address_format? asks for exactly one @ with text on both
sides, and no comma, whitespace, angle bracket or control character. The
mailer reads ann@example.com,eve@evil.example as two recipients, so
without the check one account could hold two mailboxes, have its reset
link mailed to both and, with --confirmable, be confirmed by either.
The address must also pass the mailer's own check
(Cybertrain::Mailer.address_problem): plain ASCII only, so no Unicode
space or control character either, none of ( ) [ ] ; : \ ", a local
part of at most 64 bytes and at most 254 bytes in all. An address the
mailer would refuse could be saved but never sent a mail, so it is
refused when it is entered. Some addresses the mail standards allow are
refused too (a quoted local part with a space or a comma in it, a
non-ASCII address); the method is the application's to change. An
address saved before the check existed is not checked again, so its
account can still be reset and signed in to.
--invite-only writes no sign-up page, the right default for an internal
tool, where whoever reaches the server first would otherwise get an
account. The first user comes from the user command, or from
SetupController (GET and POST /setup), which creates the user and
signs them in:
- It answers only while no user exists, only with the one-time token, and
only to a connection whose socket peer is the loopback address and that
carries no
X-Forwarded-Forheader (a proxy on the same host makes every request a loopback one, and adds that header). Everyone else gets a 404. - The token is 32 random hex characters made when the program starts
(
SetupController.setup_token), compared in constant time. It keeps the page closed where the address check cannot, behind a proxy that adds noX-Forwarded-For. The request log shows it as[FILTERED]. - While no user exists, the server logs
WARN no user exists yet: run ./<app> user EMAIL, or open /setup?token=<token> from this machinebefore it boots; that line is the only place the token is printed. <APP>_SETUP_OPEN=1(thesetup_opensetting inconfig/app.rb) lifts the address check, never the token, for a first run behind a proxy on another host. Unset it once the user exists.
The user command
./<app> user is written in both modes:
./blog user ann@example.com # create, or set the password; it is read from stdin
printf '%s' "$PASSWORD" | ./blog user ann@example.com
./blog user admin ann@example.com # make an admin
./blog user unadmin ann@example.com
Without a password argument it reads one line of standard input (prompting
on a terminal; the typing is echoed), which keeps the password out of ps
and the shell history. Setting a password signs that user's browsers out
and clears a lockout. With --confirmable, the users it creates are
confirmed. It prints created, updated, admin or unadmin and the
address and exits 0, or prints the usage or an error and exits 1.
Remember me and session limits
The sign-in form has a "Keep me signed in" box (check_box_tag
:remember_me). A sign-in lasts:
| Checked | Unchecked | |
|---|---|---|
| The Session row and the cookie end after | auth_remember_for (30 days) |
session_absolute_max_age (two weeks) |
| The cookie | Max-Age of the time left |
no Max-Age and no Expires: it ends with the browser |
Unused for auth_idle_timeout (7 days; 0 turns it off) |
ends | ends |
last_active_at is written at most once a minute. The generated
start_new_session_for(user, remember:) calls session.restart_lifetime!,
then session.stamp_lifetime!(seconds, persistent), in that order: a
restart clears the stamp. The limit it stamps is never 0: with
session_absolute_max_age = 0 an unremembered sign-in lasts
session_max_age, or two weeks. The settings are in
Configuration.
Lockout
auth_lockout_attempts (10) wrong passwords lock the account for
auth_lockout_period (an hour). A locked account answers the
wrong-password message, whatever the password. A successful sign-in, a
password reset and ./<app> user EMAIL clear the count;
auth_lockout_attempts = 0 turns lockout off and stops enforcing a lock
made before. The count is one UPDATE that reads the row as it is
(Relation#update_all_sql), so sign-ins at the same moment all count. The
per-client-address rate limit stays.
Password reset
The sign-in page links to /passwords/new. The address form always
answers "If that address is registered, a link to reset the password was
sent to it.", after the same work for an unknown address short of sending.
The mail (PasswordsMailer.reset(user, url).deliver_later, in the
request's language) carries /passwords/<token>/edit; the token is valid
for 15 minutes and only while the password and the address stay as they
were, so it works once. Setting the new password clears a lockout and ends
every session of the user; with --confirmable it also withdraws a new
address waiting (Confirming addresses).
- The mail is sent by a job thread with the
CYBERTRAIN_SMTP_*settings (Sending e-mail): a process that runs jobs, and the database, are needed. - The link's page answers
Referrer-Policy: no-referrer, and the framework's request log writes the token as[FILTERED]. - Ten requests per client address every three minutes.
Links in mails
A link starts with the base_url setting the generator declares in
config/app.rb, from <APP>_BASE_URL (BLOG_BASE_URL=https://blog.example.com).
Set it, with https, wherever the application is served. Unset, the link
takes the address the request came to only when the Host header is
checked (development, or CYBERTRAIN_HOSTS set) or in tests; anywhere
else no mail is sent, the log says ERROR [<request id>] password reset mail not sent:
set <APP>_BASE_URL (or CYBERTRAIN_HOSTS), and the page answers as usual. A
forged Host never reaches a link.
Confirming addresses
With --confirmable, a sign-up mails a link to the address and signs
nobody in. The right password for an address not confirmed yet is refused
with its own message (a wrong one gets the usual message), and the sign-in
page links to a form that mails the link again. Opening the link
(/confirmations/<token>, valid for three days, once) confirms the
address; the user then signs in. The concern's start_new_session_for
refuses an unconfirmed user too, whichever controller asks, and logs
WARN [<request id>] no session started: user <id> has not confirmed its address. That
check is in the concern the generator writes with --confirmable: in a
new application, and in a 0.4 upgrade, where the concern is a new file.
An application that already has the concern gets the check as a diff
(Turning on confirmation later).
A new address on the account page waits in unconfirmed_email, and takes
the old one's place when its own link is opened; the page can withdraw it
(DELETE /account/pending_email), which ends that link. Users made by the
user command and by /setup are confirmed. A password reset confirms an
account that was never confirmed (the link proved the mailbox), never a
new address waiting: it withdraws that address, which ends its link,
since whoever asked for it may be the one the owner is taking the account
back from. The owner asks for it again afterwards. A new password on the
account page keeps the address waiting (the user is there and sees it).
The account page
/account/edit (the nav's "Account") changes the address or the password,
each only with the current password, and deletes the account (with its
sessions, in one transaction) only with the password. A new password ends
every session of the user and signs this browser in again, remembered as
it was. Account changes and deletions (so also wrong current passwords)
are limited to ten every three minutes per client address and per user,
and a wrong current password does not count toward lockout.
Admin users and the jobs page
users.admin (false) is set with ./<app> user admin EMAIL. The concern's
require_admin answers 404 unless the signed-in user is an admin:
module AdminGate
extend ActiveSupport::Concern
included do
before_action :require_admin
end
end
The generator draws the jobs page behind it, in place of the comment
cybertrain new writes:
jobs_page "/admin/jobs", before_action: :require_admin, skip_before_action: :require_authentication
- On the jobs page
require_adminruns alone, so a visitor gets the 404, as if there were no page. In a controller that declaresbefore_action :require_adminitself,require_authenticationruns first (Rails' order), so a visitor is sent to sign in (303) and a signed-in non-admin gets the 404. - gen refuses a
skip_before_action:without abefore_action:, and one that names thebefore_action:itself: either would open the page to everyone. - A
jobs_pageline the application wrote itself is left alone. One that already hasskip_before_action: :require_authenticationcounts as drawn; for any other, the generator says to add it. Make the line readjobs_page "...", before_action: :require_admin, skip_before_action: :require_authenticationfor the 404 (gen refuses the skip without thebefore_action:). - When
ApplicationControllerdefinesrequire_adminitself, that method takes the concern's place in every controller. The generator says so as it insertsinclude Authentication(warn app/controllers/application_controller.rb defines require_admin itself: ...), and draws the jobs page without the skip (jobs_page "/admin/jobs", before_action: :require_admin), sorequire_authenticationruns before it there too. Delete the method to use the concern's. - A failed or discarded mail job keeps the mail in its row, and the jobs page shows the row's arguments: an admin can read a reset or confirmation link there while it is valid. The page is for admins only, who can act on any account already.
/setupand the user command make ordinary users; make the first one an admin with./<app> user admin EMAIL.
What is left to the application
These are choices the generated code makes, each with its reason:
- A wrong password for an existing, unlocked account writes its row once (the count); an unknown address and a locked account do not. That one write is a timing difference, accepted as in Devise's lockable: equal writes for unknown addresses would add load for a signal the rate limit already bounds. The password reset form has the same kind of difference: a known address queues its mail, one row more.
- Sign-up, reset and confirmation mails are limited per client address
only, not per address mailed: someone can mail an address at that rate.
Sign-ins are limited to ten every three minutes per client address, the
lockout threshold, so one client can keep a known account locked. A
per-address limit (
rate_limit ... by:) and a longer window are the application's to add. - The old address is not told of an address change, a new address waiting never expires (its link does, and a password reset withdraws it), and an account never confirmed is never deleted.
- The account page's "has already been taken" tells a signed-in user, who gave the current password, that an address is registered (as Devise does), within the page's rate limit.
The pieces the framework provides
The generated code is built from framework API, usable on its own:
| API | What it does |
|---|---|
Cybertrain::Password |
PBKDF2-HMAC-SHA256 digests: 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) gives "<id>--<expires>--<hmac>"; id_from(token); valid?(token, purpose, bound_to) |
Cybertrain::MailMessage |
what a mailer method returns: deliver_later (a job) or deliver_now |
Session#restart_lifetime!, stamp_lifetime!(seconds, persistent) |
a sign-in's own lifetime and a browser-session cookie |
Relation#update_all_sql(sql, binds) |
UPDATE ... SET <sql> on the matching rows |
Controller.allow_unauthenticated_access, skip_before_action |
open actions to visitors |
Controller#safe_redirect_path(text, fallback) |
a local path from the request, or the fallback |
ParameterFilter.filter_path(path) |
a path with token-shaped segments as [FILTERED] |
check_box_tag(name, value = "1", checked = false) |
a checkbox with no hidden field |
A hand-written sign-in uses Password as the generated User does:
Cybertrain::Password.verify_serialized(password, user.nil? ?
Cybertrain::Password.dummy_digest : user.password_digest) checks one
password at a time per process (a check takes about 0.2 s of CPU) and
takes as long for an unknown address; session[:password_key] =
Cybertrain::Password.session_key(user.password_digest) at sign-in, checked
with session_key_matches? on each request, signs a browser out once the
password changes.
Token.valid? checks a token against the bound_to given, so look the
record up by Token.id_from first and check against that record's own
value, as User.find_by_password_reset_token does.
Testing
The generator writes Rails-shaped test classes, which cybertrain test
runs (Testing an app):
| File | What it tests |
|---|---|
test/fixtures/users.yml |
one (an admin) and two, whose password is "password" (with --confirmable, both confirmed) |
test/support/session_test_helper.rb |
sign_in_as(user, remember: false), sign_out, open_session (a second browser) and authenticity_token_in(body) (the token of a page's first form, for requests inside with_forgery_protection), included into every integration test by test/test_helper.rb |
test/models/user_test.rb |
the address format |
test/controllers/sessions_controller_test.rb |
sign-in and sign-out |
test/controllers/registrations_controller_test.rb |
sign-up (not with --invite-only) |
test/integration/first_run_test.rb |
/setup and the user command (with --invite-only) |
test/controllers/passwords_controller_test.rb |
the reset, its mail and its link |
test/controllers/accounts_controller_test.rb |
the account page |
test/controllers/confirmations_controller_test.rb |
confirmation (with --confirmable) |
test/integration/remember_me_test.rb |
day 15 and day 30, the idle limit |
test/integration/lockout_test.rb |
the lock and its hour |
test/integration/admin_test.rb |
require_admin, user admin |
Time moves with travel_to and travel (no row is moved back in time),
and mail is read from Cybertrain::Mailer.deliveries with assert_emails
and perform_enqueued_jobs. A scaffold generated after authentication
signs users(:one) in at the top of its controller test; one generated
before it does not, so add sign_in_as users(:one) to its setup. Run
again over an application whose tests an earlier generator wrote
(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), the
generator names each with the file that replaces it; --force deletes
them.
script/auth-e2e signup invite confirmable upgrade04 in this repository
builds applications with the generator and drives them from end to end.
Upgrading from 0.4
Run the generator again in an application 0.4 generated. It writes the files that are missing, a migration with the columns the existing ones lack, and the edits; for each file it would write whole that exists with other content, it changes nothing and prints a 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 is the whole output for a sign-up application 0.4 generated.
- Save the output and apply it with
patch -p1from the application's directory (patch skips the lines that are not part of a diff), or apply each diff by hand where you changed the file. The application may not build until they are applied: the new files call what the diffs add. --forcewrites the new files over the old ones instead, for files you never edited; 0.4's block inApplicationControlleris replaced only when it is exactly as 0.4 wrote it.- The new migration adds only the columns that are missing; run
cybertrain db migrate. With--confirmableit also counts the users already there as confirmed (since they were created), or none of them could sign in. - With
--confirmable, the diffs of the sessions and registrations controllers carry anIMPORTANT:line: until they are applied, an unconfirmed account is not told why it cannot sign in, and a sign-up is mailed no link. In a 0.4 application the concern is a new file, written with its confirmation check, so it still starts no session for an unconfirmed account (and logsWARN [<request id>] no session started: user <id> has not confirmed its address) even if those diffs are never applied. - Every session ends once at the upgrade (the cookie is encrypted now), and the rest of Upgrading an application from 0.4 applies too.
Turning on confirmation later
Run cybertrain generate authentication --confirmable (with
--invite-only if the application has it) in an application generated
without it. It writes the confirmation files and an add-columns migration,
which counts the users already there as confirmed, and prints a diff for
each file it wrote before. Here the concern exists, so its confirmation
check arrives as one of those diffs, and the output marks it IMPORTANT::
until the concern's diff is applied, unconfirmed accounts sign in,
whatever the other diffs say. Apply it, and the sessions controller's,
before deploying. With --invite-only, the setup controller's diff is
marked too: until it is applied, the first user /setup creates is not
confirmed and cannot sign in (a password reset confirms it).