OAuth 2.0 Device Code Flow

The Device Code Flow is designed for devices with limited input capabilities (e.g., smart TVs, gaming consoles, and digital picture frames). It allows users to authorize the device to access protected resources without needing a browser or a full user-agent interface.

This flow is typically used by devices that:

• Do not have a browser to complete the user-agent-based authorization (e.g., smart TVs, printers, etc.).
• Are input-constrained, making it difficult to enter text for authentication.

1. • The device calls the Request Device Code API to retrieve a device_code and user_code.
   • The device then starts polling the Device Code Exchange Token Ping API at a specified interval until an access token is returned.

2. • The user enters the user_code in a browser to authorize the input-restricted device.
   • After the user authenticates, they are redirected to the AfterVerificationURL.

To enable Device Code Flow for your account, you need to contact LoginRadius Support and provide the following details in the Admin console:

1. Device Code App Name: A name for your app used in device code API calls.
2. Polling Interval: The minimum time between polling requests. E.g., if set to 10 seconds, any subsequent requests within 7 seconds will trigger a "slow_down" error.
3. Expiry Time for Device Code: The lifetime of the device_code in seconds before it expires.
4. Expiry Time for Access Token: The lifetime of the access_token in seconds.
5. Expiry Time for ID Token: The lifetime of the id_token in seconds.
6. Verification URL: The URL where the user will enter their user_code on the browser-based device.
7. After Verification URL: The URL the user will be redirected to after successful authentication.
8. User Code Mask: The pattern for generating the user_code. E.g., ***-*** could produce ACS-Q23.

This section outlines the key steps to implement the Device Code Flow with LoginRadius.

To initiate the flow, use the Device Code API to retrieve the device_code and user_code as below.

• Method: POST

• Endpoint:

https://{siteurl}/api/oauth/{OAuthAppName}/device

• Request Body:

{
  "client_id": "<OAuth Client ID>"
}

• Response:

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

Once you have the device_code, continuously call the Device Code Exchange Ping API to check for the access token.

• Method: POST

• Endpoint:

https://{siteurl}/api/oauth/{OAuthAppName}/token

• Request Body:

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

• Response (on success):

{
  "expires_in": 3598,
  "refresh_token": "d87cc355cdc61a6b...507",
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjkzMWVlYz...Vn33edUA0hQCSA",
  "token_type": "Bearer"
}

Once you have the user_code, redirect the user to the Verification URL on the browser-based device:

• URL:

https://<siteurl>/service/oauth/{OauthAppName}/authorize?client_id=<OAuth Client ID>&user_code=<User Code>

The user will be presented with the LoginRadius IDX page. After they authenticate, they will be redirected to the AfterVerificationURL.

Once authentication is successful, the user will be redirected to the AfterVerificationURL. You can show a success message on this page.

Here are some common error responses you might encounter:

Error Name	Error Response	Description
Authorization Pending	{"error":"authorization_pending"}	The user hasn't completed authentication yet. Retry polling.
Slow Down	{"error":"slow_down"}	Wait for the minimum interval specified before retrying.
Expired Token	{"error":"expired_token"}	The access token has expired.
Access Denied	{"error":"access_denied"}	The user denied the authorization.

Depending on the flow you are implementing, you can pass various query parameters to the Authorization URL. Some key parameters include:

• client_id (required): The OAuth Client ID.
• redirect_uri (required): The URI to redirect the user after authorization.
• response_type (required): Specifies the flow type, e.g., code, token, or code token.
• scope (optional): Defines the scope of the requested token.
• state (optional): Used for CSRF protection to bind the request and response.

To create a URL with encoded parameters for authorization:

var registrationUrl = encodeURIComponent(encodeURIComponent("https://www.abc.com/plus?" +encodeURIComponent("param1=aaa&param2=bbb")));
var scope = encodeURIComponent("profile&action=login&registration_url=" + registrationUrl);
var authorizationEndpoint = "https://<siteurl>/sso/oauth/redirect?scope=" + scope + "&state=ddd&response_type=code&redirect_uri=https%3A%2F%2Fabc.com&client_id=";

Following these steps, you can successfully implement the Device Code Flow to authenticate users on devices with limited input capabilities.