OAuth 2.0 Device Authorization Grant in WSO2 Identity Server

WSO2 Identity Server 5.10.0 supports the OAuth 2.0 device authorization grant which is designed for Internet-connected devices such as smart TVs, media consoles, digital picture frames, and printers, etc. It enables OAuth clients on such devices to obtain user authorization to access protected resources by using a user agent on a separate device.

Let’s get to know about the device authorization grant flow…

Device Code Grant Flow

As shown in the above figure, the client first requests access from the authorization server and includes its client identifier in the request. There, the client ID” is a required parameter and the scope parameter is optional.

Then the authorization server issues a device code and an end-user
code and provides the end-user verification URI along with the device authorization response.

After that, the end-user uses a user agent on another device and visit the provided end-user verification URI. The client provides the user with the end-user code to enter in order to review the authorization request.

The authorization server authenticates the end-user and prompts the user to input the user code provided by the device client. The authorization server validates the user code provided by the user and prompts the user to accept or decline the request.

While the end-user reviews the client’s request, the client repeatedly polls the authorization server to find out if the user completed the user authorization step. The client includes the device code and its client identifier.

The authorization server validates the device code provided by the client and responds with the access token if the client is granted access, an error if they are denied access or an indication that the client should continue to poll.

Try out device authorization flow

Configure Service provider

1. Navigate to WSO2 Identity Server Samples.
2. Download the pickup-manager.war file from the latest release assets and deploy.
3. Return to the WSO2 IS management console.
4. Navigate to Main>Identity>Service Providers and click Add.
5. Enter pickup-manager in the Service Provider Name text box, and click Register.
6. In the Inbound Authentication Configuration section, click Configure under the OAuth/OpenID Connect Configuration section.
7. Enter the following value as the Callback URL: http://localhost.com:8080/pickup-manager/oauth2client
8. Select “urn:ietf:params:oauth:grant-type:device_code” under allowed Grant Types.
9. Click Add and Note the Client id.
10. Click Register to save the changes.

Device Authorization Request

The client sends the device authorization request as follows along with the client id of the above-configured service provider.

curl -X POST 'https://localhost:9443/oauth2/device_authorize' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=<client_id>'

Device Authorization Response

The following is a sample device authorization response and note the issued user code and device code for the next steps.

{
"user_code": "v6jgtw",
"device_code": "fc57e423-d742-407d-a142-490d8e2c8b22",
"interval": "5",
"verification_uri_complete": "https://https://localhost:9443/authenticationendpoint/device.do?user_code=v6jgtw",
"verification_uri": "https://localhost:9443/authenticationendpoint/device.do",
"expires_in": "600"
}

device_code — Device verification code.

user_code— User code (end-user verification code).

verification_uri — End-user verification URI.

verification_uri_complete — End-user verification URI including a user code.

expires_in — Lifetime in seconds of the device code and the user code.

interval —The minimum amount of time in seconds between polling requests to the token endpoint.

User Interaction Step

Access the device verification endpoint using the web browser. The device verification endpoint returns the following UI to get the user code and then authenticate the user.

Device Access Token Request

Meanwhile, after receiving the response from the device authorization endpoint, the client application repeats the following token requests until it gets the final result.

curl -X POST 'https://localhost:9443/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
-d 'device_code=d582beb7-9a23-4caa-8a11-47a798771916' \
-d 'client_id=DEVELOPER_PORTAL' -k

Device Access Token Response

Then the following token response will be returned. When receiving a successful response the client application stops making token requests and the device flow finishes there.

{
   "access_token": "08287154-078f-3a77-b18a-d34237f7ba9f",
   "refresh_token": "602a1849-7292-3fde-bb68-a12f7eb09b6c",
   "token_type": "Bearer",
   "expires_in": 3600
}

I think now you have a good understanding to try out authorization code grant flow with WSO2 Identity Server. :-)

Please Note!!!

The device authorization grant has been disabled by default in the 5.11.0 version and will be available by default in the WSO2 IS release. However, you can enable it by adding the following configuration to the deployment.toml file.

[oauth.response_type.device]
enable=true
[oauth.grant_type.device_code]
enable=true

For more information please refer: https://is.docs.wso2.com/en/latest/setup/migrating-what-has-changed/#disabled-device-authorization-grant