Add device authorization doc

duzumaki · duzumaki · commit 481a97db21f3 · 2024-10-17T18:16:35.000+01:00
diff --git a/docs/oauth2/endpoints/device.rst b/docs/oauth2/endpoints/device.rst
@@ -0,0 +1,55 @@
+=============
+Device
+=============
+
+The device endpoint is used to initiate the authorization flow by requesting a set of
+verification codes from the authorization server by making an HTTP "POST" request to
+the device authorization endpoint.
+
+** Device Authorization Request **
+    The client makes a device authorization request to the device
+    authorization endpoint by including the following parameters using
+    the "application/x-www-form-urlencoded" format:
+
+    POST /device_authorization HTTP/1.1
+    Host: server.example.com
+    Content-Type: application/x-www-form-urlencoded
+    client_id=123456&scope=example_scope
+
+.. code-block:: python
+
+    # Initial setup
+    from your_validator import your_validator
+    verification_uri = "https://example.com/device"
+
+    def user_code():
+       # some logic to generate a random string...
+       return "123-456"
+
+    # user code is optional
+    server = DeviceApplicationServer(your_validator, verification_uri, user_code)
+
+    headers, data, status = server.create_device_authorization_response(request)
+
+     # response from /device_authorization endpoint on your server
+    from your_framework import http_response
+    http_response(data, status=status, headers=headers)
+
+
+
+.. code-block:: python
+
+    # example response
+    {
+        "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
+        "user_code": "123-456",
+        "verification_uri": "https://example.com/device",
+        "verification_uri_complete":
+            "https://example.com/device?user_code=WDJB-MJHT",
+        "expires_in": 1800,
+        "interval": 5
+    }
+
+
+.. autoclass:: oauthlib.oauth2.DeviceAuthorizationEndpoint
+    :members:
diff --git a/docs/oauth2/endpoints/endpoints.rst b/docs/oauth2/endpoints/endpoints.rst
@@ -15,6 +15,7 @@ client attempts to access the user resources on their behalf.
     :maxdepth: 2
 
     authorization
+    device
     introspect
     token
     metadata
diff --git a/docs/oauth2/preconfigured_servers.rst b/docs/oauth2/preconfigured_servers.rst
@@ -36,3 +36,7 @@ This function is passed the request object and a boolean indicating whether to g
 
 .. autoclass:: oauthlib.oauth2.BackendApplicationServer
     :members:
+
+
+.. autoclass:: oauthlib.oauth2.DeviceApplicationServer
+    :members:
diff --git a/oauthlib/oauth2/__init__.py b/oauthlib/oauth2/__init__.py
@@ -34,4 +34,4 @@
 from .rfc6749.tokens import BearerToken, OAuth2Token
 from .rfc6749.utils import is_secure_transport
 from .rfc8628.clients import DeviceClient
-from .rfc8628.endpoints import DeviceAuthorizationEndpoint
+from .rfc8628.endpoints import DeviceAuthorizationEndpoint, DeviceApplicationServer
diff --git a/oauthlib/oauth2/rfc8628/__init__.py b/oauthlib/oauth2/rfc8628/__init__.py
@@ -7,6 +7,5 @@
 """
 
 import logging
-from .pre_configured import DeviceApplicationServer
 
 log = logging.getLogger(__name__)
diff --git a/oauthlib/oauth2/rfc8628/endpoints/__init__.py b/oauthlib/oauth2/rfc8628/endpoints/__init__.py
@@ -6,3 +6,4 @@
 for consuming and providing OAuth 2.0 Device Authorization RFC8628.
 """
 from .device_authorization import DeviceAuthorizationEndpoint
+from .pre_configured import DeviceApplicationServer
diff --git a/oauthlib/oauth2/rfc8628/endpoints/pre_configured.py b/oauthlib/oauth2/rfc8628/endpoints/pre_configured.py
diff --git a/tests/oauth2/rfc8628/endpoints/test_error_responses.py b/tests/oauth2/rfc8628/endpoints/test_error_responses.py
@@ -3,7 +3,7 @@
 
 from oauthlib.common import Request, urlencode
 from oauthlib.oauth2.rfc6749 import errors
-from oauthlib.oauth2.rfc8628.pre_configured import DeviceApplicationServer
+from oauthlib.oauth2.rfc8628.endpoints.pre_configured import DeviceApplicationServer
 from oauthlib.oauth2.rfc8628.request_validator import RequestValidator
 
 
