0
How the Device Authorization Flow Works (RFC 8628)

The Device Flow coordinates authentication across two separate devices connected to the same identity provider:

  1. Device Initialization (POST /device/code): The input-constrained device makes a direct HTTP POST to the IdP's Device Authorization endpoint requesting an authorization session. The IdP returns:
    • user_code: A short, human-friendly code (e.g., WDJB-HGKL).
    • device_code: A long, high-entropy secret token known only to the device.
    • verification_uri: The web portal URL where the user will authorize the request.
    • interval: The mandatory polling interval (typically 5 seconds).
  2. User Action on Secondary Device: The device displays the user_code on-screen and instructs the user to open verification_uri on their phone or laptop. The user logs in with their full browser, completing passwords, passkeys, and MFA.
  3. Device Background Polling (POST /token): While the user is typing the code on their phone, the device polls the token endpoint at the designated interval, presenting grant_type=urn:ietf:params:oauth:grant-type:device_code and its private device_code.
  4. Protocol Polling States:
    • authorization_pending (HTTP 400): The user has not finished approving yet. The device continues polling.
    • slow_down (HTTP 400): The device is polling too frequently. The client must increase its interval by +5 seconds.
    • expired_token (HTTP 400): The user took longer than expires_in (typically 15 mins).
  5. Instant Token Issuance: The moment the user clicks "Approve" on their phone, the next poll request succeeds immediately with HTTP 200, delivering the user's id_token, access_token, and refresh_token to the device.
1
Device & IdP Configuration

Enter your OIDC endpoints and client ID. For public clients, leave the client secret empty.

The IdP endpoint that issues the user_code and device_code.

MS Example: https://login.microsoftonline.com/common/oauth2/v2.0/devicecode

The standard token endpoint polled by the device to receive tokens.
The application ID (configured in Entra ID / IdP to allow public client device flows).
Only required if your app registration is configured as a confidential client.
openid is required for user identity tokens.
2
Request Device & User Codes

The device initiates the flow by requesting a device code and human user code from the IdP.

Request sent to IdP

POST /api/oidc-device
// Awaiting execution...

IdP Response

// Awaiting response...