Backend
Device sign-in
A terminal, a TV app or a script has no browser of its own, and typing a
password into one is the thing to avoid. Device sign-in hands the work to a
browser where the person is already signed in: the device shows a short code
and a link, the person approves it there, and the device is answered with a
session. It follows RFC 8628, the OAuth 2.0 device authorization grant; it is
how rebase cloud login signs in to Rebase Cloud.
auth: { deviceLogin: { verificationUrl: "https://app.example.com/device" }}verificationUrl is a page of your app. It is opened with the code as
?code=BCDF-GHJK, and as the signed-in user it shows what the request is and
approves or denies it:
const request = await client.auth.describeDeviceLogin(code); // device name, IP, statusawait client.auth.approveDeviceLogin(request.userCode); // or denyDeviceLoginThe device starts and polls:
const { deviceCode, userCode, verificationUriComplete, interval } = await client.auth.startDeviceLogin({ clientName: "My CLI on laptop" });// show userCode and verificationUriComplete, then every `interval` seconds:const result = await client.auth.pollDeviceLogin(deviceCode);// { status: "pending" | "slow_down", interval } | { status: "denied" } | { status: "expired" }// | { status: "approved", user, accessToken, refreshToken }: this client is now signed inA device polls in a loop like this one:
const start = await client.auth.startDeviceLogin({ clientName: "My CLI on laptop" });console.log(`Open ${start.verificationUriComplete} and check the code ${start.userCode}`);
let interval = start.interval;for (;;) { await new Promise(resolve => setTimeout(resolve, interval * 1000)); const result = await client.auth.pollDeviceLogin(start.deviceCode); if (result.status === "approved") break; // signed in; the session is stored if (result.status === "denied" || result.status === "expired") throw new Error(result.status); interval = result.interval; // "pending", or "slow_down" with a longer one}What keeps it safe:
- Approving takes a live session, and the device gets that account. Show the code, the device’s name and where it asked from on the page, and say to approve only a code the person’s own device shows: the attack on this grant is a stranger sending someone a link to approve the stranger’s device.
- The second factor carries over. An account with a verified factor can
only approve from an
aal2session, and the device’s session has the level of the session that approved it. - Ten minutes, decided once, handed out once. The device code is stored
hashed, in
rebase.auth_device_logins, closed to the RLS role. - Paced polling. A device that polls faster than its interval is answered
slow_downand its interval grows by five seconds. - The poll always answers the session in the body, whatever
cookieAuthsays: a device has no cookie jar.
The routes are POST /auth/device, POST /auth/device/token,
GET /auth/device/:code, POST /auth/device/approve and
POST /auth/device/deny. /auth/config reports deviceLogin: true while it is
on.
Next: the rest of the auth options, the
endpoint index and the error codes
the approval routes answer, and rebase cloud login, which
signs in this way.