PySide6.QtNetworkAuth.QOAuth2DeviceAuthorizationFlow

class QOAuth2DeviceAuthorizationFlow

The QOAuth2DeviceAuthorizationFlow class provides an implementation of the Device Authorization Grant flow. More…

Inheritance diagram of PySide6.QtNetworkAuth.QOAuth2DeviceAuthorizationFlow

Added in version 6.9.

Synopsis

Properties

Methods

Slots

Signals

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

This class implements the Device Authorization Grant flow, which is used to obtain and refresh access tokens and ID tokens, particularly on devices lacking a user-agent or with limited input capabilities. These devices include televisions, machine HMIs, appliances, and IoT devices.

Device flow can be used on any platform and operating system that is capable of SSL/TLS requests. Unlike QOAuth2AuthorizationCodeFlow , this flow is not based on redirects, and therefore does not use a reply handler .

Device Flow Usage

The following snippets illustrate the typical usage. First, we set up the flow similarly to QOAuth2AuthorizationCodeFlow :

m_deviceFlow.setAuthorizationUrl(QUrl(authorizationUrl))
m_deviceFlow.setTokenUrl(QUrl(accessTokenUrl))
m_deviceFlow.setRequestedScopeTokens({scope})
m_deviceFlow.setClientIdentifier(clientIdentifier)
# The need for a client secret depends on the authorization server
m_deviceFlow.setClientIdentifierSharedKey(clientSecret)

Then we connect to authorizeWithUserCode signal to handle the user authorization:

m_deviceFlow.authorizeWithUserCode.connect(this,
    [](QUrl verificationUrl, QString userCode, QUrl completeVerificationUrl) {
        if completeVerificationUrl.isValid():
            # If the authorization server provided a complete URL
            # that already contains the necessary data as part of the URL parameters,
            # you can choose to use that
            print("Complete verification uri:", completeVerificationUrl)
        else:
            # Authorization server provided only verification URL; use that
            print("Verification uri and usercode:", verificationUrl, userCode)


)

This part is crucial to the flow, and how you handle it depends on your specific use case. One way or another, the user needs to complete the authorization.

Device flow does not define how this authorization completion is done, making it versatile for different use cases. This can be achieved by displaying the verification URI and user code to the user, who can then navigate to it on another device. Alternatively, you could present a QR code for the user to scan with their mobile device, send to a companion application, email to the user, and so on.

While authorization is pending, QOAuth2DeviceAuthorizationFlow polls the server at specific intervals (typically 5 seconds) until the user accepts or rejects the authorization, upon which the server responds accordingly and the flow concludes.

Errors can be detected as follows:

m_deviceFlow.requestFailed.connect(this, [](QAbstractOAuth::Error error) {
    Q_UNUSED(error)
    # Handle error
})
m_deviceFlow.serverReportedErrorOccurred.connect(this,
    [](QString error, QString errorDescription, QUrl uri) {
        # Check server reported error details if needed
        Q_UNUSED(error)
        Q_UNUSED(errorDescription)
        Q_UNUSED(uri)

)

serverReportedErrorOccurred() signal can be used to get information on specific RFC-defined errors. However, unlike requestFailed() , it doesn’t cover errors such as network errors or client configuration errors.

Flow completion is detected similarly as with QOAuth2AuthorizationCodeFlow , for example:

m_deviceFlow.granted.connect(this, [this](){
    # Here we use QNetworkRequestFactory to store the access token
    m_api.setBearerToken(m_deviceFlow.token().toLatin1())
})
m_deviceFlow.grant()

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property completeVerificationUrlᅟ: QUrl

This property holds an URL for user to complete the authorization. The URL itself contains the user_code and thus avoids the need for user to enter the code manually. Support for this complete URL varies between authorization servers.

See also

verificationUrl Device Flow Usage

Access functions:
property pollingᅟ: bool

This property holds whether or not the flow is actively polling for tokens.

Access functions:
property userCodeᅟ: str

This property holds the user_code received in authorization response. This code is used by the user to complete the authorization.

See also

verificationUrl completeVerificationUrl Device Flow Usage

Access functions:
property userCodeExpirationAtᅟ: QDateTime

This property holds the local time the user code and underlying device codes expire. The codes are typically valid between 5 and 30 minutes.

See also

userCode

Access functions:
property verificationUrlᅟ: QUrl

This property holds the URL where user should enter the user code to complete authorization.

See also

userCode completeVerificationUrl Device Flow Usage

Access functions:
__init__()

Constructs a QOAuth2DeviceAuthorizationFlow object.

__init__(parent)
Parameters:

parent – QObject

Constructs a QOAuth2DeviceAuthorizationFlow object with parent object parent.

__init__(manager[, parent=None])
Parameters:

Constructs a QOAuth2DeviceAuthorizationFlow object using parent as parent and sets manager as the network access manager.

authorizeWithUserCode(verificationUrl, userCode, completeVerificationUrl)
Parameters:

  • verificationUrl – QUrl

  • userCode – str

  • completeVerificationUrl – QUrl

This signal is emitted when user should complete the authorization.

If authorization server has provided completeVerificationUrl, user can navigate to that URL. The URL contains the needed userCode and any other needed parameters.

Alternatively, the user needs to navigate to verificationUrl and enter userCode manually.

See also

Device Flow Usage

completeVerificationUrl()
Return type:

QUrl

Getter of property completeVerificationUrlᅟ .

completeVerificationUrlChanged(completeVerificationUrl)
Parameters:

completeVerificationUrl – QUrl

Notification signal of property completeVerificationUrlᅟ .

isPolling()
Return type:

bool

Getter of property pollingᅟ .

pollingChanged(polling)
Parameters:

polling – bool

Notification signal of property pollingᅟ .

startTokenPolling()
Return type:

bool

Starts token polling. Returns true if the start was successful (or was already active), and false otherwise.

Calling this function is not necessary in a typical use case. Once the authorization request has completed, as a result of grant() call, the polling is started automatically.

This function can be useful in cases where resuming (retrying) the token polling a bit later is needed, without restarting the whole authorization flow. For example in case of a transient network connectivity loss.

Polling interval is defined by the authorization server, and is typically 5 seconds. First poll request is sent once the first interval has elapsed.

See also

polling stopTokenPolling() Device Flow Usage

stopTokenPolling()

Stops token polling. Any potential outstanding poll requests are silently discarded.

See also

polling startTokenPolling()

userCode()
Return type:

str

Getter of property userCodeᅟ .

userCodeChanged(userCode)
Parameters:

userCode – str

Notification signal of property userCodeᅟ .

userCodeExpirationAt()
Return type:

QDateTime

Getter of property userCodeExpirationAtᅟ .

userCodeExpirationAtChanged(expiration)
Parameters:

expiration – QDateTime

Notification signal of property userCodeExpirationAtᅟ .

verificationUrl()
Return type:

QUrl

Getter of property verificationUrlᅟ .

verificationUrlChanged(verificationUrl)
Parameters:

verificationUrl – QUrl

Notification signal of property verificationUrlᅟ .