Device Code Flow

Overview

The Device Code Flow is designed to enable user authentication on devices with limited input capabilities, such as smart TVs, printers, or media consoles, where traditional browser-based authorization is impractical. It allows these devices to request a device code, which users can enter on another device with a browser to authenticate and grant access.

• Used in devices like smart TVs, media consoles, digital picture frames, and printers.
• It is beneficial for input-constrained environments where browser-based authorization is impractical.

Select the Device Code option in the OIDC settings and configure the required parameters to enable Device Code Flow.

• Verification URL
  Where users manually enter the user code.
  • Verification Complete URL
    Redirect the URL after successful authentication.
    • Device Code Expiration (in seconds).
      Sets validity duration for device_code.
    • Polling Interval (in seconds).
      Minimum time clients must wait before polling.
    • Scopes
      Defines the requested access permissions.
    • Token Expiration and ID Token Expiration (in seconds).
      Specifies token validity duration.
    • Signed User Info
      Optionally returns signed JWT tokens.

• Endpoint:
  https://{siteurl}/api/oidc/{OidcAppName}/device
• Method: POST
• Request Body:

{
  "client_id": "<OIDC Client ID>",
  "scope": "openid email profile"
}

• Response Example:

{
  "interval": 10,
  "expires_in": 1800,
  "device_code": "1522d771f27b408baca35eca7d81c37d",
  "user_code": "MXD-TPV",
  "verification_uri": "https://example.com/verify",
  "verification_uri_complete": "https://example.com/verify?user_code=MXD-TPV"
}

---

• Endpoint:
  https://{siteurl}/api/oidc/{OidcAppName}/token
• Method: POST
• Request Body:

{
  "client_id": "<OIDC Client ID>",
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "<device_code>"
}

• Response Example:

{
  "expires_in": 3598,
  "refresh_token": "<refresh_token>",
  "access_token": "<access_token>",
  "id_token": "<id_token>"
}

---

• Verification URL:
  Users enter user_code on the browser-based device.
• Device Code Confirm URL:
  Redirects to LoginRadius IDX page for login.

• The user logs in on the IDX page.
• After successful authentication, the user is redirected to the afterverificationURL.

---

Error Name	Response Example	Description
Authorization Pending	{"error":"authorization\_pending"}	The user hasn't completed the user code authentication. The client should retry the token request after the polling interval.
Slow Down	{"error":"slow\_down"}	The client must wait for the interval specified in the Device Authorization Response before retrying.
Expired Token	{"error":"expired\_token"}	The device code or token has expired.
Access Denied	{"error":"access\_denied"}	The user denied the authorization request.

This process ensures secure and user-friendly access for constrained devices in OIDC workflows. Let me know if you'd like further assistance or examples!

After obtaining a code or access token through the Device Code Flow, you can utilize the following functionalities to manage tokens, retrieve user information, and access other OpenID features.

If you've received an authorization code, you can exchange it for an access token using the Access Token by OpenID Code API.

• Endpoint:
  https://{siteurl}/api/oidc/{OidcAppName}/token
• Method: POST
• Request Body:

{
  "client_id": "<OIDC Client ID>",
  "grant_type": "authorization_code",
  "code": "<authorization_code>",
  "redirect_uri": "<redirect_URI>"
}

• Response Example:

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "id_token": "<id_token>",
  "token_type": "Bearer",
  "expires_in": 3600
}

To manually expire a refresh token and prevent further usage, use the Revoke Refresh Token API.

• Endpoint:
  https://{siteurl}/api/oidc/{OidcAppName}/revoke
• Method: POST
• Request Body:

{
  "client_id": "<OIDC Client ID>",
  "token": "<refresh_token>",
  "token_type_hint": "refresh_token"
}

• Response Example:

{
  "status": "success"
}

If an access token has expired but the refresh token is still valid, you can use the Refresh Access Token API to obtain a new access token.

• Endpoint:
  https://{siteurl}/api/oidc/{OidcAppName}/token
• Method: POST
• Request Body:

{
  "client_id": "<OIDC Client ID>",
  "grant_type": "refresh_token",
  "refresh_token": "<refresh_token>"
}

• Response Example:

{
  "access_token": "<new_access_token>",
  "id_token": "<new_id_token>",
  "expires_in": 3600
}

To retrieve user information for a logged-in user, use the UserInfo by Access Token API.

• Endpoint: https://{siteurl}/api/oidc/{OidcAppName}/userinfo
• Method: GET
• Headers:
  • Authorization: Bearer <access_token>
• Response Example:

{
  "sub": "1234567890",
  "name": "John Doe",
  "email": "[email protected]",
  "email_verified": true
}

The JSON Web Key Set API allows you to retrieve keys for verifying JWT tokens.

• Endpoint:
  https://{siteurl}/service/oidc/{OIDCAppName}/.well-known/jwks.json
• Method: GET
• Response Example:

{
  "keys": [
    {
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "n": "<modulus>",
      "e": "<exponent>",
      "kid": "<key_id>"
    }
  ]
}

The OIDC Discovery API provides metadata configuration for your OpenID Connect implementation.

• URL Format:
  https://{siteurl}/service/oidc/{OIDCAppName}/.well-known/openid-configuration
• Response Example:

{
  "issuer": "https://{siteurl}/service/oidc/{OIDCAppName}",
  "authorization_endpoint": "https://{siteurl}/service/oidc/{OIDCAppName}/authorize",
  "token_endpoint": "https://{siteurl}/api/oidc/{OIDCAppName}/token",
  "userinfo_endpoint": "https://{siteurl}/api/oidc/{OIDCAppName}/userinfo",
  "jwks_uri": "https://{siteurl}/service/oidc/{OIDCAppName}/.well-known/jwks.json"
}

The RSA algorithm is currently the only supported encryption method for JWT tokens. The JSON Web Key Set (JWKS) endpoint provides public keys for verifying the JWT signature.

Following this guide, you can successfully implement the Device Code Flow for OpenID Connect in environments with limited input capabilities, such as smart TVs, media consoles, and IoT devices. This process ensures a secure and user-friendly authentication experience for devices without browsers, enabling seamless access to protected resources. With the detailed configuration and implementation steps provided, you can efficiently set up and manage the Device Code Flow for your application.