Multi-User Auth & RBAC

Multi-User Authentication & Access Control

The dashboard supports multiple named users with two roles, admin and user, each signing in with a per-account Telegram one-time code (OTP). This replaced an earlier single-operator design where the dashboard had exactly one hard-coded session; see Deployment for the deploy-time sequencing and Infrastructure for the PostgreSQL container this all runs against.

Role capability matrix

Role editing, account deletion, impersonation, and public self-registration do not exist in this phase — an admin can only create a new user-role account (see Creating a user). There is no endpoint or UI path that promotes an existing account to admin.

User-owned vs. shared vs. admin-only data

Every table below carries an authoritative owner_user_id column and is scoped at the ORM chokepoint (a SQLAlchemy do_orm_execute/before_flush listener pair in arb_bot/portfolio_app/db/engine.py) plus PostgreSQL row-level security as defense-in-depth (arb_bot/auth/tenancy.py:apply_rls). No tenant context set (an anonymous or mis-scoped call) sees zero rows and cannot write — the isolation is fail-closed, never fail-open.

Login flow

1. User enters their username (not an email, not a Telegram handle) and requests a code.
2. POST /api/auth/request-otp {"username"} always returns the same generic response — whether the account exists, is inactive, or is being throttled is never revealed. If the account is real and active, a 6-digit code is sent to that user’s own configured Telegram chat.
3. User enters the code; POST /api/auth/verify-otp {"username", "otp"} validates it against a hashed, single-use, attempt-bounded challenge and, on success, creates a new persisted session row and sets an HttpOnly session cookie.
4. The frontend loads GET /api/auth/me to learn the signed-in identity (id, username, display name, role) and routes an admin to /dashboard, an ordinary user to /portfolio.
5. POST /api/auth/logout revokes only the current session — other devices/sessions for the same or other users are unaffected.

OTPs are 6 digits, generated with secrets, expire after Config.OTP_EXPIRY_MINUTES (5 minutes), are stored only as an HMAC-SHA256 hash, allow at most 5 verification attempts, and are single-use. Requesting more than 3 codes for the same account within 5 minutes is silently throttled (still returns the generic success response). Multiple users can be signed in concurrently; a new login never revokes another user’s session.

Creating a user (admin only)

From Settings → User management (/settings/users, hidden from and rejected for non-admins), an admin fills in a username, display name, and the new user’s Telegram chat ID, then submits. The account is always created with role user — the API rejects any client-supplied role field outright (422). Duplicate usernames (case-insensitive) and duplicate chat IDs are both rejected with a 409 naming which field conflicted.

Bootstrap & the initial admin

On a database with an empty dashboard_users table, arb_bot/auth/bootstrap.py:run_bootstrap() creates exactly one admin account from existing operator configuration — no manual SQL, no interactive prompt:

run_bootstrap() is called both from db/migrate.py (production deploys) and from the dashboard’s own FastAPI startup hook (fresh local installs), and is safe to call on every restart:

• Empty users table + TELEGRAM_CHAT_ID set → creates the one admin, then backfills every pre-existing user-owned row (holdings, transactions, broker connections, everything in the ownership table above) to that admin’s owner_user_id.
• Empty users table + no TELEGRAM_CHAT_ID → logs a warning and does nothing; safe to re-run once the variable is set.
• Any user already exists → a strict no-op for account creation. Restarting the process, redeploying, or re-running migrations never creates a second admin and never promotes an existing account, even if DASHBOARD_BOOTSTRAP_ADMIN_* still points at that user’s username.

Migration & rollout sequence

The auth/tenancy schema ships as ordinary numbered files in db/, applied in order by db/migrate.py:

Deploying to an existing (pre-multi-user) database:

1. make docker-deploy (or python db/migrate.py directly) applies 056–059, then run_bootstrap() runs automatically at the end of the script.
2. Verify the bootstrap admin exists and every pre-existing row is owned: SELECT count(*) FROM dashboard_users; (expect 1 on a first-ever rollout) and, for each user-owned table, SELECT count(*) FROM <table> WHERE owner_user_id IS NULL; (expect 0 — the migration sets the column NOT NULL once the backfill completes, so a non-zero count here means the backfill did not finish and the deploy should not proceed to the app restart).
3. Restart the dashboard service and confirm the existing operator can log in with their existing username and receive an OTP on their existing Telegram chat.
4. Re-running db/migrate.py or restarting the dashboard again is a no-op — every step above is idempotent.

