Device Authorization Grant

March 30, 2024 | seedling, permanent

tags :

Grant Types or OAuth flow in OAuth2 #

Description #

Designed for devices with limited input capabilities, involving a code entered by the user on a secondary device.

Use Cases #

Smart TVs
IoT devices

Security #

Moderately secure, depends on user entering the code on a trusted device.

Details of the flow #

blog

Step 1: Get a code #

So the first step of the flow is for the device to send an HTTP POST to the OAuth2 server’s device endpoint with a few fields formatted as JSON. In IDCS that URL is “/oauth2/v1/device” and the POST body looks like this:

post request


"response_type": "device_code",
"scope": "openid",
"client_id": "3e880dd2af3341f0ae84c899016d38a7"

response


"device_code": "49f4a78f-79f8-4d6d-ae0c-93d3d244b859",
"user_code": "934TXS",
"verification_uri": "https://idcs-XXXXXXXX.identity.oraclecloud.com/ui/v1/device",
"expires_in": 300,

The device_code is only known by the device and by IDCS and doesn’t need to be shown to the user.

The verification_url is also shown to the user. The device should show that URL to the user, tell them to open a browser on their computer / phone / tablet to that URL, and enter the user_code, or by using the QR Code, When the user goes to that URL if they’re not logged in they will be asked to do so in order to enter the user_code.

And finally the expires_in tells the device how long the device_code and user_code are valid. Most devices don’t show that information to the user but after the limit is reached it can show the user an error and give them an opportunity to get another code. Or it can just silently get another. I’ll talk more about that in a bit.

Step 2: Device Polls IDCS #

The POST payload for this contains 3 fields:


"client_id": "3e880dd2af3341f0ae84c899016d38a7",
"device_code": "49f4a78f-79f8-4d6d-ae0c-93d3d244b859",
"grant_type": "urn:ietf:params:oauth:grant-type:device_code"

waiting


"error": "authorization_pending",
"error_description": "The authorization for this token is pending."

Step 3: User uses their browser to enter the code #

Since the user might have to go find their laptop, maybe find the power cord, wait for it to boot up, open a browser, type in the URL, type in the URL a second time - this time without typos, and finally log in it’s possible that the device might be polling for a while. The device is going to keep on quietly polling IDCS (step 2) in the background all the while.

The next time the device polls IDCS with the device code IDCS will be ready to cough up an Access Token with the user’s identity embedded.

Step 4: Polling finishes #

Immediately after you hit submit in step 3 IDCS is ready to serve up an Access Token.


"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXJpb3VzbHk_ISI6IllvdSBkZWNvZGVkIHRoaXMgSldUIGp1c3QgdG8gc2VlIHdoYXQgd2FzIGhlcmU_ISBJIHByb21pc2UgeW91IG5vdGhpbmcgaW50ZXJlc3RpbmciLCJ1c2VyX3R6IjoiQW1lcmljYS9DaGljYWdvIiwic3ViIjoiY2hyaXN0b3BoZXIuam9obnNvbkBvcmFjbGUuY29tIiwidXNlcl9sb2NhbGUiOiJlbiIsInVzZXJfZGlzcGxheW5hbWUiOiJDaHJpc3RvcGhlciBKb2huc29uIiwidXNlci50ZW5hbnQubmFtZSI6InNvbWUgdGVuYW50IG5hbWUiLCJzdWJfbWFwcGluZ2F0dHIiOiJ1c2VyTmFtZSIsImlzcyI6Imh0dHBzOi8vaWRlbnRpdHkub3JhY2xlY2xvdWQuY29tLyIsInRva190eXBlIjoiQVQiLCJ1c2VyX3RlbmFudG5hbWUiOiJzb21lIHRlbmFudCBuYW1lIiwiY2xpZW50X2lkIjoiM2U4ODBkZDJhZjMzNDFmMGFlODRjODk5MDE2ZDM4YTciLCJ1c2VyX2lzQWRtaW4iOnRydWUsImF1ZCI6Imh0dHBzOi8vaWRjcy1YWFhYWFhYWC5pZGVudGl0eS5vcmFjbGVjbG91ZC5jb20iLCJ1c2VyX2lkIjoiOWNhMWQ5YjI2OTk2NDc1MDhiNWI0YmNmMTllNmUwZjAiLCJzdWJfdHlwZSI6InVzZXIiLCJzY29wZSI6Im9wZW5pZCIsImNsaWVudF90ZW5hbnRuYW1lIjoiaWRjcy1YWFhYWFhYWCIsInVzZXJfbGFuZyI6ImVuIiwiZXhwIjoxNTQzMzU1NDU3LCJpYXQiOjE1NDMzNTE4NTcsImNsaWVudF9ndWlkIjoiYWE3ZDY3Y2MxYWY1NDk5Yjg3ZjFjM2U5YmYxNzRiMDciLCJjbGllbnRfbmFtZSI6ImRldmljZSBjb2RlIHRlc3QiLCJ0ZW5hbnQiOiJpZGNzLVhYWFhYWFhYIiwianRpIjoiOTdiMDJkMTItODhiNi00ODA3LTk5MmUtMGNlOWVmZGVmZjY5In0.jsERIekF9OppQxsgPas2fx6UYVTpHZaTh737i4j2sME",
"expires_in": 3600,
"token_type": "Bearer"

The device now has an Access Token that it can use to talk to the Resource Server (RS) as normal. The RS doesn’t even need to know that the AT(Access Token) came via the Device Code flow.

Links to this note

Grant Types