Add tutotial doc

Author: duzumaki

docs/_images/application-register-device-code.png

@@ -9,4 +9,4 @@ Tutorials
    tutorial_03
    tutorial_04
    tutorial_05
-
+   tutorial_06

docs/tutorial/tutorial.rst

@@ -0,0 +1,144 @@
+Device authorization grant flow
+====================================================
+
+Scenario
+--------
+In :doc:`Part 1 <tutorial_01>` you created your own :term:`Authorization Server` and it's running along just fine.
+You have devices that your users have and those users need to authenticate the device against your
+:term:`Authorization Server` in order to make the required api calls.
+
+Device Authorization
+-----------------
+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.
+
+
+Point your browser to http://127.0.0.1:8000/o/applications/register/ create an application.
+
+Fill the form as show in the screenshot below, and before saving take note of ``Client id``.
+Make sure the client type is set to "Public". There are cases where a confidential client makes sense
+but generally, it assumed the device is unable to safely store the client secret.
+
+.. image:: _images/application-register-device-code.png
+   :alt: Device Authorization application registration
+
+Ensure the setting OAUTH_DEVICE_VERIFICATION_URI is set to a uri you want to come back
+verification_uri key in the response. This is what the device will use display
+to the user
+
+.. code-block:: sh
+    curl -X POST \
+    --header 'Content-Type: application/x-www-form-urlencoded' \
+    "http://localhost:8008/o/device_authorization/" \
+    --data-urlencode 'client_id=${CLIENT_ID}}' \
+    --data-urlencode 'scope={your scope}'
+
+The OAuth2 provider will return the following response:
+
+.. code-block:: json
+    {
+        "verification_uri": "example.com/device",
+        "expires_in": 1800,
+        "user_code": "12345",
+        "device_code": "12345",
+        "interval": 5
+    }
+
+You will now need to implement your own /device and /device_confirm endpoints in
+your own :term:`Authorization Server`.((the name of these endpoints are up to you)  It should follow the RFC but device flow implementation usually
+extend beyond the RFC on authorization server to authorization server basis.
+
+You may see some implementations out there add an extra openid connect layer on top of this oauth 2 device flow
+for example.
+
+/device endpoint
+-------------
+
+following the rfc(https://datatracker.ietf.org/doc/html/rfc8628#section-3.3)
+your implementation may look like this
+
+.. code-block:: python
+    from oauthlib.oauth2.rfc8628.errors import (
+        AccessDenied,
+        AuthorizationPendingError,
+        ExpiredTokenError,
+    )
+    from oauth2_provider.models import Device, get_device_model
+
+    class DeviceForm(forms.Form):
+        user_code = forms.CharField(required=True)
+
+    def device_view(request, **kwargs):
+        form = forms.DeviceForm(request.POST)
+
+        if request.method != "POST":
+            # deny the request
+
+        user_code = form.cleaned_data['user_code']
+
+        # there should only be one
+        device: Device = get_device_model().objects.get(user_code=user_code)
+
+        if datetime.now(tz=UTC) > device.expires:
+            device.status = device.EXPIRED
+            device.save(update_fields=['status']) # this is saving to the db
+            raise ExpiredTokenError()
+
+        # If the decisions to approve/deny has already been made, the flow is considered done
+        if device.status in (device.DENIED, device.AUTHORIZED):
+            raise AccessDenied()
+
+        # Add a check to make sure the user is logged into their account
+        # as the /device endpoint is public
+        if request.user.is_authenticated is False:
+            # redirect to your app's login page
+            return http.HttpResponseRedirect(...)
+
+        # user is logged in and typed the user code in correctly. redirect to the the approve deny endpoint now
+        return http.HttpResponseRedirect(reverse("device-confirm", kwargs={"device_code": device.device_code}))
+
+
+/Device polling [user approving or denying happens concurrently]
+-------------
+
+Note: You should already have the /token endpoint implemented in your authorization server before this.
+
+After your app redirects to the device confirm/approve deny endpoint, your device must poll the authorization server's
+/token endpoint every "interval" amount of seconds to check if the user has approved or denied it. If approved
+your authorization server should return the access token back to the device.
+
+The /token endpoint should be behind a rate limiter that falls in line with the DEVICE_FLOW_INTERVAL setting.
+
+
+/device-confirm endpoint [device polling is happening concurrently]
+-------------
+The device confirm endpoint may look like this:
+
+.. code-block:: python
+    def device_confirm(request: http.HttpRequest, device_code: str):
+     device: Device = get_device_model().objects.get(device_code=device_code)
+
+        if device.status in (device.AUTHORIZED, device.DENIED):
+            return http.HttpResponse("Invalid")
+
+        if request.user.is_authenticated is False:
+            return http.HttpResponse("Nope")
+
+        action = request.POST.get('action')
+
+        if action == "accept":
+            device.status = device.AUTHORIZED
+            device.save(update_fields=["status"])
+            return http.HttpResponse("approved")
+        elif action == "deny":
+            device.status = device.DENIED
+            device.save(update_fields=["status"])
+            return http.HttpResponse("deny")
+
+        return render(request, 'authserver/accept_deny_device_access.html')