SSO for 10-Foot Devices

If your application runs on a 10 foot/3 meter (10’/3m) device, use the Device Authorization Grant (DAG) flow to obtain tokens on the device. In the DAG flow, the device creates a pending authorization request to Digital Identity Management, and Digital Identity Management responds with secure, long, device code and a much shorter, user-friendly user code. The device presents the user code on page, and invites the user to visit a specific URL. On a separate device (for example, phone, laptop) the user authenticates into Digital Identity Management and approves the user code. Meanwhile, the device has been repeatedly polling the /oidc/token endpoint using the device code to check for approval in the background. Once the user approves, the device receives its tokens.

Flow Diagram

The diagram below represents the communication between the key actors using the Device Authorization Grant flow:

Note: The Device Authorization Grant flow has the significant advantage in that the user does not have to wrestle with entering their credentials using an inconvenient TV interface. Instead, they perform any sign-in operation on a much more convenient handheld device or physical keyboard.

Interaction Steps

The interaction steps between each actor in the flow are as a follows:

The user initiates the login process for your application on the 10’/3m device.
The device calls Digital Identity Management’s POST /oidc/devicecode DAG endpoint with the following HTTP parameters in an x-www-form-encoded body:
Parameter Description Sample Value
client_id ID of the relying party. MyApplication-WebUI
scope Space-separated list of OAuth 2.0/OIDC scopes to request. openid profile email offline_access
Digital Identity Management verifies that the registered RP, specified by the client_id, is configured to allow DAG, and that the scopes are valid for the client. Digital Identity Management then generates and stores a DAG device_code and user_code for the request.
Digital Identity Managements responds to the device with a JSON object that contains the following fields:

Parameter	Description	Sample Value
`client_id`	ID of the relying party.	`MyApplication-WebUI`
`scope`	Space-separated list of OAuth 2.0/OIDC scopes to request.	`openid profile email offline_access`

Parameter	Description
`error`	(Optional) The error code, if an error occurred. The following codes are possible:
Error Code	Meaning
`invalid_request`	The `/oidc/authorize` request was not valid.
`unauthorized_client`	The RP’s `client_id` that was specified in the `/oidc/authorize` request does not exist.
`invalid_scope`	One or more of the `scope` values that was specified in the `/oidc/authorize` request is not enabled for this relying party.
`server_error`	An error occurred on the Digital Identity Management server. Equivalent to an `HTTP 500` error code. The request may be retried.
`temporarily_unavailable`	The Digital Identity Management server is temporarily unavailable to process the request. Equivalent to an `HTTP 503` error code. The request may be retried.
`error_description`	(Optional) An easily understandable and readable description of the error, if an error occurs.
`device_code`	Code used for the 10’/3m device to poll for approval. A relatively long UUID string.
`user_code`	Code the user must enter to approve the device. A relatively short alphanumeric string.
`verification_uri`	The location of the DAG approval UI. Loading this URI will prompt the user to enter the `user_code`.
`verification_uri_complete`	(Optional) If configured, the `verification_uri` concatenated with the `user_code` as an `HTTP GET` query parameter so that the user does not need to manually enter the code.
`expires_in`	(Optional) If DAG requests are configured to expire (strongly recommended), then the expiry time is in seconds.
`interval`	(Optional) The minimum interval in seconds between requests by the device to check if the DAG has been approved.Note: As per section 3.5 of RFC-8628, if Digital Identity Management does not specify an `interval` value in this response, then your client must assume a default value of 5 seconds. In other words, if Digital Identity Management does not specify an interval, then your client must not poll Digital Identity Management’s `oidc/token` API faster than once every 5 seconds.

Your device UI prompts the user to visit the approval page UI on their mobile device or personal computer. Your device may display the user_code on the page, or use the verification_uri_complete string that incorporates the user_code into the URI. Note: A URL shortener or other mechanism may be used to make the URL easier to type. The device might even translate the URI into a QR code for ease-of-use with a mobile device.

