Add docs for device flow

Author: nkottary

docs/internals.md

@@ -104,3 +104,75 @@ stateDiagram-v2
 ```
 
 > **Note** This file is automatically generated by the `bin/structure.jl` script.
+
+## Device flow authentication
+
+Device flow authentication enables an application to authenticate a user by providing a link that can be opened on another device where the user can proceed with authentication. The application will be able to check whether the user has completed authentication on the other device by calling certain APIs. Finally, the application can retrieve the users OAuth token via the same API call. Device flow authentication becomes necessary on devices that do not have a browser based interface for regular login or applications that are not browser based such as command line applications. More details [here](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow).
+
+### Working of device flow in PkgAuthentication.jl
+
+We first call the dex [openid-configuration](https://dexidp.io/docs/openid-connect/) endpoint to determine whether the Pkg server supports device authentication. When device authentication is supported by the Pkg server we call the `/dex/device/code` endpoint. When the Pkg server does not support device authentication we fall back to the legacy browser authentication flow. The state machine for both flows are exactly the same (see diagram above). Only the http requests are different. The request and response for device code endpoint looks like:
+
+Request:
+
+```
+curl --request POST \
+    -H 'Accept: application/json' \
+    -H 'Content-Type: application/x-www-form-urlencoded' \
+    --data 'client_id=device&scope=openid email profile offline_access' \
+    https://juliahub.com/dex/device/code
+```
+
+Response:
+
+```json
+{
+   "device_code": "abcdefghijklmnopqrstuvwxyz1234567890",
+   "user_code": "FJMC-LPVR",
+   "verification_uri": "https://juliahub.com/dex/device",
+   "verification_uri_complete": "https://juliahub.com/dex/device?user_code=FJMC-LPVR",
+   "expires_in": 300,
+   "interval": 5
+}
+```
+
+The `verfication_uri_complete` value is opened in the browser for the user so that they can continue logging in. As in the legacy browser flow which calls `/claimtoken` to poll for completion of authentication, we call `/dex/token` when device authentication is available.
+
+The poll request looks like:
+
+```
+curl --request POST \
+    -H 'Accept: application/json' \
+    -H 'Content-Type: application/x-www-form-urlencoded' \
+    --data "client_id=device&scope=openid email profile offline_access&grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=$device_code" \
+    https://juliahub.com/dex/token
+```
+
+While the user hasn't finished authenticating, the response will be:
+
+```
+HTTP/1.1 401 Unauthorized
+
+{"error":"authorization_pending"}
+```
+
+Sometimes the response code might be 400.
+
+After the user is successfully authenticated, the response will be:
+
+```json
+{
+  "access_token": "abcdefghijklmnopqrstuvwxyz1234567890",
+  "token_type": "bearer",
+  "expires_in": 86399,
+  "refresh_token": "abcdefghijklmnopqrstuvwxyz1234567890",
+  "id_token": "abcdefghijklmnopqrstuvwxyz1234567890"
+}
+```
+
+We generate content for the `auth.toml` file with these values. We add some extra key/values to auth.toml when device authentication is enabled:
+- `client: "device"` This will help us distinguish between device authenticated auth.toml's and legacy auth.toml's.
+- `expires_at: <expires_in> + <time()>` This value is required to determine whether the token is expired and needs refresh. This is missing in the token response so we add it by summing the `expires_in` in value with the current timestamp. 
+- `refresh_url` This value is also missing in the device token response but is necessary for refreshing expired tokens. We create this field with value `<server>/auth/renew/token.toml/device/`.
+
+The mechanism to refresh the token is the same as in the legacy browser authentication flow.