From 0f6e684dfdd22525ff4066ac09591955091177e2 Mon Sep 17 00:00:00 2001 From: Nikos Date: Thu, 13 Feb 2025 14:09:37 +0100 Subject: [PATCH 01/17] docs: add device flow documentation --- docs/oauth2-oidc/device-authorization.mdx | 130 ++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 docs/oauth2-oidc/device-authorization.mdx diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx new file mode 100644 index 0000000000..e39a36c621 --- /dev/null +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -0,0 +1,130 @@ +--- +id: device-authorization +title: Device Authorization +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 +or limited input capability to obtain an access token. It enables users to authotize devices with limited input capabilities, such +as smart TVs, gaming consoles, or IoT devices, by delegating the authentication process to another device with a full browser such +as a phone or computer. + +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 + +Here is the high-level overview for the Device Authorization Flow: + +1. The device requests to be authorized from the Authorization Server. +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 + be used to access the protected resource. + +### Device requests authorization + +The user tries to log in through the limited input device. The device sends a POST request to the Authorization Server to initiate +the flow with the following parameters: + +- `client_id`: The ID of the client that's making the request. +- `scope` (optional): The scope of the access request, which specifies what resources the requesting application can access. + +The Authorization Server responds with the following information: + +- `device_code`: A unique code to identify the authorization request. +- `user_code`: A code the user will enter at the verification URL. +- `verification_uri`: The URL where the user can authorize the device. +- `verification_uri_complete`: The URL where the user can authorize the device, with the user_code already filled in. +- `expires_in`: The lifespan of the device code (in seconds). +- `interval`: The polling interval (in seconds) for the client to check if the user has authorized the device. + +### Display user code and verification URI + +The device shows the user the `user_code` and `verification_uri` it received from the Authorization Server. + +The user visits the provided URI on a separate device, such as a phone, and enters the code. + +### User grants permission + +Once the user enters the code, they're 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. + +### Device polls for the access token + +While the user is authorizing the device, the device polls the `token` endpoint of the Authorization Server to check whether the +user has completed the authorization process, by making a POST request with the following parameters: + +- `client_id`: The ID of the client that's making the request. +- `device_code`: The device code received from the device authorization request. +- `grant_type`: This should always be `urn:ietf:params:oauth:grant-type:device_code`. + +After the user grants permission, the Authorization Server will respond with an access token. + +## Configuration options + +### Configuring the user interface + +To enable and configure the Device Authorization Grant in Ory Hydra, adjust the following settings in your configuration file: + +``` +urls: + device: + verification: http://path/to/device/verification/ui + success: http://path/to/device/success +``` + +### Configuring user code entropy + +Depending on your security needs and your traffic load, you may wish to enhance your `user_code` entropy. The Ory Hydra +`oauth2.device_authorization.user_code_entropy` configuration supports 3 values: + +- `high`: `user_code` is 8 characters long and consists of alphanumeric characters, excluding some ambiguous symbols +- `medium`: `user_code` is 8 characters long and consists of upper case letter +- `low`: `user_code` is 9 characters long and consists of numbers + +Keep in mind that higher entropy may make it harder for the user to enter the user code. + +## Device verification user interface implementation + +Here is a sample implementation for a device verification UI : + +```js +import { Configuration, OAuth2Api } from "@ory/client" +import { Request, Response } from "express" + +const ory = new OAuth2Api( + new Configuration({ + basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`, + accessToken: process.env.ORY_API_KEY, + }), +) + +// Please note that this is an example implementation. +// In a production app, please add proper error handling. +export async function handleLogin(request: Request, response: Response) { + const challenge = request.query.device_challenge.toString() + const userCode = request.query.user_code.toString() + + // Show the login form if the form was not submitted. + if (request.method === "GET") { + response.render("device", { + challenge, + userCode, + }) + return + } + + // User was authenticated successfully, + return await ory + .acceptUserCodeRequest({ + deviceChallenge: challenge, + acceptDeviceUserCodeRequest: { + user_code: userCode, + }, + }) + .then(({ redirect_to }) => { + response.redirect(String(redirect_to)) + }) +} +``` From 8d3c50063166d957113e95e88dec0ee4087be07e Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Wed, 15 Oct 2025 17:10:32 -0700 Subject: [PATCH 02/17] chore: Refine device verification UI section wording --- docs/oauth2-oidc/device-authorization.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index e39a36c621..4aedc1c7ad 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -85,9 +85,9 @@ Depending on your security needs and your traffic load, you may wish to enhance Keep in mind that higher entropy may make it harder for the user to enter the user code. -## Device verification user interface implementation +## Device verification UI implementation -Here is a sample implementation for a device verification UI : +Here is a sample UI implementation for device verification: ```js import { Configuration, OAuth2Api } from "@ory/client" From 329b28284373b5ca2e054ed2f657417b4284fba4 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Wed, 15 Oct 2025 17:41:08 -0700 Subject: [PATCH 03/17] chore: Update user code entropy configuration details Clarified the description of user code entropy options and their implications for user entry. --- docs/oauth2-oidc/device-authorization.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index 4aedc1c7ad..692728f603 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -76,14 +76,14 @@ urls: ### Configuring user code entropy -Depending on your security needs and your traffic load, you may wish to enhance your `user_code` entropy. The Ory Hydra +Depending on your security needs and your traffic load, you should choose the appropriate `user_code` entropy. The `oauth2.device_authorization.user_code_entropy` configuration supports 3 values: - `high`: `user_code` is 8 characters long and consists of alphanumeric characters, excluding some ambiguous symbols -- `medium`: `user_code` is 8 characters long and consists of upper case letter -- `low`: `user_code` is 9 characters long and consists of numbers +- `medium`: `user_code` is 8 characters long and consists of only upper case alphabetic characters +- `low`: `user_code` is 9 characters long and consists of only numberic characters -Keep in mind that higher entropy may make it harder for the user to enter the user code. +As users will need to manually enter the user code, the higher the entropy, the more difficult it will be for the user to enter the user code. ## Device verification UI implementation From 87c75d110c800c6acf3f5a710747e091c0ab2890 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Wed, 15 Oct 2025 18:21:42 -0700 Subject: [PATCH 04/17] chore: Revise Device Authorization Grant documentation Updated the description and steps for the Device Authorization Grant to clarify the process and correct terminology. --- docs/oauth2-oidc/device-authorization.mdx | 65 ++++++++++++----------- 1 file changed, 33 insertions(+), 32 deletions(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index 692728f603..2ac66e1e54 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -4,68 +4,69 @@ title: Device Authorization 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 -or limited input capability to obtain an access token. It enables users to authotize devices with limited input capabilities, such -as smart TVs, gaming consoles, or IoT devices, by delegating the authentication process to another device with a full browser such -as a phone or computer. +The OAuth 2.0 Device Authorization Grant (RFC 8628) brings OAuth to devices with internet connectivity but limited input +capabilities. This flow is designed for smart TVs, streaming devices, IoT hardware, printers, AI agents and other connected devices +where typing credentials isn't practical. Here's how it works: the device to be authenticated displays a URL and a short code, prompting +you to open that URL on your phone or computer to authorize access. The two devices don't need to communicate directly—the authorization +happens through the OAuth provider. -This document provides an overview of the Device Authorization Grant, a step-by-step example of its implementation, configuration +This document provides an overview of the Ory's device authorization grant flow, with 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 -Here is the high-level overview for the Device Authorization Flow: +Here is the high-level overview for the device authorization grant flow: -1. The device requests to be authorized from the Authorization Server. -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 - be used to access the protected resource. +1. The user attempts to log in to the device. This initiates the device to request authorization from the authorization server. +1. When the authorization server responds, the user is instructed to visit a URL and enter the provided user code, which they do + on a different device. +1. On the different device the user visits the URL, enters the user code, (logs in, if needed) and grants access to the device. +1. In the meantime, the device polls the authorization server. Once the user authenticates and grants access, the authenicaton server + sends an access token to the device, which is used to access the protected resource. ### Device requests authorization -The user tries to log in through the limited input device. The device sends a POST request to the Authorization Server to initiate +The user attempts to log in through the limited input device. The device sends a POST request to the authorization server to initiate the flow with the following parameters: -- `client_id`: The ID of the client that's making the request. -- `scope` (optional): The scope of the access request, which specifies what resources the requesting application can access. +- `client_id`: The ID of the client (device) that's making the request. +- `scope` (optional): The scope of the access request, which specifies which resources the requesting device can access. -The Authorization Server responds with the following information: +The authorization server responds with the following information: -- `device_code`: A unique code to identify the authorization request. -- `user_code`: A code the user will enter at the verification URL. -- `verification_uri`: The URL where the user can authorize the device. -- `verification_uri_complete`: The URL where the user can authorize the device, with the user_code already filled in. -- `expires_in`: The lifespan of the device code (in seconds). -- `interval`: The polling interval (in seconds) for the client to check if the user has authorized the device. +- `device_code`: A unique code to identify the authorization request +- `user_code`: A code the user enters at the verification URL +- `verification_uri`: The URL where the user authorizes the device +- `verification_uri_complete`: The URL where the user authorizes the device, with the user_code already filled in +- `expires_in`: The lifespan of the device code (in seconds) +- `interval`: The polling interval (in seconds) for the client to check if the user has authorized the device yet ### Display user code and verification URI -The device shows the user the `user_code` and `verification_uri` it received from the Authorization Server. - -The user visits the provided URI on a separate device, such as a phone, and enters the code. +The device shows the user the `user_code` and `verification_uri` it received from the authorization server. ### User grants permission -Once the user enters the code, they're 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. +The user visits the provided URI on a separate device, such as a phone, and enters the code. Once the user enters the code, +the user is prompted to log in, if not already authenticated, and grants or denies permission to the client (device). After granting +permission, the user is redirected to a page confirming they are successfully logged in. ### Device polls for the access token -While the user is authorizing the device, the device polls the `token` endpoint of the Authorization Server to check whether the +While the user is authorizing the device, the device polls the `token` endpoint of the authorization server to check whether the user has completed the authorization process, by making a POST request with the following parameters: -- `client_id`: The ID of the client that's making the request. -- `device_code`: The device code received from the device authorization request. -- `grant_type`: This should always be `urn:ietf:params:oauth:grant-type:device_code`. +- `client_id`: The ID of the client that's making the request +- `device_code`: The device code returned from the authorization request +- `grant_type`: This must always be `urn:ietf:params:oauth:grant-type:device_code` -After the user grants permission, the Authorization Server will respond with an access token. +After the user grants permission, the authenicaton server sends an access token to the device, which is used to access the protected resource. ## Configuration options ### Configuring the user interface -To enable and configure the Device Authorization Grant in Ory Hydra, adjust the following settings in your configuration file: +To enable and configure the device authorization grant in Ory Hydra, adjust the following settings in your configuration file: ``` urls: From 6730380451d9cdcd065f48c4aff89477e4db912d Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Wed, 15 Oct 2025 18:27:53 -0700 Subject: [PATCH 05/17] chore: Update device authorization flow steps and formatting --- docs/oauth2-oidc/device-authorization.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index 2ac66e1e54..036820b137 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -5,7 +5,7 @@ sidebar_label: Device authorization flow --- The OAuth 2.0 Device Authorization Grant (RFC 8628) brings OAuth to devices with internet connectivity but limited input -capabilities. This flow is designed for smart TVs, streaming devices, IoT hardware, printers, AI agents and other connected devices +capabilities. This flow is designed for smart TVs, streaming devices, IoT hardware, printers, AI agents, and other connected devices where typing credentials isn't practical. Here's how it works: the device to be authenticated displays a URL and a short code, prompting you to open that URL on your phone or computer to authorize access. The two devices don't need to communicate directly—the authorization happens through the OAuth provider. @@ -24,13 +24,13 @@ Here is the high-level overview for the device authorization grant flow: 1. In the meantime, the device polls the authorization server. Once the user authenticates and grants access, the authenicaton server sends an access token to the device, which is used to access the protected resource. -### Device requests authorization +### Step 1: Device requests authorization The user attempts to log in through the limited input device. The device sends a POST request to the authorization server to initiate the flow with the following parameters: -- `client_id`: The ID of the client (device) that's making the request. -- `scope` (optional): The scope of the access request, which specifies which resources the requesting device can access. +- `client_id`: The ID of the client (device) that's making the request +- `scope` (optional): The scope of the access request, which specifies which resources the requesting device can access The authorization server responds with the following information: @@ -41,17 +41,17 @@ The authorization server responds with the following information: - `expires_in`: The lifespan of the device code (in seconds) - `interval`: The polling interval (in seconds) for the client to check if the user has authorized the device yet -### Display user code and verification URI +### Step 2: Display user code and verification URI The device shows the user the `user_code` and `verification_uri` it received from the authorization server. -### User grants permission +### Step 3: User grants permission The user visits the provided URI on a separate device, such as a phone, and enters the code. Once the user enters the code, the user is prompted to log in, if not already authenticated, and grants or denies permission to the client (device). After granting permission, the user is redirected to a page confirming they are successfully logged in. -### Device polls for the access token +### Step 4: Device polls for the access token While the user is authorizing the device, the device polls the `token` endpoint of the authorization server to check whether the user has completed the authorization process, by making a POST request with the following parameters: From 6511171ccdfcec7ff8f5816191ed659ae4349ed7 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Thu, 16 Oct 2025 14:35:59 -0700 Subject: [PATCH 06/17] chore: Added image for device authorization flow Added an image to illustrate the device authorization flow. --- docs/oauth2-oidc/device-authorization.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index 036820b137..4b2074ecd6 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -24,6 +24,8 @@ Here is the high-level overview for the device authorization grant flow: 1. In the meantime, the device polls the authorization server. Once the user authenticates and grants access, the authenicaton server sends an access token to the device, which is used to access the protected resource. +![Device authorization flow](/_static/deviceAuthFlow.png) + ### Step 1: Device requests authorization The user attempts to log in through the limited input device. The device sends a POST request to the authorization server to initiate From 055a4a3b9e3d739d843ae2d4c26b5521502464c9 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Thu, 16 Oct 2025 14:36:47 -0700 Subject: [PATCH 07/17] chore: Fix image path for device authorization flow --- docs/oauth2-oidc/device-authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index 4b2074ecd6..54035bd944 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -24,7 +24,7 @@ Here is the high-level overview for the device authorization grant flow: 1. In the meantime, the device polls the authorization server. Once the user authenticates and grants access, the authenicaton server sends an access token to the device, which is used to access the protected resource. -![Device authorization flow](/_static/deviceAuthFlow.png) +![Device authorization flow](./_static/deviceAuthFlow.png) ### Step 1: Device requests authorization From 1f9242583df8b890fd3a0b4f4b05de8c20fa0e5b Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Fri, 17 Oct 2025 08:03:27 -0700 Subject: [PATCH 08/17] chore: Integrate Mermaid diagram for device authorization flow Added a sequence diagram to illustrate the device authorization flow using Mermaid. --- docs/oauth2-oidc/device-authorization.mdx | 33 ++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index 54035bd944..d29f7bd605 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -24,7 +24,38 @@ Here is the high-level overview for the device authorization grant flow: 1. In the meantime, the device polls the authorization server. Once the user authenticates and grants access, the authenicaton server sends an access token to the device, which is used to access the protected resource. -![Device authorization flow](./_static/deviceAuthFlow.png) +```mdx-code-block +import Mermaid from "@site/src/theme/Mermaid"; + +>+AS: Start device code grant + AS-->>-D: Verification URI, Device-code, User-code + loop background poll before user authorized + D->>+AS: Request Token by device code + AS-->>-D: Error + end + D->>+U: Ask visit verification URI
Reveal User-code + U->>+AS: Request verification URI + AS-->>-U: Prompt for User-code + U->>+AS: Sumbit User-code + AS-->>-U: Prompt for login and consent + U->>+AS: Submit credentials and consent + AS-->>-U: Show success + deactivate U + loop background poll after user authorized + D->>+AS: Request Token by device code + end + AS-->>-D: Token + D-->>D: Process and store token + deactivate D +`} /> +``` ### Step 1: Device requests authorization From ac20e1127f32951833e5c05bf35dbc341de62e33 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Thu, 6 Nov 2025 14:21:50 -0800 Subject: [PATCH 09/17] Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik --- docs/oauth2-oidc/device-authorization.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index d29f7bd605..58c80d9268 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -5,8 +5,8 @@ sidebar_label: Device authorization flow --- The OAuth 2.0 Device Authorization Grant (RFC 8628) brings OAuth to devices with internet connectivity but limited input -capabilities. This flow is designed for smart TVs, streaming devices, IoT hardware, printers, AI agents, and other connected devices -where typing credentials isn't practical. Here's how it works: the device to be authenticated displays a URL and a short code, prompting +capabilities. This flow is designed for smart TVs, streaming devices, IoT hardware, printers, remote terminal sessions, AI agents, and other connected devices +where typing credentials or opening a browser isn't practical or possible. Here's how it works: the device to be authenticated displays a URL and a short code, prompting you to open that URL on your phone or computer to authorize access. The two devices don't need to communicate directly—the authorization happens through the OAuth provider. From 03ef2b0acd3282f72325638556705456d3036e57 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Thu, 6 Nov 2025 14:22:18 -0800 Subject: [PATCH 10/17] Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik --- docs/oauth2-oidc/device-authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index 58c80d9268..f1d9e29629 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -7,7 +7,7 @@ sidebar_label: Device authorization flow The OAuth 2.0 Device Authorization Grant (RFC 8628) brings OAuth to devices with internet connectivity but limited input capabilities. This flow is designed for smart TVs, streaming devices, IoT hardware, printers, remote terminal sessions, AI agents, and other connected devices where typing credentials or opening a browser isn't practical or possible. Here's how it works: the device to be authenticated displays a URL and a short code, prompting -you to open that URL on your phone or computer to authorize access. The two devices don't need to communicate directly—the authorization +you to open that URL on your phone or computer to authorize access. After successful authorization, the device will get an access and (optionally) a refresh token. The two devices don't need to communicate directly—the authorization happens through the OAuth provider. This document provides an overview of the Ory's device authorization grant flow, with a step-by-step example of its implementation, configuration From d6eedd43838d841a54840fe998f54ddb3423c2d0 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Thu, 6 Nov 2025 14:22:39 -0800 Subject: [PATCH 11/17] Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik --- docs/oauth2-oidc/device-authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index f1d9e29629..b9ff01c670 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -76,7 +76,7 @@ The authorization server responds with the following information: ### Step 2: Display user code and verification URI -The device shows the user the `user_code` and `verification_uri` it received from the authorization server. +The device shows the user the `user_code` and `verification_uri` it received from the authorization server. Depending on the device, this can be in the form of a URL, QR-code, acoustically, or any other form that the device can communicate with the user. ### Step 3: User grants permission From 825fb19d140102ec5a91a34b53a4d63308e1b841 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Thu, 6 Nov 2025 14:23:17 -0800 Subject: [PATCH 12/17] Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik --- docs/oauth2-oidc/device-authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index b9ff01c670..ea2328d38c 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -93,7 +93,7 @@ user has completed the authorization process, by making a POST request with the - `device_code`: The device code returned from the authorization request - `grant_type`: This must always be `urn:ietf:params:oauth:grant-type:device_code` -After the user grants permission, the authenicaton server sends an access token to the device, which is used to access the protected resource. +After the user grants their consent, the authentication server sends an access token to the device, which is used to access the protected resource. ## Configuration options From d6e798adfef3f9bb81301947f12239f4b22b86ef Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Thu, 6 Nov 2025 14:23:47 -0800 Subject: [PATCH 13/17] Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik --- docs/oauth2-oidc/device-authorization.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index ea2328d38c..1ade7b4631 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -101,10 +101,12 @@ After the user grants their consent, the authentication server sends an access t To enable and configure the device authorization grant in Ory Hydra, adjust the following settings in your configuration file: -``` +```yaml urls: device: + # The verification UI is where the user inputs the user-code verification: http://path/to/device/verification/ui + # The success UI is where the user is sent to after successful authorization success: http://path/to/device/success ``` From 0279663ac7b41c2c3f6fda204020ec8d560971f6 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Thu, 6 Nov 2025 14:24:55 -0800 Subject: [PATCH 14/17] Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik --- docs/oauth2-oidc/device-authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index 1ade7b4631..1ffc297e8e 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -113,7 +113,7 @@ urls: ### Configuring user code entropy Depending on your security needs and your traffic load, you should choose the appropriate `user_code` entropy. The -`oauth2.device_authorization.user_code_entropy` configuration supports 3 values: +`oauth2.device_authorization.user_code.entropy_preset` configuration supports 3 values: - `high`: `user_code` is 8 characters long and consists of alphanumeric characters, excluding some ambiguous symbols - `medium`: `user_code` is 8 characters long and consists of only upper case alphabetic characters From d3d0128341989aa37a315e9066bbb43a26197112 Mon Sep 17 00:00:00 2001 From: zepatrik Date: Fri, 7 Nov 2025 10:38:19 +0100 Subject: [PATCH 15/17] chore: address review comments and format --- docs/oauth2-oidc/device-authorization.mdx | 56 +++++++++++++++-------- 1 file changed, 37 insertions(+), 19 deletions(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index 1ffc297e8e..1eac465696 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -4,25 +4,26 @@ title: Device Authorization sidebar_label: Device authorization flow --- -The OAuth 2.0 Device Authorization Grant (RFC 8628) brings OAuth to devices with internet connectivity but limited input -capabilities. This flow is designed for smart TVs, streaming devices, IoT hardware, printers, remote terminal sessions, AI agents, and other connected devices -where typing credentials or opening a browser isn't practical or possible. Here's how it works: the device to be authenticated displays a URL and a short code, prompting -you to open that URL on your phone or computer to authorize access. After successful authorization, the device will get an access and (optionally) a refresh token. The two devices don't need to communicate directly—the authorization -happens through the OAuth provider. +The OAuth 2.0 Device Authorization Grant (RFC 8628) brings OAuth to devices with internet connectivity but limited input +capabilities. This flow is designed for smart TVs, streaming devices, IoT hardware, printers, remote terminal sessions, AI agents, +and other connected devices where typing credentials or opening a browser isn't practical or possible. Here's how it works: the +device to be authenticated displays a URL and a short code, prompting you to open that URL on your phone or computer to authorize +access. After successful authorization, the device will get an access and (optionally) a refresh token. The two devices don't need +to communicate directly—the authorization happens through the OAuth provider. -This document provides an overview of the Ory's device authorization grant flow, with a step-by-step example of its implementation, configuration -options, and guidance on creating custom user interfaces for the verification screen. +This document provides an overview of the Ory's device authorization grant flow, with 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 Here is the high-level overview for the device authorization grant flow: 1. The user attempts to log in to the device. This initiates the device to request authorization from the authorization server. -1. When the authorization server responds, the user is instructed to visit a URL and enter the provided user code, which they do +1. When the authorization server responds, the user is instructed to visit a URL and enter the provided user code, which they do on a different device. 1. On the different device the user visits the URL, enters the user code, (logs in, if needed) and grants access to the device. -1. In the meantime, the device polls the authorization server. Once the user authenticates and grants access, the authenicaton server - sends an access token to the device, which is used to access the protected resource. +1. In the meantime, the device polls the authorization server. Once the user authenticates and grants access, the authenicaton + server sends an access token to the device, which is used to access the protected resource. ```mdx-code-block import Mermaid from "@site/src/theme/Mermaid"; @@ -59,8 +60,8 @@ import Mermaid from "@site/src/theme/Mermaid"; ### Step 1: Device requests authorization -The user attempts to log in through the limited input device. The device sends a POST request to the authorization server to initiate -the flow with the following parameters: +The user attempts to log in through the limited input device. The device sends a POST request to the authorization server to +initiate the flow with the following parameters: - `client_id`: The ID of the client (device) that's making the request - `scope` (optional): The scope of the access request, which specifies which resources the requesting device can access @@ -76,12 +77,13 @@ The authorization server responds with the following information: ### Step 2: Display user code and verification URI -The device shows the user the `user_code` and `verification_uri` it received from the authorization server. Depending on the device, this can be in the form of a URL, QR-code, acoustically, or any other form that the device can communicate with the user. +The device shows the user the `user_code` and `verification_uri` it received from the authorization server. Depending on the +device, this can be in the form of a URL, QR-code, acoustically, or any other form that the device can communicate with the user. ### Step 3: User grants permission -The user visits the provided URI on a separate device, such as a phone, and enters the code. Once the user enters the code, -the user is prompted to log in, if not already authenticated, and grants or denies permission to the client (device). After granting +The user visits the provided URI on a separate device, such as a phone, and enters the code. Once the user enters the code, the +user is prompted to log in, if not already authenticated, and grants or denies permission to the client (device). After granting permission, the user is redirected to a page confirming they are successfully logged in. ### Step 4: Device polls for the access token @@ -93,7 +95,8 @@ user has completed the authorization process, by making a POST request with the - `device_code`: The device code returned from the authorization request - `grant_type`: This must always be `urn:ietf:params:oauth:grant-type:device_code` -After the user grants their consent, the authentication server sends an access token to the device, which is used to access the protected resource. +After the user grants their consent, the authentication server sends an access token to the device, which is used to access the +protected resource. ## Configuration options @@ -112,14 +115,29 @@ urls: ### Configuring user code entropy -Depending on your security needs and your traffic load, you should choose the appropriate `user_code` entropy. The +Depending on your security needs and your traffic load, you should choose the appropriate `user_code` entropy. The `oauth2.device_authorization.user_code.entropy_preset` configuration supports 3 values: - `high`: `user_code` is 8 characters long and consists of alphanumeric characters, excluding some ambiguous symbols - `medium`: `user_code` is 8 characters long and consists of only upper case alphabetic characters -- `low`: `user_code` is 9 characters long and consists of only numberic characters +- `low`: `user_code` is 9 characters long and consists of only numeric characters -As users will need to manually enter the user code, the higher the entropy, the more difficult it will be for the user to enter the user code. +It is also possible to configure the length and character set directly: + +```yaml +oauth2: + device_authorization: + user_code: + length: 8 + character_set: abcdefghijklmnopqrstuvwxyz0123456789 +``` + +It is important to strike the right balance between security and user-experience here. Higher entropy enhances security and +protects against an attacker randomly guessing valid user-codes. This is especially important the more concurrent device flows are +being performed. As users will need to manually enter the user code, the higher the entropy, the more difficult it will be for the +user to enter the user code. For better user-experience ambiguous characters should be avoided (e.g. `O` and `0` on any display, +or `1` and `7` on a 7-segment display). This is not of any concern when the user doesn't need to input the user-code manually, +e.g. by scanning a QR-code. ## Device verification UI implementation From e8280011e59e3afd0f99db81443b1b335aee983c Mon Sep 17 00:00:00 2001 From: vinckr Date: Mon, 10 Nov 2025 12:42:27 -0300 Subject: [PATCH 16/17] chore: add to sidebar --- src/sidebar.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/sidebar.ts b/src/sidebar.ts index 4adeae0c5e..d1f6909c3b 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -653,6 +653,7 @@ const hydra: SidebarItemsConfig = [ items: [ "oauth2-oidc/authorization-code-flow", "oauth2-oidc/client-credentials", + "oauth2-oidc/device-authorization", "oauth2-oidc/resource-owner-password-grant", "oauth2-oidc/refresh-token-grant", "oauth2-oidc/userinfo-oidc", From f94a41f03d5b8e0c2a705d9c130c301633de6629 Mon Sep 17 00:00:00 2001 From: vinckr Date: Mon, 10 Nov 2025 12:42:37 -0300 Subject: [PATCH 17/17] chore: fix grammar and typos --- docs/oauth2-oidc/device-authorization.mdx | 26 +++++++++++------------ 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/oauth2-oidc/device-authorization.mdx b/docs/oauth2-oidc/device-authorization.mdx index 1eac465696..fc8a901702 100644 --- a/docs/oauth2-oidc/device-authorization.mdx +++ b/docs/oauth2-oidc/device-authorization.mdx @@ -9,7 +9,7 @@ capabilities. This flow is designed for smart TVs, streaming devices, IoT hardwa and other connected devices where typing credentials or opening a browser isn't practical or possible. Here's how it works: the device to be authenticated displays a URL and a short code, prompting you to open that URL on your phone or computer to authorize access. After successful authorization, the device will get an access and (optionally) a refresh token. The two devices don't need -to communicate directly—the authorization happens through the OAuth provider. +to communicate directly; the authorization happens through the OAuth provider. This document provides an overview of the Ory's device authorization grant flow, with a step-by-step example of its implementation, configuration options, and guidance on creating custom user interfaces for the verification screen. @@ -21,8 +21,8 @@ Here is the high-level overview for the device authorization grant flow: 1. The user attempts to log in to the device. This initiates the device to request authorization from the authorization server. 1. When the authorization server responds, the user is instructed to visit a URL and enter the provided user code, which they do on a different device. -1. On the different device the user visits the URL, enters the user code, (logs in, if needed) and grants access to the device. -1. In the meantime, the device polls the authorization server. Once the user authenticates and grants access, the authenicaton +1. On the different device the user visits the URL, enters the user code, logs in, and grants access to the device. +1. In the meantime, the device polls the authorization server. Once the user authenticates and grants access, the authentication server sends an access token to the device, which is used to access the protected resource. ```mdx-code-block @@ -78,7 +78,7 @@ The authorization server responds with the following information: ### Step 2: Display user code and verification URI The device shows the user the `user_code` and `verification_uri` it received from the authorization server. Depending on the -device, this can be in the form of a URL, QR-code, acoustically, or any other form that the device can communicate with the user. +device, this can be in the form of a URL, QR code, acoustically, or any other form that the device can communicate with the user. ### Step 3: User grants permission @@ -89,7 +89,7 @@ permission, the user is redirected to a page confirming they are successfully lo ### Step 4: Device polls for the access token While the user is authorizing the device, the device polls the `token` endpoint of the authorization server to check whether the -user has completed the authorization process, by making a POST request with the following parameters: +user has completed the authorization process by making a POST request with the following parameters: - `client_id`: The ID of the client that's making the request - `device_code`: The device code returned from the authorization request @@ -100,7 +100,7 @@ protected resource. ## Configuration options -### Configuring the user interface +### Configure the user interface To enable and configure the device authorization grant in Ory Hydra, adjust the following settings in your configuration file: @@ -113,7 +113,7 @@ urls: success: http://path/to/device/success ``` -### Configuring user code entropy +### Configure user code entropy Depending on your security needs and your traffic load, you should choose the appropriate `user_code` entropy. The `oauth2.device_authorization.user_code.entropy_preset` configuration supports 3 values: @@ -132,12 +132,12 @@ oauth2: character_set: abcdefghijklmnopqrstuvwxyz0123456789 ``` -It is important to strike the right balance between security and user-experience here. Higher entropy enhances security and -protects against an attacker randomly guessing valid user-codes. This is especially important the more concurrent device flows are -being performed. As users will need to manually enter the user code, the higher the entropy, the more difficult it will be for the -user to enter the user code. For better user-experience ambiguous characters should be avoided (e.g. `O` and `0` on any display, -or `1` and `7` on a 7-segment display). This is not of any concern when the user doesn't need to input the user-code manually, -e.g. by scanning a QR-code. +It is important to strike the right balance between security and user experience here. Higher entropy enhances security and +protects against an attacker randomly guessing valid user-codes. This is especially important when more concurrent device flows +are being performed. As users will need to manually enter the user code, the higher the entropy, the more difficult it will be for +the user to enter the user code. For a better user experience, ambiguous characters should be avoided, for example `O` and `0` on +any display, or `1` and `7` on a 7-segment display. This isn't of any concern when the user doesn't need to input the user-code +manually, for example when scanning a QR code. ## Device verification UI implementation