Troubleshooting

MCP & Google connection

Every authenticated dashboard user can link the Keycloak identity used by an MCP client from Settings → Connections (/account/connections). Google is an upstream login broker inside Keycloak only: the Agent Gateway continues to accept only Keycloak-issued RS256 access tokens. The durable identity key is the canonical Keycloak (issuer, subject) pair; Google email and provider values are display/audit metadata and never participate in authorization.

The flow is default-off behind MCP_GOOGLE_LINKING_ENABLED. When disabled, the API returns 404 and the Connections route renders a feature-disabled card. When enabled, the dashboard startup validator rejects missing, weak, insecure, or cross-origin configuration before serving traffic.

Self-service link flow

1. The user selects Connect Google account. The SPA requests a six-digit Telegram OTP for the signed-in user and verifies it. The resulting HttpOnly step-up grant is purpose-bound, session-bound, HMAC-signed, single-use, attempt-capped, and short-lived (default grant TTL: 7 minutes; OTP TTL: 5 minutes).
2. After successful verification the SPA immediately posts to POST /api/auth/mcp-link/start. In one transaction the service consumes that grant and creates a user/session-scoped challenge containing only digests of state and nonce plus a Fernet-encrypted PKCE verifier. The response contains authorization_url, tx_id, and expires_at; raw state is present only inside the server-built authorization URL.
3. The browser completes Authorization Code + PKCE S256 through Keycloak and its Google broker. The callback verifies the state digest, decrypts the PKCE verifier only for the token exchange, and validates the ID token with an exact RS256 algorithm and non-empty kid, trusted JWKS, iss, aud, multi-audience azp, expiry, future-iat skew, nonce, non-empty subject, and broker=google. The broker claim is supplied by a dashboard-mcp-link client protocol mapper that copies Keycloak’s identity_provider client-session note. The OAuth token exchange itself binds the exact registered callback URI.
4. The callback performs a compare-and-set transition from CREATED to GOOGLE_AUTHENTICATED, then redirects only to the fixed relative route /account/connections?tx=<id>. The page polls GET /api/auth/mcp-link/pending and receives only masked email metadata.
5. Selecting Confirm link requires a second, fresh Telegram step-up. Confirm locks the link challenge, grant, existing subject mapping, and the user’s active issuer mapping inside one database transaction before creating or reactivating the mapping. Database uniqueness enforces one owner for each (issuer, subject) and at most one active mapping per (user_id, issuer).
6. Disconnect also requires a fresh Telegram step-up. It atomically consumes the grant, writes the audit event, and sets is_active=false. The next MCP request is rejected even if its Keycloak access token has not expired.

Link challenges expire after DASHBOARD_MCP_LINK_LINK_TTL_MINUTES (default 10 minutes). Callback delivery from a different session returns 403 link_session_mismatch. A pending lookup from the wrong session is deliberately indistinguishable from an unknown transaction and returns 404 link_transaction_not_found. Expired and consumed transactions return their stable 410 error codes.

Tenant isolation and administration

• All self-service repository operations include an explicit user_id and, where applicable, session filter. These four identity-linking tables do not yet use PostgreSQL RLS; adding RLS is a defense-in-depth follow-up, not a property claimed by this release.
• Ordinary status, pending, confirm, cancel, and disconnect requests cannot discover or mutate another user’s rows. Conflict responses never identify the other owner.
• The admin OAuth-mapping API is an explicit break-glass inventory and recovery surface. It can list mapping metadata and deliberately remove or recreate a mapping; merely holding the admin role never bypasses the self-service ownership checks or grants access to another user’s portfolio data.
• The audit table is append-only at the database layer: migration 071 rejects UPDATE and DELETE. Email hints are masked before any response reaches the SPA and are never used by the resolver.

Troubleshooting

Per-user LLM provider chain

The per-user LLM provider chain configured under /portfolio/ai-providers applies to every LLM-bearing surface in the product: AI assistant chat (/api/ai/ask, /api/ai/refresh), AI Market predictions, AI Research analytics insight, and AI Research V3 runs (the chain is snapshotted onto the run row at creation time so the worker reproduces it later).

For the trading bot and Telegram, the chain resolves by the active Telegram chat id. When a dashboard user is bound to that chat id (set when the user is created), the bot uses that user’s chain; otherwise it falls back to the system Codex chain.