website/docs: "Device code flow" documentation improvements (#14257)
* Improved RFC reference Replaced "abilities" with "capabilities" to better reflect RFC wording, added extended summary from RFC to ensure complete and clear understanding. Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Improved documentation Added link for brand keyword, removed repetition Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Improved UX Marked keywords with Capital letters and proper formatting to clarify those are references to actual values/labels Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * SEO Optimization Added alternative name to "also known" section to improve searchability Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Added step-by-step tutorial for setup Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * "Relative vs. absolute paths" rule Removed full link in favor of relative path Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Fixed formatting according to style guide Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Fixed relative path Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Update website/docs/add-secure-apps/providers/oauth2/device_code.md Co-authored-by: Dominic R <dominic@sdko.org> Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Update website/docs/add-secure-apps/providers/oauth2/device_code.md Co-authored-by: Dominic R <dominic@sdko.org> Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Update website/docs/add-secure-apps/providers/oauth2/device_code.md Co-authored-by: Dominic R <dominic@sdko.org> Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Update website/docs/add-secure-apps/providers/oauth2/device_code.md Co-authored-by: Dominic R <dominic@sdko.org> Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Update website/docs/add-secure-apps/providers/oauth2/device_code.md Co-authored-by: Dominic R <dominic@sdko.org> Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Update website/docs/add-secure-apps/providers/oauth2/device_code.md Co-authored-by: Dominic R <dominic@sdko.org> Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Update device_code.md removed newline as per "prettier --write" Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Update website/docs/add-secure-apps/providers/oauth2/device_code.md Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com> Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> * Update website/docs/add-secure-apps/providers/oauth2/device_code.md Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com> Signed-off-by: Dewi Roberts <dewi@goauthentik.io> * Update device_code.md brute forced it here... Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com> --------- Signed-off-by: Dametto Luca <45915503+LucaTheHacker@users.noreply.github.com> Signed-off-by: Dewi Roberts <dewi@goauthentik.io> Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com> Co-authored-by: Dominic R <dominic@sdko.org> Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com> Co-authored-by: Dewi Roberts <dewi@goauthentik.io>
This commit is contained in:
@ -1,18 +1,20 @@
|
||||
# Device code flow
|
||||
---
|
||||
title: Device code flow
|
||||
---
|
||||
|
||||
(Also known as device flow and [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628))
|
||||
The device code flow is also known as _device flow_ or _device authorization grant flow_. This type of authentication flow is useful for devices with limited input capabilities and/or devices without browsers. The Request for Comments (RFC) 8628) abstract for this flow states:
|
||||
|
||||
This type of authentication flow is useful for devices with limited input abilities and/or devices without browsers.
|
||||
> The OAuth 2.0 device authorization grant is designed for Internet-connected devices that either lack a browser to perform a user-agent-based authorization or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorization flow is impractical. It enables OAuth clients on such devices (like smart TVs, media consoles, digital picture frames, and printers) to obtain user authorization to access protected resources by using a user agent on a separate device.
|
||||
|
||||
### Requirements
|
||||
|
||||
This device flow is only possible if the active brand has a device code flow setup. This device code flow is run _after_ the user logs in, and before the user authenticates.
|
||||
This device flow is only possible if the active [brand](../../../sys-mgmt/brands.md) has a device code flow configured. This flow is run _after_ the user logs in, and before the user authenticates.
|
||||
|
||||
authentik doesn't ship with a default flow for this usecase, so it is recommended to create a new flow for this usecase with the designation of _Stage configuration_
|
||||
authentik does not include a default flow for this use case, so it is necessary to create a new one with a **Designation** of `Stage Configuration`.
|
||||
|
||||
### Device-side
|
||||
### Device flow initiation
|
||||
|
||||
The flow is initiated by sending a POST request to the device authorization endpoint, `/application/o/device/` with the following contents:
|
||||
The flow is initiated by sending a POST request to the device authorization endpoint, `/application/o/device/`, with the following contents:
|
||||
|
||||
```http
|
||||
POST /application/o/device/ HTTP/1.1
|
||||
@ -32,8 +34,6 @@ The response contains the following fields:
|
||||
- `expires_in`: The total seconds after which this token will expire
|
||||
- `interval`: The interval in seconds for how often the device should check the token status
|
||||
|
||||
---
|
||||
|
||||
With this response, the device can start checking the status of the token by sending requests to the token endpoint like this:
|
||||
|
||||
```http
|
||||
@ -50,7 +50,7 @@ If the user has not opened the link above yet, or has not finished the authentic
|
||||
|
||||
If the user _has_ finished the authentication and authorization, the response will be similar to any other generic OAuth2 Token request, containing `access_token` and `id_token`.
|
||||
|
||||
### Creating and applying a device code flow
|
||||
### Create and apply a device code flow
|
||||
|
||||
1. Log in to authentik as an admin, and open the authentik Admin interface.
|
||||
2. Navigate to **Flows and Stages** > **Flows** and click **Create**.
|
||||
|
Reference in New Issue
Block a user