chore: address review comments and format

Author: zepatrik

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