Upgrading to v0.26.19
v0.26.19 moves the authentication library, Rodauth, from 2.45 to 2.48, which closes an upstream passkey sign-in account takeover. In full mode, closing an account now deletes its sign-in record and its authentication audit log. Commands using the shared bin/ots write gate are dry runs unless you pass --apply; other commands retain their own behavior. No migration runs and rollback is a tag swap.
If you are upgrading from v0.26.17 or earlier, follow the v0.26.18 guide first: it has a migration.
Before You Start
Section titled “Before You Start”- Record the tag you are running now.
- Note your
AUTHENTICATION_MODE(see Simple or full auth) and whetherAUTH_WEBAUTHN_ENABLED=true. Most steps below apply to full mode only. - List the scripts, cron jobs and runbooks that call
bin/ots.
What Changes
Section titled “What Changes”| Area | Change | Action required? |
|---|---|---|
| Passkey sign-in | Rodauth 2.46 fix: a signed-in session could use passkey login to sign in as another account | Upgrade promptly if AUTH_WEBAUTHN_ENABLED=true |
| Account closure (full mode) | Deletes the accounts row and all of its account_authentication_audit_logs rows |
Export the audit log before upgrading |
| Closed accounts from earlier versions | New bin/ots customers prune-closed-accounts |
Optional, later (full mode) |
bin/ots write-gated commands |
Need --apply to write; no prompts; a piped y no longer confirms |
Update scripts for the affected commands |
| Sign-in routes | A signed-in browser gets 403 “Already logged in” on sign-in, signup, verify and magic-link routes | None |
| Organization members | Removing a member clears their default organization when it names that organization | Optional cleanup for earlier removals |
| Receipt and burn API | Burn returns the receipt after the burn; share_url is null once the secret is gone |
Only if you script against it |
| Frontend | Routes and languages load as separate chunks; open tabs reload once after the deploy | None |
| Expiration warnings | Now delivered when the job system runs | Only if expiration_warnings.enabled: true |
| SAML | An EntityID containing {…} is refused |
Only if you use one |
The Upgrade Checklist
Section titled “The Upgrade Checklist”-
Full mode: export the authentication audit log before upgrading. From v0.26.19 on, each closure deletes that account’s rows in the same transaction. The export is also the record you need if you later review past passkey sign-ins. Schedule it from now on if you keep this history.
Terminal window (umask 077; psql "$AUTH_DATABASE_URL" -c "\copy account_authentication_audit_logs TO 'auth-audit-$(date +%F).csv' CSV HEADER")On SQLite, the default, the database is the file named by
AUTH_DATABASE_URL. The defaultsqlite://data/auth.dbisdata/auth.dbin the application directory; if you set another path, use that file in the commands below. On a bare-metal install, install thesqlite3command-line tool if it is missing (sudo apt install sqlite3on Debian), then run this from the application directory as theonetimeuser:Terminal window (umask 077; sqlite3 -readonly -header -csv data/auth.db 'SELECT * FROM account_authentication_audit_logs;' > "auth-audit-$(date +%F).csv")The application image has no
sqlite3tool. On the shipped compose stacks, export through the application’s Ruby instead. The file is written on the host, in the directory you run the command from:Terminal window (umask 077; docker compose exec -T app bundle exec ruby -rcsv -rsqlite3 -e 'SQLite3::Database.new("data/auth.db", readonly: true).execute2("SELECT * FROM account_authentication_audit_logs") { |row| print row.to_csv }' > "auth-audit-$(date +%F).csv")Each command creates the export readable only by your user, because it contains account sign-in history. Move it to wherever you keep backups.
-
Check scripts that call
bin/ots. The shared write gate applies to commands such as membership changes and organization ownership transfers. Check each command’s--help; it is not a universal CLI switch. For example,customers createstill creates an account without--apply.Terminal window bin/ots memberships add ORG CUSTOMER --role member --apply # was organizations add-member --org … --email …bin/ots organizations doctor --all # was organizations --checkbin/ots organizations show ORG # was organizations --show, --customer, --subscriptionOn shared write-gated commands,
--yes,-yand-fare aliases for--apply. Pipingyto one of these commands previews and exits 0 without writing. Oncustomers change-emailandcustomers role reconcile,--yesand--forceare ignored: pass--apply.bin/ots memberships removeexits 1 when the removal succeeds but leaves the member’s default organization behind, and prints the repair command.purge,purge-inactive,prune-closed-accountsandfinish-closureskeep their own flags. -
Deploy v0.26.19, backend and frontend together.
-
Only if a SAML EntityID contains a placeholder such as
{tenantid}: replace it with the EntityID your IdP issues for your tenant, inSAML_IDP_ENTITY_ID(platform SAML stays off until you do) or in the custom domain’s SSO settings. -
Only if
expiration_warnings.enabled: trueand the job system runs: once no v0.26.18 process is left, delete the queue nothing reads.Terminal window rabbitmqctl delete_queue email.message.schedule
After the Upgrade: Optional Cleanup
Section titled “After the Upgrade: Optional Cleanup”These are not needed for v0.26.19 to work.
-
Default organizations left by earlier member removals. Read the report before repairing:
--repairfixes every repairable finding it lists.Terminal window bin/ots customers doctor --allbin/ots customers doctor --all --repair -
Closed accounts kept by earlier versions (full mode). If passkeys were ever enabled, wait until you have decided whether to review past passkey sign-ins: this deletes audit rows. Run it only after the export in step 1.
Terminal window bin/ots customers prune-closed-accounts # previewbin/ots customers prune-closed-accounts --confirm # deletebin/ots customers finish-closures # preview, if the prune reports interrupted closuresbin/ots customers finish-closures --confirm # purge
Verify
Section titled “Verify”- Sign in with each method you enable (password, magic link, passkey), sign out, and sign in again.
- If you enable passkeys and TOTP: sign in with a passkey on an account that also has TOTP, then add a second passkey. Both finish without an error and the session stays signed in.
- Sign up a throwaway account and verify it from the emailed link in a private window.
Config Mapping Reference
Section titled “Config Mapping Reference”New variables, all optional. See .env.reference for each.
| Variable | Default | Parsing |
|---|---|---|
ORGS_HOMEPAGE_NETWORK_RULES_UI_ENABLED |
off | only the literal true enables |
ORGS_BASE_DOMAIN_SIGNUP_ENABLED |
off | only the literal true enables |
SSO_METADATA_FETCH_RATE_LIMIT_ENABLED |
on | only the literal false disables |
SSO_METADATA_FETCH_RATE_LIMIT_MAX_PER_CUSTOMER, _WINDOW, _LOCKOUT |
30, 3600 s, 3600 s | integers |
With billing enabled, the two ORGS_ features also need the homepage_network_rules and base_domain_signup entitlements on a plan.
Troubleshooting
Section titled “Troubleshooting”“Already logged in” (403) on a verify or magic link
Section titled ““Already logged in” (403) on a verify or magic link”The browser is signed in to an account. Sign out, or open the link in a private window.
A bin/ots command prints DRY RUN — nothing was written
Section titled “A bin/ots command prints DRY RUN — nothing was written”Review the preview, then add --apply to that command if you intend to make the change.
bin/ots organizations add-member is an unknown command
Section titled “bin/ots organizations add-member is an unknown command”Use bin/ots memberships add ORG CUSTOMER --apply.
bin/ots memberships remove exits 1 after removing the member
Section titled “bin/ots memberships remove exits 1 after removing the member”The member’s default organization still names the organization. Run the customers doctor command it prints.
Platform SAML sign-in is gone after the upgrade
Section titled “Platform SAML sign-in is gone after the upgrade”SAML_IDP_ENTITY_ID contains a {…} placeholder. See step 4.
Rollback
Section titled “Rollback”Pin the tag you recorded and restart; no migration ran. If passkeys are enabled, set AUTH_WEBAUTHN_ENABLED=false before starting v0.26.18: that version is exposed to the passkey sign-in takeover this release fixes. On v0.26.18, homepage network rules and base-domain sign-up settings are ignored, so a homepage a tenant restricted is public until you return to v0.26.19. Rows deleted by closures or by prune-closed-accounts stay deleted. Avoid bin/ots customers sync-auth-accounts on v0.26.18 after a rollback: it does not read the closure marker this release writes and may give an interrupted closure a sign-in again.