While displaying the verification information on the page, in the background your device repeatedly polls Digital Identity Management’s /oidc/token endpoint to check if the request has been approved. The following HTTP query parameters must be supplied in each request:

Parameter	Value
`device_code`	The `device_code` value received in step 4.
`client_id`	The Relying Party’s ID that is registered with Digital Identity Management.
`grant_type`	Value must always be `urn:ietf:params:oauth:grant-type:device_code`.
`client_secret`	The relying party secret key, if the relying party is configured as a confidential client (not recommended when using DAG).

Note: As per section 3.5 of RFC-8628, if Digital Identity Management did not specify an interval value in the initial POST /oidc/devicecode API response, then your client must assume a default value of 5 seconds. In other words, if Digital Identity Management did not specify an interval, then your client must not poll Digital Identity Management’s oidc/token API faster than once every 5 seconds.

Digital Identity Management responds with HTTP 400 status and a JSON payload that indicates the request is still pending:
**Error response - body** { "error": "authorization_pending", "error_description": "Authorization pending for code f73b7b8a-7e55-45f8-ac3e-e18f86ace4a1" }
Steps 6 and 7 continue in the background until the user authenticates and approves the device.
The user does as instructed and loads the OIDC device approval URL /oidc/device (or /oidc/device?user_code=X, if the full URL was supplied), as provided by the device UI, onto a separate device. This is an endpoint on Digital Identity Management.
The approval UI checks if the user is authenticated on this device. This can be accomplished by any number of means, such as a call to the Digital Identity Management GET /user API or even a call to /oidc/device?device_code=A endpoint if the user_code is already known. Either API will return 401 Unauthorized message if the user is already signed in.
(Conditional) If the user is currently signed in to Digital Identity Management, then Digital Identity Management redirects them to the approval page in the portal UI with an HTTP 302 redirect. Skip steps 11 through 15 and go to step 16.
(Conditional) If the user is not currently signed in to Digital Identity Management, then Digital Identity Management redirects them to the login page in the portal UI with an HTTP 302 redirect. Proceed to steps 12 through 15.
User authentication typically begins with Digital Identity Management’s POST session/start API, which initializes the Authenticate User Process. If the user needs to or is allowed to onboard first, they may do that instead (not shown in the diagram).
Eventually, whether from a /session/start or other process call, and potentially after several more steps (for example, to satisfy multi-factor authentication rules, if enabled), the final HTTP response from Digital Identity Management indicates that the user is now authenticated, and the approval process can continue.
The user’s browser once again loads the approval endpoint.
Digital Identity Management recognizes the user as signed in and redirects them to the approval page in the portal UI.
(Conditional) If the approval UI was not loaded with the verification_uri_full, then it must prompt the user to enter the user_code that the device displayed on the TV page.
(Conditional) The user enters the user_code to confirm the device that they wish to approve.
The portal calls Digital Identity Management’s /oidc/device endpoint with the single HTTP query parameter user_code set to the value of the user-supplied code.
Digital Identity Management uses the user-supplied code to look up the pending DAG request.

Digital Identity Management returns the details of the pending DAG request as a JSON Object, which resembles the following:

