Compatibilidad de Qt con OAuth2 en el navegador
Agentes de usuario de OAuth2
La fase de autorización de OAuth2 se basa en un agente de usuario, que suele ser el navegador del sistema o un agente de usuario integrado, como Qt WebEngine.
La elección entre el navegador del sistema y un agente de usuario integrado depende de varios factores. A continuación se describen algunas de las principales consideraciones:
- Es posible que el navegador del sistema ya tenga sesiones de inicio de sesión activas del usuario. Por lo tanto, la autenticación del usuario durante la etapa de autorización puede ser más sencilla, ya que se puede utilizar la sesión existente. En cambio, con un agente de usuario integrado, el usuario suele tener que iniciar sesión de nuevo. Por otro lado, dejar una sesión abierta en el navegador del sistema puede no ser siempre lo más recomendable. Los navegadores del sistema también pueden compartir datos de uso de la aplicación con terceros.
- El navegador del sistema suele resultar familiar para el usuario y ofrece una experiencia de usuario conocida a la hora de iniciar sesión. Por otro lado, aunque un agente de usuario integrado pueda ofrecer una apariencia y un funcionamiento menos familiares, el desarrollador de la aplicación puede integrar la interacción de inicio de sesión como parte de la ventana de la aplicación, en lugar de que se produzca en una ventana de navegador independiente. Además, el desarrollador de la aplicación puede automatizar el cierre del agente de usuario integrado cuando ya no sea necesario.
- Los navegadores del sistema ofrecen elementos visuales de seguridad conocidos, como la barra de direcciones y la validación de certificados para el usuario. Es posible que estos no sean visibles en un agente de usuario integrado. Además, los navegadores del sistema pueden aprovechar mejor las funciones de seguridad del sistema operativo subyacente.
- Un agente de usuario integrado tiene potencialmente acceso a todas las credenciales de seguridad que introduce el usuario.
- No todas las plataformas admiten el manejo de redireccionamientos de URL con el esquema «
https» o con esquemas URI personalizados (véase QOAuthUriSchemeReplyHandler). En estas plataformas, se puede utilizar un agente de usuario integrado para sortear esta limitación. - Incluir un agente de usuario integrado como parte de la aplicación suele suponer un componente de gran tamaño, lo que aumenta el espacio de almacenamiento que ocupa la aplicación. Por otro lado, es posible que no en todos los casos de uso se disponga de un navegador del sistema, o que la aplicación ya utilice un agente de usuario integrado para otros fines.
Teniendo en cuenta estas consideraciones, se recomienda utilizar el navegador del sistema para las aplicaciones nativas. Sin embargo, tal y como sugieren algunos de los puntos anteriores, puede que sigan existiendo casos de uso válidos para el uso de un agente de usuario integrado.
Uso del navegador del sistema
Para utilizar el navegador del sistema, es necesario abrirlo y navegar hasta la URL de autorización configurada por la aplicación. El uso típico es el siguiente:
connect(&m_oauth, &QAbstractOAuth::authorizeWithBrowser, this, &QDesktopServices::openUrl);El código conecta la señal « QAbstractOAuth::authorizeWithBrowser » con la ranura « QDesktopServices::openUrl ». Esto abre el navegador del sistema, donde el usuario realiza la autenticación y autorización necesarias. La aplicación o las bibliotecas Qt no tienen control directo sobre el navegador del sistema, y este suele permanecer abierto una vez concluida la autorización.
Para obtener más detalles y conocer los esquemas de URL de redirección compatibles con el navegador del sistema, consulta la Descripción general de OAuth 2.0, QOAuthHttpServerReplyHandler y QOAuthUriSchemeReplyHandler.
El uso de Qt WebEngine
Qt WebEngine proporciona un motor de navegador web para integrar contenido web directamente en la aplicación Qt.
Además de las funciones de control básicas, incluye vistas fáciles de usar tanto para aplicaciones QtWidgets como QtQuick. Estas vistas pueden utilizarse como agente de usuario en una autorización OAuth 2.0. Qt WebEngine es un módulo amplio y versátil, y esta documentación se centra en su uso con la autorización OAuth2.
Existen muchas formas de integrar el « Qt WebEngine » como parte de la aplicación. Desde un punto de vista práctico, las principales consideraciones son:
- Aplicaciones QtQuick frente a QtWidgets. Esto influye en cómo configurar la integración necesaria con las clases de QtNetworkAuth.
- Esquema de URI de redirección. Esto influye en qué clases de controladores de respuesta de QtNetworkAuth se deben utilizar y cómo (véase Descripción general de OAuth 2.0).
Las aplicaciones QtQuick y QtWidgets
Qt WebEngine pueden utilizarse tanto con aplicaciones QtQuick como con aplicaciones QtWidgets para la autorización OAuth 2.0. La principal diferencia radica en cómo configurar los pocos elementos habilitadores necesarios.
A continuación se ilustra una configuración simplificada de QWebEngineView (QtWidget). Se omiten, por brevedad, el manejo de errores y cualquier posible Qt WebEngine se omiten por brevedad.
Supongamos los siguientes widgets:
QWebEngineView *webView = nullptr;
QMainWindow mainWindow;En lugar de abrir el navegador del sistema, utilizamos el QWebEngineView para realizar la autorización:
connect(&m_oauth, &QAbstractOAuth::authorizeWithBrowser, this, [this](const QUrl &url) {
mainWindow.show();
webView->load(url);
webView->show();
});Una vez finalizada la autorización, cerramos la vista:
connect(&m_oauth, &QAbstractOAuth::granted, this, [this]() {
// Here we use QNetworkRequestFactory to store the access token
m_api.setBearerToken(m_oauth.token().toLatin1());
m_handler->close();
webView->close();
});Para las aplicaciones QtQuick, el flujo es, en principio, el mismo, pero en lugar del widget « QWebEngineView » utilizamos el elemento QML « WebEngineView »:
WebEngineView {
id: authorizationWebView
anchors.fill: parent
visible: false
}Este ejemplo simplificado expone las API necesarias desde la clase C++
class HttpExample : public QObject
{
Q_OBJECT
#ifdef QT_QML_LIB
QML_NAMED_ELEMENT(OAuth2)
#endif
public:
Q_INVOKABLE void authorize();
signals:
void authorizationCompleted(bool success);
void authorizeWithBrowser(const QUrl &url);que luego se utilizan en el lado QML para invocar ` WebEngineView ` y gestionar la autorización:
onAuthorizeWithBrowser:
(url) => {
console.log("Starting authorization with WebView")
authorizationWebView.url = url
authorizationWebView.visible = true
}
onAuthorizationCompleted:
(success) => {
console.log("Authorized: " + success);
authorizationWebView.visible = false
}Esquemas de URI de redireccionamiento
La elección del esquema de URI de redirección (http, https o custom-uri ) influye en cómo se utiliza Qt WebEngine.
URI de bucle cerrado de http
Con los URI de redirección de bucle cerrado http y QOAuthHttpServerReplyHandler, el funcionamiento es similar al del navegador del sistema. Qt WebEngine redirige la autorización al servidor localhost del gestor de respuestas, de forma similar al navegador del sistema.
URI con esquema personalizado
Con las URI de esquema personalizado (como com.example.myqtapp:/redirect) y QOAuthUriSchemeReplyHandler, el flujo también funciona de manera similar a como lo hace con el navegador del sistema.
La principal diferencia es que no es necesario configurar la aplicación de la misma forma que los «Universal Links» en iOS/macOS o los «App Links» en Android, tal y como se describe en la documentación de QOAuthUriSchemeReplyHandler.
m_handler.setRedirectUrl(QUrl{"com.example.myqtapp://oauth2redirect"_L1});
m_oauth.setReplyHandler(&m_handler);
connect(&m_oauth, &QAbstractOAuth::authorizeWithBrowser, this, [this](const QUrl &url) {
mainWindow.show();
webView->load(url);
webView->show();
});
connect(&m_oauth, &QAbstractOAuth::granted, this, [this]() {
// Here we use QNetworkRequestFactory to store the access token
m_api.setBearerToken(m_oauth.token().toLatin1());
m_handler.close();
webView->close();
});Técnicamente, esto funciona de tal manera que Qt WebEngine se invoca la función QDesktopServices::openUrl() para los esquemas URI no gestionados, a los que responde la función QOAuthUriSchemeReplyHandler.
URI https
Con los URI de https y QOAuthUriSchemeReplyHandler, la lógica cambia ligeramente. Al igual que con los URI de esquemas personalizados, no es necesario configurar la aplicación, pero debemos proporcionar la redirección al final de la fase de autorización al motor web.
connect(webView, &QWebEngineView::urlChanged, this, [this](const QUrl &url){
m_handler.handleAuthorizationRedirect(url);
});Esto es necesario porque, desde Qt WebEngine punto de vista, la URL de redirección es una URL válida de https y, por defecto, se intentará navegar a ella.
Para evitar dichos intentos de navegación y la exposición accidental del código de autorización (piensa en el caso de que el dominio de la URL de redirección no esté bajo tu control), se debe utilizar un filtrado más exhaustivo. Asimismo, se recomienda encarecidamente el uso de QOAuth2AuthorizationCodeFlow::PkceMethod, ya que mitiga el impacto del secuestro del código de autorización.
Por ejemplo:
connect(webView->page(), &QWebEnginePage::navigationRequested,
this, [this](QWebEngineNavigationRequest &request) {
if (request.navigationType() == QWebEngineNavigationRequest::RedirectNavigation
&& m_handler.handleAuthorizationRedirect(request.url())) {
request.reject();
webView->close();
} else {
request.accept();
}
});© 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.