OAuth 2.0 – Device flow

OAuth 2.0 - Device flow

Overview

The device flow is designed for devices that either do not have access to a browser or have limited input capabilities. This flow allows users to share specific data with an application while keeping their usernames, passwords, and other information private.

This grant type can eliminate the need for the client to store the user credentials for future use, by exchanging the credentials with a long-lived access token or refresh token.

How to implement the device-flow

Register the Client Id at Identify

At the Identify connection list, you can create an OAuth2.0 protocol that has the following settings:

  • Client ID: Specify the unique ID of the application. Please note: we do check the case-sensitive.
  • Client secret: Specify the Client secret of the application. Please note: we do check the case-sensitive.
  • Redirect URL: Specify the redirect URL after successful authentication. e.g, https://identifydomain/runtime/
  • Application name: Specify the name of the application
  • Set the audience field of tokens which are issued for the application: Specify the Identifier URL which issues the token.
  • Allow client credentials flow: This setting must be True.
  • Code life time (minutes): Specifies the input code lifetime. Its default value is 60.
  • Number of user code group: Specifies the number of 4-character groups of a code. Its default value is 2.
  • JWS algorithm: Either RSASigning or HMACSymmetric.
  • Open auto-generated HMAC button: Used to generate a HMAC Symmetric signing key; key can be 32-byte, 48-byte, or 64-byte. You can then either copy the key and paste it to the configuration or check the appropriate check box and click Select key to apply it.

Here is the screenshot of a sample connection:

identify-admin-oauth2-device

Ask for a Token

The flow has the following steps:

  • The client requests access from the authorization server and includes its client identifier in the request.
  • The authorization server issues a verification code and an end-user code, and provides the end-user verification URI.
  • The client instructs the end-user to use his or her user-agent elsewhere (mostly a browser on a laptop or a mobile phone) and visit the provided end-user verification URI. The client provides the end-user with the end-user code to enter to grant access.
  • The authorization server authenticates the end-user and prompts the end-user to grant the client's access request. If the user hasn't logged in yet, he or she will need to log in.
  • While the end-user authorizes (or denies) the client's request, the client repeatedly polls the authorization server to find out if the end-user has completed the end-user authorization step.
  • Assuming the end-user has granted access, the authorization server validates the verification code provided by the client and responds with the access token.

Step 1: Request device and user codes

Perform a POST operation to the device_authorization endpoint:

URI parameters:

Parameter Description
client_id Your application's Client ID.
client_secret Optional. In case you specify the Client Secret, Identify will validate it with the Client Secret which is configured in the OAuth2.0 protocol connection.
scope Optional. A space-delimited list of scopes that identifies the resources that your application could access on the user's behalf.

oauth2-device-authorization

Step 2: Handle the authorization server response

The authorization server returns a JSON object to your device.

oauth2-device-authorization-response

Its content includes:

  • device_code: The device verification code.
  • user_code: The device verification code.
  • verification_uri: The end-user verification URI on the authorization server

Step 3: User login and consent

  1. The user navigates to the OAuth2/devicepairing endpoint which is shown up from the verification_uri parameter above:

oauth2-verification-uri

  1. The user enters the verification code.
  2. If the code is correct, and if the user hasn't logged yet, the user will need to log in.
  3. The user approves consent.

oauth2-device-approve-consent

Step 4: Poll the authorization server

While the end-user authorizes (or denies) the client's request, the client repeatedly polls the authorization server via the method POST to the token endpoint

URI parameters:

Parameter Description
client_id Your application's Client ID.
grant_type The value must be "urn:ietf:params:oauth:grant-type:device_code".
Device_code The value comes from the message which is received at the 2nd step.

oauth2-token-device

Step 5: Get the access token

If the user has approved the grant, the token endpoint responds with a success response

oauth2-token-device-response

If you decode the access_token you will see that it contains the following claims: