diff --git a/docs/_images/application-register-device-code.png b/docs/_images/application-register-device-code.png new file mode 100644 index 000000000..4eac6d262 Binary files /dev/null and b/docs/_images/application-register-device-code.png differ diff --git a/docs/_images/device-approve-deny.png b/docs/_images/device-approve-deny.png new file mode 100644 index 000000000..dcff24b25 Binary files /dev/null and b/docs/_images/device-approve-deny.png differ diff --git a/docs/_images/device-enter-code-displayed.png b/docs/_images/device-enter-code-displayed.png new file mode 100644 index 000000000..201137ce3 Binary files /dev/null and b/docs/_images/device-enter-code-displayed.png differ diff --git a/docs/tutorial/tutorial.rst b/docs/tutorial/tutorial.rst index 5a0662507..140313673 100644 --- a/docs/tutorial/tutorial.rst +++ b/docs/tutorial/tutorial.rst @@ -9,4 +9,4 @@ Tutorials tutorial_03 tutorial_04 tutorial_05 - + tutorial_06 diff --git a/docs/tutorial/tutorial_06.rst b/docs/tutorial/tutorial_06.rst new file mode 100644 index 000000000..b1ff1d45d --- /dev/null +++ b/docs/tutorial/tutorial_06.rst @@ -0,0 +1,86 @@ +Device authorization grant flow +==================================================== + +Scenario +-------- +In :doc:`Part 1 ` 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 + +1: cd into the tests/app/idp directory + +.. code-block:: sh + curl --location 'http://127.0.0.1:8000/o/device-authorization/' \ + --header 'Content-Type: application/x-www-form-urlencoded' \ + --data-urlencode 'client_id={your application's client id}' + +The OAuth2 provider will return the following response: + +.. code-block:: json +{ + "verification_uri": "http://127.0.0.1:8000/o/device", + "expires_in": 1800, + "user_code": "A32RVADM", + "device_code": "G30j94v0kNfipD4KmGLTWeL4eZnKHm", + "interval": 5 +} + +Go to http://127.0.0.1:8000/o/device in browser + +.. image:: _images/device-enter-code-displayed.png + +Enter the code and it will redirect to the device-confirm endpoint + +/device-confirm endpoint [device polling is happening concurrently] +------------- + +.. image:: _images/device-approve-deny.png + +/Device polling [user approving or denying happens concurrently] +------------- +Note: You should already have the /token endpoint implemented in your authorization server before this. + +Send this request (in the real world the device makes this request): + +.. code-block:: sh + curl --location 'http://localhost:8000/o/token/' \ + --header 'Content-Type: application/x-www-form-urlencoded' \ + --data-urlencode 'device_code={the device code from the device-authorization response}' \ + --data-urlencode 'client_id={your application's client id}' \ + --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' + +.. code-block:: json +{ + "access_token": "SkJMgyL432P04nHDPyB63DEAM0nVxk", + "expires_in": 36000, + "token_type": "Bearer", + "scope": "openid", + "refresh_token": "Go6VumurDfFAeCeKrpCKPDtElV77id" +} + +