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

# Initial setup
from your_validator import your_validator
verification_uri = "https://example.com/device"

# verification_uri_complete can either be a callable that receives user code as an arg
# or a string (e.g verification_uri_complete = "https://example.com/device=1234")
verification_uri_complete = lambda user_code: f"https://example.com/device={user_code}"

def user_code():
   # some logic to generate a random string...
   return "123-456"

# user code is optional
server = DeviceApplicationServer(
    request_validator=your_validator,
    verification_uri=verification_uri,
    verification_uri_complete=verification_uri_complete,
    user_code=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)

# 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
}

class oauthlib.oauth2.DeviceAuthorizationEndpoint(request_validator, verification_uri, expires_in=1800, interval=None, verification_uri_complete=None, user_code_generator: Callable[[None], str] = None)[source]

DeviceAuthorization endpoint - used by the client 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.

The client authentication requirements of Section 3.2.1 of [RFC6749] apply to requests on this endpoint, which means that confidential clients (those that have established client credentials) authenticate in the same manner as when making requests to the token endpoint, and public clients provide the “client_id” parameter to identify themselves.

create_device_authorization_response(uri, http_method='POST', body=None, headers=None)[source]

Generate a unique device verification code and an end-user code that are valid for a limited time. Include them in the HTTP response body using the “application/json” format [RFC8259] with a 200 (OK) status code, as described in Section-3.2.

Parameters:

uri (str) – The full URI of the token request.
request (oauthlib.common.Request) – OAuthlib request.
user_code_generator (Callable[[], str]) – A callable that returns a string for the user code. This allows the caller to decide how the user_code should be formatted.

Returns:

A tuple of three elements: 1. A dict of headers to set on the response. 2. The response body as a string. 3. The response status code as an integer.

Return type:

tuple

The response contains the following parameters:

device_code: REQUIRED. The device verification code.
user_code: REQUIRED. The end-user verification code.
verification_uri: REQUIRED. The end-user verification URI on the authorization server. The URI should be short and easy to remember as end users will be asked to manually type it into their user agent.
verification_uri_complete: OPTIONAL. A verification URI that includes the user_code (or other information with the same function as the user_code), which is designed for non-textual transmission.
expires_in: REQUIRED. The lifetime in seconds of the device_code and user_code.
interval: OPTIONAL. The minimum amount of time in seconds that the client SHOULD wait between polling requests to the token endpoint. If no value is provided, clients MUST use 5 as the default.

For example:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://example.com/device",
  "verification_uri_complete":
      "https://example.com/device?user_code=WDJB-MJHT",
  "expires_in": 1800,
  "interval": 5
}

property expires_in: The lifetime in seconds of the “device_code” and “user_code”.

property interval: The minimum amount of time in seconds that the client SHOULD wait between polling requests to the token endpoint. If no value is provided, clients MUST use 5 as the default.

validate_device_authorization_request(request)[source]

Validate the device authorization request.

The client_id is required if the client is not authenticating with the authorization server as described in Section 3.2.1. of [RFC6749]. The client identifier as described in Section 2.2 of [RFC6749].

property verification_uri: The end-user verification URI on the authorization server. The URI should be short and easy to remember as end users will be asked to manually type it into their user agent.