**oidc/device - response**
{ 
  "deviceCode": { 
    "deviceCode": "31961bfa-6767-4beb-b99c-369982e4f46b", 
    "userCode": "R0PLI5", 
    "scope": [ 
      "email", 
      "openid", 
      "profile" 
    ], 
    "expiration": null, 
    "clientId": "MyApplication-WebUI", 
    "requestParameters": {}, 
    "approved": false 
  }, 
  "client": { 
    "id": "MyApplication-WebUI", 
    "name": "My Application", 
    "description": null, 
    "registeredAt": 1610139194000, 
    "homeURI": null, 
    "logoURI": null, 
    "policyURI": null, 
    "tosURI": null, 
    "contacts": [], 
    "subjectType": 
    "PUBLIC", "provisionedScopes": [ 
      "com.uxpsystems.ulm", 
      "phone", "openid", 
      "email", "profile" 
    ], 
    "dynamicallyRegistered": false 
  }, 
  "requestedScopes": [ 
    { 
      "id": 1, 
      "value": "openid", 
      "description": "log in using your identity", 
      "icon": "user", "defaultScope": true, 
      "restricted": false, 
      "structured": false, 
      "structuredParamDescription": null, 
      "structuredValue": null 
    }, 
    { 
      "id": 2, 
      "value": "profile", 
      "description": "basic profile information", 
      "icon": "list-alt", 
      "defaultScope": true, 
      "restricted": false, 
      "structured": false, 
      "structuredParamDescription": null, 
      "structuredValue": null 
    }, 
    { 
      "id": 3, 
      "value": "email", 
      "description": "email address", 
      "icon": "envelope", 
      "defaultScope": true, 
      "restricted": false, 
      "structured": false, 
      "structuredParamDescription": null, 
      "structuredValue": null 
    } 
  ], 
  "status": "PENDING" 
}

The fields of the response are as follows:

Field	Description
`status`	Current status of the DAG request out of the following:- PENDING - APPROVED - DENIED
`deviceCode`	JSON object with details about the DAG request, with the following fields:
Field	Description
`deviceCode`	Long code that was supplied to the device by Digital Identity Management.
`userCode`	Short code supplied to the user.
`scope`	Array of scopes requested by the device.
`expiration`	Expiration date as UNIX epoch time, or null if the DAG request does not expire.
`clientId`	Relying Party ID for the DAG request.
`requestParameters`	Any additional parameters from the original DAG request.
`approved`	Specifies whether the DAG request has already been approved.
`client`	Information about the relying party for which the DAG was issued for the purposes of presenting information to the user. This information is only relevant to the generic DAG approval UI supplied by Digital Identity Management. If you are writing your own UI, you may assume the relying party the user is approving and may not need to display anything at all.
`requestedScopes`	Array of detailed information about the scopes requested for the purposes of presenting information to the user. This information is only relevant to the generic DAG approval UI supplied by Digital Identity Management. If you are writing your own UI, you may read the scopes listed in the `deviceCode` field and present them (or not) as you see fit.
Note: The default DAG approval UI supplied by Digital Identity Management asks the user to confirm the details of the DAG request, and will use the information in this response to construct that page. However, even if you write your own approval UI that skips a confirmation step, your UI must still make this API call to initialize the approval.

The default DAG approval presents information about the request to the user, and prompts them to approve.
The user confirms the DAG Request.
The approval UI calls the POST /oidc/device/approve endpoint with the following HTTP query parameters:
Parameter Value
user_code The user_code entered in previous steps, or received by the portal as part of the verification URI in step 8.
user_oauth_approval The fixed string “true” (without quotes).
Digital Identity Management records the DAG as approved. The next approval-check request by the device will receive the tokens.
Digital Identity Management informs the portal that the approval is complete.
The approval UI tells the user that their device should begin working shortly.
As it has been doing repeatedly this whole time, the device calls the /oidc/token endpoint in the background to check for approval (see step 6 for details). This time, however, Digital Identity Management is going to respond with HTTP 200 OK.
Digital Identity Management responds to the 10’/3m device with 200 OK and a JSON Object containing the requested tokens.
The device must store the access token, ID token, and refresh token for future usage.
The device informs the user that they are now logged in and may begin using the application.

Parameter	Value
`user_code`	The `user_code` entered in previous steps, or received by the portal as part of the verification URI in step 8.
`user_oauth_approval`	The fixed string “true” (without quotes).

Parent topic:Using Digital Identity Management for Single Sign-On

Home

Guides

APIs

Flow Diagram

Interaction Steps

​Flow Diagram

​Interaction Steps

Flow Diagram

Interaction Steps