QOAuth2DeviceAuthorizationFlow Class
La clase `QOAuth2DeviceAuthorizationFlow` proporciona una implementación del flujo de concesión de autorización de dispositivo. Más información...
| Encabezado: | #include <QOAuth2DeviceAuthorizationFlow> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS NetworkAuth) target_link_libraries(mytarget PRIVATE Qt6::NetworkAuth) |
| qmake: | QT += networkauth |
| Desde: | Qt 6.9 |
| Heredan de: | QAbstractOAuth2 |
Propiedades
|
|
Funciones públicas
| QOAuth2DeviceAuthorizationFlow() | |
| QOAuth2DeviceAuthorizationFlow(QObject *parent) | |
| QOAuth2DeviceAuthorizationFlow(QNetworkAccessManager *manager, QObject *parent = nullptr) | |
| virtual | ~QOAuth2DeviceAuthorizationFlow() override |
| QUrl | completeVerificationUrl() const |
| bool | isPolling() const |
| QString | userCode() const |
| QDateTime | userCodeExpirationAt() const |
| QUrl | verificationUrl() const |
Ranuras públicas
| virtual void | grant() override |
| bool | startTokenPolling() |
| void | stopTokenPolling() |
Señales
| void | authorizeWithUserCode(const QUrl &verificationUrl, const QString &userCode, const QUrl &completeVerificationUrl) |
| void | completeVerificationUrlChanged(const QUrl &completeVerificationUrl) |
| void | pollingChanged(bool polling) |
| void | userCodeChanged(const QString &userCode) |
| void | userCodeExpirationAtChanged(const QDateTime &expiration) |
| void | verificationUrlChanged(const QUrl &verificationUrl) |
Ranuras protegidas
(since 6.9) void | refreshTokensImplementation() |
Descripción detallada
Esta clase implementa el flujo de concesión de autorización de dispositivos, que se utiliza para obtener y actualizar tokens de acceso y tokens de identificación, especialmente en dispositivos que carecen de agente de usuario o con capacidades de entrada limitadas. Entre estos dispositivos se incluyen televisores, interfaces hombre-máquina (HMI), electrodomésticos y dispositivos del Internet de las cosas (IoT).
El flujo de dispositivo se puede utilizar en cualquier plataforma y sistema operativo capaz de realizar solicitudes SSL/TLS. A diferencia de QOAuth2AuthorizationCodeFlow, este flujo no se basa en redireccionamientos y, por lo tanto, no utiliza un reply handler.
Uso del «Device Flow»
Los siguientes fragmentos de código ilustran el uso habitual. En primer lugar, configuramos el flujo de forma similar a 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);A continuación, conectamos la señal de authorizeWithUserCode para gestionar la autorización del usuario:
connect(&m_deviceFlow, &QOAuth2DeviceAuthorizationFlow::authorizeWithUserCode, this,
[](const QUrl&verificationUrl, const QString&userCode, const QUrl&completeVerificationUrl) {
if (completeVerificationUrl.isValid()) {
// Si el servidor de autorización ha proporcionado una URL completa
// que ya contiene los datos necesarios como parte de los parámetros de la URL,
// puedes optar por utilizarla
qDebug() << "Complete verification uri:" << completeVerificationUrl;
} else {
// El servidor de autorización solo ha facilitado una URL de verificación; utilízala
qDebug() << "Verification uri and usercode:" << verificationUrl << userCode;
}
}
);Esta parte es fundamental para el flujo, y la forma de gestionarla depende de tu caso de uso específico. De una forma u otra, el usuario debe completar la autorización.
El flujo del dispositivo no define cómo se lleva a cabo esta finalización de la autorización, lo que lo hace versátil para diferentes casos de uso. Esto se puede lograr mostrando al usuario el URI de verificación y el código de usuario, de modo que pueda acceder a ellos desde otro dispositivo. Como alternativa, se puede mostrar un código QR para que el usuario lo escanee con su dispositivo móvil, enviarlo a una aplicación complementaria, enviarlo por correo electrónico al usuario, etc.
Mientras la autorización está pendiente, QOAuth2DeviceAuthorizationFlow consulta al servidor a intervalos específicos (normalmente cada 5 segundos) hasta que el usuario acepta o rechaza la autorización, tras lo cual el servidor responde en consecuencia y el flujo concluye.
Los errores se pueden detectar de la siguiente manera:
connect(&m_deviceFlow, &QAbstractOAuth::requestFailed, this, [](QAbstractOAuth::Error error) {
Q_UNUSED(error);
// Handle error
});
connect(&m_deviceFlow, &QAbstractOAuth2::serverReportedErrorOccurred, this,
[](const QString &error, const QString &errorDescription, const QUrl &uri) {
// Check server reported error details if needed
Q_UNUSED(error);
Q_UNUSED(errorDescription);
Q_UNUSED(uri);
}
);QAbstractOAuth2::serverReportedErrorOccurredLa señal () se puede utilizar para obtener información sobre errores específicos definidos en el RFC. Sin embargo, a diferencia de QAbstractOAuth::requestFailed(), no cubre errores como los de red o los de configuración del cliente.
La finalización del flujo se detecta de forma similar a como se hace con ` QOAuth2AuthorizationCodeFlow`, por ejemplo:
connect(&m_deviceFlow, &QAbstractOAuth::granted, this, [this](){
// Here we use QNetworkRequestFactory to store the access token
m_api.setBearerToken(m_deviceFlow.token().toLatin1());
});
m_deviceFlow.grant();Documentación de propiedades
[read-only] completeVerificationUrl : QUrl
Esta propiedad contiene una URL para que el usuario complete la autorización. La propia URL incluye el user_code, lo que evita que el usuario tenga que introducir el código manualmente. La compatibilidad con esta URL completa varía según los servidores de autorización.
Funciones de acceso:
| QUrl | completeVerificationUrl() const |
Señal de notificador:
| void | completeVerificationUrlChanged(const QUrl &completeVerificationUrl) |
Véase también verificationUrl y Device Flow Usage.
[read-only] polling : bool
Esta propiedad indica si el flujo está realizando un sondeo activo en busca de tokens o no.
Funciones de acceso:
| bool | isPolling() const |
Señal del notificador:
| void | pollingChanged(bool polling) |
Véase también startTokenPolling() y stopTokenPolling().
[read-only] userCode : QString
Esta propiedad contiene el «user_code» recibido en la respuesta de autorización. El usuario utiliza este código para completar la autorización.
Funciones de acceso:
| QString | userCode() const |
Señal de notificador:
| void | userCodeChanged(const QString &userCode) |
Véase también verificationUrl, completeVerificationUrl y Device Flow Usage.
[read-only] userCodeExpirationAt : QDateTime
Esta propiedad contiene la hora local a la que caducan el código de usuario y los códigos del dispositivo subyacente. Por lo general, los códigos tienen una validez de entre 5 y 30 minutos.
Funciones de acceso:
| QDateTime | userCodeExpirationAt() const |
Señal de notificación:
| void | userCodeExpirationAtChanged(const QDateTime &expiration) |
Véase también userCode.
[read-only] verificationUrl : QUrl
Esta propiedad contiene la URL en la que el usuario debe introducir el código de usuario para completar la autorización.
Funciones de acceso:
| QUrl | verificationUrl() const |
Señal de notificador:
| void | verificationUrlChanged(const QUrl &verificationUrl) |
Véase también userCode, completeVerificationUrl y Device Flow Usage.
Documentación de las funciones de miembro
QOAuth2DeviceAuthorizationFlow::QOAuth2DeviceAuthorizationFlow()
Crea un objeto QOAuth2DeviceAuthorizationFlow.
[explicit] QOAuth2DeviceAuthorizationFlow::QOAuth2DeviceAuthorizationFlow(QObject *parent)
Crea un objeto `QOAuth2DeviceAuthorizationFlow` cuyo objeto padre es ` parent`.
[explicit] QOAuth2DeviceAuthorizationFlow::QOAuth2DeviceAuthorizationFlow(QNetworkAccessManager *manager, QObject *parent = nullptr)
Crea un objeto `QOAuth2DeviceAuthorizationFlow` utilizando ` parent ` como objeto padre y establece ` manager ` como gestor de acceso a la red.
[override virtual noexcept] QOAuth2DeviceAuthorizationFlow::~QOAuth2DeviceAuthorizationFlow()
Elimina la instancia de « QOAuth2DeviceAuthorizationFlow ».
[signal] void QOAuth2DeviceAuthorizationFlow::authorizeWithUserCode(const QUrl &verificationUrl, const QString &userCode, const QUrl &completeVerificationUrl)
Esta señal se emite cuando el usuario debe completar el proceso de autorización.
Si el servidor de autorización ha facilitado completeVerificationUrl, el usuario puede acceder a esa URL. La URL contiene el userCode necesario y cualquier otro parámetro requerido.
Como alternativa, el usuario debe acceder a verificationUrl e introducir userCode manualmente.
Véase también Device Flow Usage.
[override virtual slot] void QOAuth2DeviceAuthorizationFlow::grant()
Reimplementa: QAbstractOAuth::grant().
Inicia el flujo de autorización tal y como se describe en el RFC de autorización por dispositivo.
El flujo consta de los siguientes pasos:
- Solicitud de autorización al servidor de autorización
- El usuario autoriza el acceso; véase authorizeWithUserCode()
- Consulta al servidor de autorización hasta que el usuario haya aceptado o rechazado la autorización (o hasta que caduquen los códigos)
- Notificación del resultado a la aplicación (véase granted() y QAbstractOAuth::requestFailed())
El flujo avanza automáticamente desde la autorización hasta la consulta de tokens.
Al llamar a esta función se restablecerán todos los datos de autorización anteriores.
Véase también authorizeWithUserCode(), granted(), QAbstractOAuth::requestFailed(), polling, startTokenPolling(), stopTokenPolling() y Device Flow Usage.
[protected slot, since 6.9] void QOAuth2DeviceAuthorizationFlow::refreshTokensImplementation()
Esta función envía una solicitud de actualización del token.
Si la solicitud de actualización se ha iniciado correctamente, el estado se establece en « QAbstractOAuth::Status::RefreshingToken »; en caso contrario, se emite la señal « requestFailed()» y el estado no cambia. Los tokens no se pueden actualizar mientras « isPolling » esté en « true ».
Esta función no tiene ningún efecto si el proceso de actualización del token ya está en curso.
Si falla la actualización del token y existe un token de acceso, el estado se establece en QAbstractOAuth::Status::Granted, y en QAbstractOAuth::Status::NotAuthenticated si no existe ningún token de acceso.
Esta función se introdujo en Qt 6.9.
Véanse también QAbstractOAuth::requestFailed() y QAbstractOAuth2::refreshTokens().
[slot] bool QOAuth2DeviceAuthorizationFlow::startTokenPolling()
Inicia la comprobación de tokens. Devuelve « true » si el inicio se ha realizado correctamente (o si ya estaba activo), y « false » en caso contrario.
No es necesario llamar a esta función en un caso de uso habitual. Una vez completada la solicitud de autorización, como resultado de la llamada a grant(), la consulta se inicia automáticamente.
Esta función puede resultar útil en casos en los que sea necesario reanudar (reintentar) la consulta del token un poco más tarde, sin tener que reiniciar todo el flujo de autorización. Por ejemplo, en caso de una pérdida transitoria de conectividad de red.
El intervalo de sondeo lo define el servidor de autorización y suele ser de 5 segundos. La primera solicitud de sondeo se envía una vez transcurrido el primer intervalo.
Véase también polling, stopTokenPolling() y Device Flow Usage.
[slot] void QOAuth2DeviceAuthorizationFlow::stopTokenPolling()
Detiene el sondeo de tokens. Cualquier solicitud de sondeo pendiente se descarta sin aviso.
Véase también polling y startTokenPolling().
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.