docs: add device flow documentation #2026
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
7 tasks
vinckr
requested changes
Feb 21, 2025
| sidebar_label: Device authorization flow | ||
| --- | ||
|
|
||
| The OAuth 2.0 Device Authorization Grant (also known as Device Flow) is OAuth 2.0 extension that enables devices with no browser |
There was a problem hiding this comment.
Suggested change
| The OAuth 2.0 Device Authorization Grant (also known as Device Flow) is OAuth 2.0 extension that enables devices with no browser | |
| The OAuth 2.0 Device Authorization Grant -also known as Device Flow- is OAuth 2.0 extension that enables devices with no browser |
generally try to avoid parentheses in text
Comment on lines
+9
to
+10
| such as smart TVs, gaming consoles, or IoT devices, by delegating the authentication process to another device with a full browser | ||
| (e.g., a smartphone or computer). |
There was a problem hiding this comment.
Suggested change
| such as smart TVs, gaming consoles, or IoT devices, by delegating the authentication process to another device with a full browser | |
| (e.g., a smartphone or computer). | |
| such as smart TVs, gaming consoles, or IoT devices, by delegating the authentication process to another device with a full browser such as a smartphone or computer. |
avoid abbreviations like e.g.
| This document provides an overview of the Device Authorization Grant, a step-by-step example of its implementation, configuration | ||
| options, and guidance on creating custom user interfaces for the verification screen. | ||
|
|
||
| ## Overview of the Flow |
There was a problem hiding this comment.
Suggested change
| ## Overview of the Flow | |
| ## Overview of the flow |
sentence casing in headlines
Comment on lines
+20
to
+22
| 2. The user is instructed to visit a URL on a different device and is given a user code. | ||
| 3. On a different device the user, visits the URL, provides the user code, logs in and grants access to the device. | ||
| 4. The device polls the Authorization server. Once the user authenticates and grants access, an access token is returned that can |
There was a problem hiding this comment.
Suggested change
| 2. The user is instructed to visit a URL on a different device and is given a user code. | |
| 3. On a different device the user, visits the URL, provides the user code, logs in and grants access to the device. | |
| 4. The device polls the Authorization server. Once the user authenticates and grants access, an access token is returned that can | |
| 1. The user is instructed to visit a URL on a different device and is given a user code. | |
| 1. On a different device the user, visits the URL, provides the user code, logs in and grants access to the device. | |
| 1. The device polls the Authorization server. Once the user authenticates and grants access, an access token is returned that can |
markdown should number this automatically
|
|
||
| Here is the high-level overview for the Device Authorization Flow: | ||
|
|
||
| 1. The device requests to be authorized from the Authorization server. |
There was a problem hiding this comment.
is "Authorization server" a term that is specific to this flow here?
If yes I would say capitalize it as "Authorization Server"; pelase use "authorization server" throughout the document.
| Once the user enters the code, they are prompted to log in (if not already authenticated) and grant or deny permission to the | ||
| client. After granting permission, the user is redirected to a page confirming successful login. | ||
|
|
||
| ## Step 4: Device Polls for the Access Token |
There was a problem hiding this comment.
Suggested change
| ## Step 4: Device Polls for the Access Token | |
| ## Step 4: Device polls for the access token |
see above
|
|
||
| The user visits the provided URL on a separate device (e.g., a smartphone) and enters the code. | ||
|
|
||
| ## Step 3: User Grants Permission |
There was a problem hiding this comment.
Suggested change
| ## Step 3: User Grants Permission | |
| ## Step 3: User grants permission |
see above
|
|
||
| --- | ||
|
|
||
| ## Step 2: Display User Code and Verification URL |
There was a problem hiding this comment.
Suggested change
| ## Step 2: Display User Code and Verification URL | |
| ## Step 2: Display user code and verification URI |
is it URL or URI?
| 4. The device polls the Authorization server. Once the user authenticates and grants access, an access token is returned that can | ||
| be used to access the protected resource. | ||
|
|
||
| ### Step 1: Device Requests Authorization |
There was a problem hiding this comment.
Suggested change
| ### Step 1: Device Requests Authorization | |
| ### Step 1: Device requests authorization |
|
|
||
| Keep in mind that higher entropy may make it harder for the user to enter the user_code. | ||
|
|
||
| ## Device Verification UI implementation |
There was a problem hiding this comment.
Suggested change
| ## Device Verification UI implementation | |
| ## Device verification user interface implementation |
|
as for the place of the doc and also place in the sidebar we can check what the best place is once its ready to merge. @christiannwamba is currently working on a restructure of the docs, so depending on when its ready to merge we might have a different place for it. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Related Issue or Design Document
Adds docs for the device flow as implemented in ory/hydra#3912.
Checklist
If this pull request addresses a security vulnerability,
I confirm that I got approval (please contact [email protected]) from the maintainers to push the changes.
Further comments
I am not sure if this is the right place to place the doc, The rest of the docs in that folder do not reference hydra configurations, but the docs in the hydra folder do not seem to document oauth2/oidc flows. Please let me know if there is a better place for it.