docs: Added the device authorization example. (#6598)

* Added the device authorization example.

* Update docs/docs/guides/solution-scenarios/device-authorization.mdx

Co-authored-by: Tim Möhlmann <tim+github@zitadel.com>

* Update docs/docs/guides/solution-scenarios/device-authorization.mdx

Co-authored-by: Tim Möhlmann <tim+github@zitadel.com>

---------

Co-authored-by: Tim Möhlmann <tim+github@zitadel.com>

docs/docs/guides/solution-scenarios/device-authorization.mdx

@@ -0,0 +1,120 @@
+---
+title: OAuth 2.0 Device Authorization Flow
+sidebar_label: Device Authorization
+---
+
+ZITADEL implements device authorization as per [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628). This document demonstrates its use.
+
+## Setup in ZITADEL
+
+1. Go to “Organization”/”Projects”.
+2. Under “Applications” click the “New” button.
+
+    <img src="/docs/img/device-auth/device-auth-01.png" alt="Device Authorization Flow in ZITADEL"/>
+
+3. Select “Native” and enter a name for the application, and click “Continue”.
+
+    <img src="/docs/img/device-auth/device-auth-02.png" alt="Device Authorization Flow in ZITADEL"/>
+
+4. Select “Device Code”. Click “Continue”.
+
+    <img src="/docs/img/device-auth/device-auth-03.png" alt="Device Authorization Flow in ZITADEL"/>
+
+
+5. Check the details and click “Create”.
+
+    <img src="/docs/img/device-auth/device-auth-04.png" alt="Device Authorization Flow in ZITADEL"/>
+
+6. Copy the “Client ID” and store it for later use.
+
+    <img src="/docs/img/device-auth/device-auth-05.png" alt="Device Authorization Flow in ZITADEL"/>
+
+## Device Client Example
+
+The [ZITADEL OpenID Connect client and server library](https://github.com/zitadel/oidc/) written for Go has a device client example, which can behave and authenticate as a device. In order to run this client, you need a recent version of Go (>=1.20) installed on your device.
+
+
+The example requires two environment variables to be set:
+
+
+- `ISSUER`: server address of your instance or domain. You can find the issuer URL in the “URLs” section. In this example, it will be set to [https://test-0o6zvq.zitadel.cloud](https://test-0o6zvq.zitadel.cloud). **Do not use a trailing slash!**
+
+    <img src="/docs/img/device-auth/device-auth-06.png" alt="Device Authorization Flow in ZITADEL"/>
+
+- `CLIENT_ID`: the Client ID we obtained earlier.
+
+
+Replace `ISSUER` and `CLIENT_ID` values with the ones you obtained and run the example as shown below:
+
+
+``` bash
+ISSUER="https://test-0o6zvq.zitadel.cloud" \
+CLIENT_ID="232685602728952637@device_auth" \
+go run github.com/zitadel/oidc/v2/example/client/device@latest
+```
+
+
+You should see some info-level log output with response data and a line with login instructions as given below:
+
+``` bash
+Please browse to https://test-0o6zvq.zitadel.cloud/device and enter code GQWC-FWFK
+INFO[0002] start polling  
+```
+
+At this point, the device app starts polling the token endpoint at 5-second intervals until the request is allowed, denied, or times out (currently 5 minutes).
+
+## Authenticate
+
+When you browse to the given URL and the device code is entered, the authentication flow for a user is started. If you are already logged in, it skips right ahead to the final screen where you can choose to allow or deny the request. If you are not logged in, you will have to enter your credentials for login.
+
+<img src="/docs/img/device-auth/device-auth-07.png" alt="Device Authorization Flow in ZITADEL"/>
+
+<img src="/docs/img/device-auth/device-auth-08.png" alt="Device Authorization Flow in ZITADEL"/>
+
+<img src="/docs/img/device-auth/device-auth-09.png" alt="Device Authorization Flow in ZITADEL"/>
+
+<img src="/docs/img/device-auth/device-auth-10.png" alt="Device Authorization Flow in ZITADEL"/>
+
+<img src="/docs/img/device-auth/device-auth-11.png" alt="Device Authorization Flow in ZITADEL"/>
+
+When “allow”  is clicked, the device (the CLI in this case) will receive a token on the next poll. A log line will be shown as given below:
+
+``` bash
+INFO[0165] successfully obtained token: &{Um2W5Od0yBU0KHfhP0AD0726rXrpxlepOR7yyftMvocgMWr25pVCuca1oiSSLiQjcXQqCEA Bearer  43199  }
+```
+
+At this point, the program terminates as it doesn’t have any other useful purpose. Regular device apps would of course use the token to consume the actual service.
+
+## Code URL
+
+During the start of the authorization flow ,there is a log line printed with the complete response object from ZITADEL that looks like this:
+
+``` bash
+resp&{dOcbPeysDhT26ZatRh9n7Q KPVZ-DJGG https://test-0o6zvq.zitadel.cloud/device https://test-0o6zvq.zitadel.cloud/device?user_code=GQWC-FWFK 300 5}
+```
+
+From this object, we used the `verification_uri` and `user_code` fields to print the information to the user to go to an address and enter the code. We also return a `verification_uri_complete` field,  which already includes the code and allows skipping manual entry of the code.
+
+
+``` bash
+https://test-0o6zvq.zitadel.cloud/device?user_code=GQWC-FWFK
+```
+
+In real-life applications, this could be used to create a QR code on the device screen, and users can use their mobile phones to scan the code to go to the required URL for authentication. In the context of this example, you can restart the device example program and copy/paste the complete link instead of manually entering it.
+
+## Security considerations
+
+The user uses a low entropy code to link a device to their account, which is easy to brute-force. Also, the code or QR might be displayed in environments where others could observe and use the code to authenticate the device (hijack the session) to their account.
+
+The device authorization grant specification was written with the philosophy that hijacking such sessions is not beneficial for the attacker. For example, with an on-demand streaming service, the attacker would be paying for the services the user is benefiting from. Hence, economically, the attack would not make sense.
+
+See [here](https://datatracker.ietf.org/doc/html/rfc8628#section-5) for more information.
+
+## Client library
+
+For Go clients, the ZITADEL OIDC repository already includes device authorization in the `rp` package.
+
+Use [rp.DeviceAuthorization](https://pkg.go.dev/github.com/zitadel/oidc/v2/pkg/client/rp#DeviceAuthorization) to start the flow and receive the URL and user code.
+[rp.DeviceAccessToken](https://pkg.go.dev/github.com/zitadel/oidc/v2/pkg/client/rp#DeviceAccessToken) polls the token endpoint and returns the access token once it succeeds.
+
+The client implementation is rather simple and can easily be recreated in other languages. Go can be used as an example, or simply follow the [RFC](https://datatracker.ietf.org/doc/html/rfc8628) as a guide.

docs/sidebars.js

@@ -361,6 +361,7 @@ module.exports = {
         "guides/solution-scenarios/domain-discovery",
         "guides/solution-scenarios/configurations",
         "guides/solution-scenarios/frontend-calling-backend-API",
+        "guides/solution-scenarios/device-authorization",
       ],
     },
     {