Device authorization

The device authorization grant (RFC 8628) signs a person in on a device that has no browser or no usable keyboard: a smart TV app, a command-line tool on a remote server, a kiosk, a set-top box. The device asks the OAuth/OIDC provider for a short code, shows it with a URL, and waits. The person opens that URL on their phone or laptop, signs in to Better IAM there, enters the code, and approves the device. The device then receives the same access, ID, and refresh tokens a browser app would.

Use it when typing a password on the device is impractical or unsafe. When the device has a browser, use the authorization code flow instead: it is shorter and needs no polling.

Device authorization is part of createOAuthProvider and is always enabled. A client may use it only when it is registered with the urn:ietf:params:oauth:grant-type:device_code grant type.

How it works

The person approves on their own device, with their own Better IAM session, so passwords, passkeys, single sign-on, and MFA all work unchanged. The grant is bound to that IAM session like every other consent: signing out or being deactivated ends the device's tokens too.

Setup

import { createOAuthProvider } from 'better-iam/oauth';
import { iam } from './iam';

const keys = JSON.parse(process.env.OIDC_KEYS!); // { jwks, cookieKeys, encryptionKey } from your secret store

const escape = (value: string) =>
  value.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]!);

function page(title: string, body: string) {
  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${escape(title)}</title></head><body><main><h1>${escape(title)}</h1>${body}</main></body></html>`;
}

export const issuer = createOAuthProvider({
  ...iam.protocolHost,
  issuer: 'https://identity.example/oidc',
  jwks: keys.jwks,
  cookieKeys: keys.cookieKeys,
  encryptionKey: keys.encryptionKey,
  trustedOrigins: ['https://identity.example'],
  interactionUrl: (uid) => `https://identity.example/interactions/${uid}`,
  renderDevicePage: ({ kind, form, userCode, clientName }) =>
    page(
      'Connect a device',
      kind === 'success'
        ? '<p>Device connected. You can return to your device.</p>'
        : kind === 'input'
          ? `<p>Enter the code shown on your device.</p>${form}`
          : `<p>Allow ${escape(clientName ?? 'this application')} with code ${escape(userCode ?? '')}?</p>${form}`,
    ),
  renderLogoutPage: ({ form }) => page('Sign out', form),
});
iam.useProtocol(issuer);

import { createServer } from 'node:http';
import { iam } from './iam';
import './oauth'; // registers the provider with iam.useProtocol

createServer((req, res) => void iam.nodeHandler(req, res)).listen(3000);

import { issuer } from '../oauth';

await issuer.registerClient(adminCredential, {
  tenantId: 'acme',
  clientId: 'reports-tv',
  name: 'Reports for TV',
  public: true,
  redirectUris: [],
  grantTypes: ['urn:ietf:params:oauth:grant-type:device_code', 'refresh_token'],
  scopes: ['openid', 'profile', 'offline_access', 'reports:read'],
});

Usage

The device side is plain HTTP. These examples use fetch and work in Node 22 and later. Read the endpoint URLs from discovery rather than building them by hand.

Discover the endpoints

const issuerUrl = 'https://identity.example/oidc';

export async function discover() {
  const response = await fetch(`${issuerUrl}/.well-known/openid-configuration`);
  if (!response.ok) throw new Error(`Discovery failed: ${response.status}`);
  const metadata = (await response.json()) as {
    device_authorization_endpoint: string;
    token_endpoint: string;
  };
  return metadata;
}

Start a device authorization

The device posts its client_id and the scopes it wants to the device authorization endpoint. Add resource to get an access token for one of your resource servers.

import { discover } from './discover';

export async function startDeviceLogin() {
  const { device_authorization_endpoint } = await discover();
  const response = await fetch(device_authorization_endpoint, {
    method: 'POST',
    headers: { 'content-type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: 'reports-tv',
      scope: 'openid profile offline_access reports:read',
    }),
  });
  if (!response.ok) throw new Error(`Device authorization failed: ${response.status}`);
  return (await response.json()) as {
    device_code: string;
    user_code: string;
    verification_uri: string;
    verification_uri_complete: string;
    expires_in: number;
  };
}

Endpoint: POST {issuer}/device/auth

The response has no interval field, so poll every 5 seconds, the RFC 8628 default.

Show the code

Display user_code and verification_uri, for example "Go to identity.example/oidc/device and enter WDJB-MJHT". The person can type the code with or without the dash and in any letter case; the provider normalizes it.

Poll for tokens

While the person approves, the device polls the token endpoint with the device code grant:

import { discover } from './discover';

const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';

export async function pollForTokens(deviceCode: string, expiresIn: number) {
  const { token_endpoint } = await discover();
  const deadline = Date.now() + expiresIn * 1000;
  let interval = 5;
  while (Date.now() < deadline) {
    await new Promise((resolve) => setTimeout(resolve, interval * 1000));
    const response = await fetch(token_endpoint, {
      method: 'POST',
      headers: { 'content-type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({ grant_type: DEVICE_GRANT, device_code: deviceCode, client_id: 'reports-tv' }),
    });
    const body = (await response.json()) as Record<string, string>;
    if (response.ok) return body; // access_token, id_token, refresh_token, expires_in, scope
    if (body.error === 'authorization_pending') continue;
    if (body.error === 'slow_down') {
      interval += 5; // RFC 8628: back off when asked
      continue;
    }
    throw new Error(`Device sign-in failed: ${body.error}`); // access_denied, expired_token, invalid_grant
  }
  throw new Error('Device sign-in expired');
}

Endpoint: POST {issuer}/token with grant_type=urn:ietf:params:oauth:grant-type:device_code

A device code is redeemed once. The token response is the standard one; refresh_token is present when the client is registered for the refresh_token grant and the request included offline_access.

Approve on another device

The person opens verification_uri (or verification_uri_complete). The provider then:

1. Shows your page with kind: 'input' (skipped when the URL carries the code).
2. Looks the code up and shows kind: 'confirm' with userCode and clientName, so the person can check that the code matches their screen. Cancelling marks the device code access_denied.
3. Sends the browser to your interaction page. The person signs in to the client's tenant if needed and approves the requested scopes; your page calls completeInteraction.
4. Shows kind: 'success'. The device's next poll receives the tokens.

A code that is unknown, expired, or already used does not reach the confirm step.

Use and refresh the tokens

Device tokens are ordinary provider tokens: call your API with the access token, verify it there with createAccessTokenVerifier, and refresh with grant_type=refresh_token. Refresh tokens rotate on every use. A client registered with requireDpop must send a DPoP proof when it polls, and receives key-bound tokens (DPoP).

Endpoints

Paths are relative to the issuer URL. With an issuer of https://identity.example/oidc, the device authorization endpoint is https://identity.example/oidc/device/auth.

Options

Device authorization has no switch of its own. These provider and client settings shape it:

Fixed lifetimes: device codes and interactions last 10 minutes, access tokens 15 minutes (or the shorter of the resource server's and the client's accessTokenTtl), and the consent 30 days from the last approval.

Schema

Device codes are provider artifacts in the oauthArtifacts collection, like authorization codes. Each is encrypted with the provider's encryptionKey, bound to the client's tenant, and indexed by a SHA-256 hash of its user code (userCodeHash), so neither code is stored in readable form. Consents land in oauthGrantSessions, which binds each grant to the IAM session that approved it.

Errors

The device endpoints answer with standard OAuth errors (the table under Poll for tokens). Better IAM errors come from the server-side calls:

Related