docs(website): record trusted-device support on the SSO login paths #62

wtclaude · 2026-07-28T06:03:34Z

wtclaude commented

2026-07-28 06:03:34 +00:00

What & why

Doc side of website#108 and Android-app feat/sso-trusted-device.

TRUSTED_DEVICES_MFA.md §6 gains an "SSO login paths" subsection: SSO is not exempt from the second factor, and a trusted device skips it exactly as on the password path. Previously SSO consulted trust nowhere, so a user signing in with an external identity was asked for a code on every single sign-in. Documents the callback-side skip, the new trustDevice/deviceName on POST /auth/sso/totp, and why recovery codes stay password-login only.

It also writes down how this reaches the Android app, since it isn't obvious from the code: the app's SSO runs in a Custom Tab that shares the system browser's cookie jar, so the rg_trust cookie covers native SSO with no app change and no trust token in a start URL (which would leak a secret into query strings and logs). The app's own token is minted at /auth/mobile/sso/exchange instead — an authenticated app→server call — so it never travels in the deep link, and the bridge row holds only a boolean. Notes that one tick yields two independently-revocable rows.

§4 documents the new mobile_auth_sessions.trust_device column. BACKEND_DESIGN.md gets the same column in its bridge table, the trust note on the /exchange row, and a pointer from the bridge intro to the Custom Tab cookie model.

How it was tested

Documentation only — no code. Every statement was verified against the running server and real MariaDB while building website#108: the trust cookie is issued and the row persisted by the SSO TOTP step, a subsequent SSO callback carrying it skips the code, and an invalid trust is still challenged.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand
every change, and take responsibility for it. AI-authored commits are
marked with a Co-Authored-By / Assisted-By trailer.

License

I agree that my contribution is licensed under this project's license
(GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Doc side of **website#108** and **Android-app** `feat/sso-trusted-device`. **`TRUSTED_DEVICES_MFA.md` §6** gains an "SSO login paths" subsection: SSO is not exempt from the second factor, and a trusted device skips it exactly as on the password path. Previously SSO consulted trust **nowhere**, so a user signing in with an external identity was asked for a code on every single sign-in. Documents the callback-side skip, the new `trustDevice`/`deviceName` on `POST /auth/sso/totp`, and why recovery codes stay password-login only. It also writes down **how this reaches the Android app**, since it isn't obvious from the code: the app's SSO runs in a Custom Tab that shares the system browser's cookie jar, so the `rg_trust` cookie covers native SSO with no app change and no trust token in a start URL (which would leak a secret into query strings and logs). The app's own token is minted at `/auth/mobile/sso/exchange` instead — an authenticated app→server call — so it never travels in the deep link, and the bridge row holds only a boolean. Notes that one tick yields two independently-revocable rows. **§4** documents the new `mobile_auth_sessions.trust_device` column. **`BACKEND_DESIGN.md`** gets the same column in its bridge table, the trust note on the `/exchange` row, and a pointer from the bridge intro to the Custom Tab cookie model. ## How it was tested Documentation only — no code. Every statement was verified against the running server and real MariaDB while building website#108: the trust cookie is issued and the row persisted by the SSO TOTP step, a subsequent SSO callback carrying it skips the code, and an invalid trust is still challenged. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` / `Assisted-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-07-28 06:03:36 +00:00

docs(website): record trusted-device support on the SSO login paths e4bec0caba

Doc side of website + Android-app feat/sso-trusted-device.

TRUSTED_DEVICES_MFA.md §6 gains an "SSO login paths" subsection: SSO is not
exempt from the second factor, and a trusted device skips it exactly as on the
password path (previously SSO consulted trust nowhere, so an external-identity
user was asked for a code on every sign-in). Documents the callback-side skip,
the new trustDevice/deviceName on POST /auth/sso/totp, and why recovery codes
stay password-login only.

Also writes down how this reaches the Android app, since it is not obvious: the
app's SSO runs in a Custom Tab that shares the system browser's cookie jar, so
the rg_trust cookie covers native SSO with no app change and no trust token in a
start URL (which would leak a secret into query strings and logs). The app's own
token is minted at /auth/mobile/sso/exchange instead — an authenticated
app→server call — so it never travels in the deep link, and the bridge row holds
only a boolean. Notes that one tick yields two independently-revocable rows.

§4 documents the new mobile_auth_sessions.trust_device column; BACKEND_DESIGN.md
gets the same column in its bridge table, the trust note on the /exchange row,
and a pointer from the bridge intro to the Custom Tab cookie model.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech approved these changes 2026-07-28 06:06:53 +00:00

whitlocktech merged commit b523336313 into main

2026-07-28 06:07:01 +00:00

whitlocktech deleted branch feat/sso-trusted-device

2026-07-28 06:07:02 +00:00

whitlocktech referenced this issue from a commit

2026-07-28 06:07:02 +00:00

Merge pull request 'docs(website): record trusted-device support on the SSO login paths' (#62) from feat/sso-trusted-device into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#62