QDBAuth Administrator User Guide

Audience: anyone with admin-role access to QDBAuth's own dashboard, who creates/manages accounts for the QDB ecosystem's sites (CMS, TD, QDB admin, migration tool).

Prerequisites: an existing admin account (role admin, is_admin=1), and at least one site registered under Manage Sites if you plan to grant site access to new users.

Log in

Go to /login/ with no return_url — this is the direct path into QDBAuth's own dashboard (as opposed to a consuming app redirecting here for SSO). Email + password, then a TOTP code from your authenticator app. On success you land on /dashboard/.

Create a single user

1. Dashboard → Users → Create user.
2. Fill in first name, last name, email, and a placeholder password (the new user will replace this themselves during signup verification).
3. Check the Sites to grant box(es). If TD is checked, the Role dropdown automatically switches to TD's own 5 roles (Developer, Support, Dev Lead, Support Lead, Super Admin) instead of the default admin/developer/user list — this happens live in the form, no page reload.
4. Submit. One verification email is sent per granted site (or one if no site was granted). Each email lets that person independently set their own password and scan a QR code for that specific site's authenticator entry — completing one site's setup does not affect the others.

Bulk-create users from a file

1. Dashboard → Users → Bulk user management → upload a .csv or .xlsx with header row first_name, last_name, email, password, role, sites.
2. sites is semicolon-separated (e.g. CMS;QDB admin) and must match existing site_name values exactly — unknown names are silently dropped.
3. role must be valid for whichever site(s) that row grants (e.g. a TD-only row needs one of TD's 5 roles, not admin/developer/user) — an invalid role falls back to that group's default rather than failing the whole row.
4. A sample CSV is downloadable from the same page as a starting template.
5. Rows with missing required fields or an already-used email are skipped and listed as errors after upload — everything else in the file still gets created.

Reset a user's password

1. Dashboard → Users → edit icon on their row.
2. If the account has per-site credentials, a site selector appears above the password field — pick which site's password you're resetting (each site has its own). Accounts without per-site credentials (legacy accounts) just show a single reset field, no site picker.
3. Enter the new password and click Reset. The user gets an email confirming their password was changed (so they notice if it wasn't them).

Manage sites

Dashboard → Manage sites: add a site (site_name + site_url), toggle a site active/inactive, or delete one. site_url is used to auto-match a consuming app's SSO return_url back to a site name, and (for accounts with per-site credentials) to build each verification email's destination link.

Deactivate / delete a user

Toggling a user inactive immediately revokes all of their refresh tokens (they can't silently keep using an already-issued token) and blocks future logins, without deleting their data. Deleting is permanent and cannot target your own logged-in account.

Troubleshooting

"Table 'qdb.user_site_credentials' doesn't exist" when creating a user — the per-site credentials database migration (db/create_user_site_credentials_table.sql) hasn't been run against the live database yet. Run it once; it's a single CREATE TABLE, safe to run anytime.

A second/third site's verification link says "already verified" — this was the original (fixed) behavior for accounts sharing one credential across sites. If it still happens on a NEW account, check whether that account actually has rows in user_site_credentials (new-style) — if it doesn't (legacy), that's expected: legacy accounts intentionally share one credential.

A consuming app gets 401 on every call — check its X-QDB-Client-Secret header value matches QDB_SSO_SHARED_SECRET exactly.

"Invalid email or password" for a real account — for new-style (per-site) accounts, confirm the site value the consuming app sends matches a registered site_name exactly; a mismatch falls through to the account's siteless credential (if any), which won't match a site-specific password.

Verification

After creating a test user: confirm the verification email(s) arrive, that each one's QR code / password-set flow works end to end, and that the person can subsequently log in through whichever consuming app(s) they were granted.