Implementing Device Authorization Grant in Keycloak: A Step-by-Step Guide

Device Authorization Grant is a mechanism to allow devices with limited user input capability, such as smart TVs or IoT devices, to access an OAuth2-protected API on behalf of a user. This flow works by allowing the user to authorize devices through another device, like a mobile phone or computer, where authentication is easier.

Keycloak, a popular open-source Identity and Access Management solution, supports the Device Authorization Grant, making it ideal for scenarios involving IoT or constrained devices. In this guide, we will walk you through enabling and implementing this flow in Keycloak.

Key Concepts

Device Code: A unique code for the device, used to poll the authorization server to check for user approval.
User Code: A code displayed to the user, which they can input on a separate device.
Verification URI: A link where the user inputs the user code to approve the device.
Polling: The device periodically asks the authorization server if the user has approved it.

Enabling Device Authorization Grant in Keycloak

Before implementing the flow, ensure that the client in Keycloak is configured to support the Device Authorization Grant. Follow these steps:

Login to Keycloak Admin Console: Open your Keycloak instance and log in to the admin console.
Navigate to appropriate Realm.
Navigate to Clients: Go to the Clients section on the left sidebar and select the client that will be used by your device to access the resources.
Enable OAuth 2.0 Device Authorization Grant:
- In the client configuration, under the Settings tab, find the OAuth 2.0 Device Authorization Grant setting. Toggle the setting to ON to enable the device grant for the selected client.
Save the Configuration: Once enabled, click Save to apply the changes.

Step 1: Generate Device Code, User Code, and Verification URI

The device initiates the flow by requesting a device code, user code, and verification URI from Keycloak. Here’s how to generate these codes.

REST Request:

Make a POST request to the device authorization endpoint, including the client ID and scope.

POST {Keycloak_Server_URL}/realms/{realm_name}/protocol/openid-connect/auth/device
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&scope=openid

Sample Response:

{
  "device_code": "D2G89bKHb7YTXYFp-5vR_H",
  "user_code": "A8G9-PKZ2",
  "verification_uri": "https://auth.example.com/device",
  "verification_uri_complete": "https://auth.example.com/device?user_code=A8G9-PKZ2",
  "expires_in": 1800,
  "interval": 5
}

device_code: The code the device will use to poll the Keycloak server.
user_code: The code the user needs to input at the verification URI.
verification_uri: The link where the user authorizes the device.
interval: How often (in seconds) the device should poll the server.

Step 2: User Approval Process

The user needs to visit the verification URI (https://auth.example.com/device in the example) on another device (like a phone or computer) and enter the user code.

Steps:

The device shows the user a screen with the user code and verification URI.
The user opens a browser and visits the verification URI (https://auth.example.com/device).
The user enters the user code and logs in (if not already logged in).
The user is asked to approve the device for access.

Step 3: Polling for Access Token

In parallel to the user approval process, the device starts polling the Keycloak server to check if the approval process is complete.

REST Request:

Make a POST request to the token endpoint with the device_code.

POST {Keycloak_Server_URL}/realms/{realm_name}/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=D2G89bKHb7YTXYFp-5vR_H

Sample Response (Before Approval):

If the user hasn’t approved yet, Keycloak will return an error indicating that the device should continue polling.

{
  "error": "authorization_pending",
  "error_description": "The authorization request is still pending."
}

Sample Response (After Approval):

Once the user approves the device, Keycloak will return an access token.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "expires_in": 300,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "refresh_expires_in": 1800,
  "scope": "openid email profile"
}

Handling Errors

Common errors in the polling process:

authorization_pending: Continue polling. The user hasn’t completed the authorization.
slow_down: The device is polling too fast. Increase the interval between polling attempts.
expired_token: The device code has expired. Start the process again by requesting a new device code.

Conclusion

The Device Authorization Grant flow is highly effective for devices with limited input capabilities. Keycloak makes it easy to set up this flow by providing built-in support for the Device Authorization Grant. By following the steps outlined in this guide, you can implement this flow to enable seamless device-based access for your users.

With the device code and polling mechanism, the process ensures that even constrained devices can securely authenticate users and retrieve tokens. This is especially beneficial for IoT devices, set-top boxes, and other similar environments.

MaheshNotes