Soporte del navegador Qt OAuth2

Agentes de usuario de OAuth2

La fase de autorización de OAuth2 se basa en un agente de usuario, que normalmente es el navegador del sistema o un agente de usuario incrustado como por ejemplo 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 consideraciones principales:

• El navegador del sistema puede tener ya inicios de sesión activos por parte del usuario. Por lo tanto, la autenticación del usuario durante la fase de autorización puede ser más sencilla, ya que se puede utilizar el inicio de sesión existente. En cambio, con un agente de usuario incrustado, el usuario suele tener que realizar un nuevo inicio de sesión. Por otro lado, no siempre es deseable dejar una sesión de inicio de sesión en el navegador del sistema. Los navegadores del sistema también pueden compartir datos de uso de la aplicación con otras partes.
• El navegador del sistema es normalmente familiar para el usuario, y proporciona una experiencia de usuario familiar para el inicio de sesión. Por otro lado, mientras que un agente de usuario integrado puede proporcionar un aspecto menos familiar, 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 ocurra en una ventana separada del navegador. Además, el desarrollador de la aplicación puede automatizar el cierre del agente de usuario integrado cuando ya no sea necesario.
• Los navegadores de sistema ofrecen al usuario elementos visuales de seguridad familiares, como la barra de direcciones y la validación de certificados. Estos elementos pueden no ser visibles en un agente de usuario integrado. Además, los navegadores de sistema pueden aprovechar mejor las características de seguridad del sistema operativo subyacente.
• Un agente de usuario integrado puede tener acceso a todas las credenciales de seguridad que introduzca el usuario.
• No todas las plataformas ofrecen soporte para el manejo de https o URL de redirección de esquema uri personalizado (véase QOAuthUriSchemeReplyHandler). Con estas plataformas se puede utilizar un agente de usuario integrado para evitar esta limitación.
• Incluir un agente de usuario incrustado como parte de la aplicación suele ser un componente de gran tamaño, lo que aumenta la huella de almacenamiento de la aplicación. Por otro lado, es posible que no todos los casos de uso dispongan de un navegador del sistema, o que la aplicación ya utilice un agente de usuario integrado para otros fines.

Dadas estas consideraciones, se recomienda utilizar el navegador del sistema para las aplicaciones nativas. Sin embargo, como se indica en algunos de los puntos anteriores, todavía puede haber casos de uso válidos para el uso de un agente de usuario incrustado.

Uso del navegador del sistema

Usar el navegador del sistema requiere abrirlo y navegar a 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 y 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 librerías Qt no tienen control directo sobre el navegador del sistema, y normalmente permanece abierto una vez concluida la autorización.

Para más detalles y esquemas de URL de redirección soportados con el navegador del sistema, por favor consulta OAuth 2.0 Overview, QOAuthHttpServerReplyHandler, y QOAuthUriSchemeReplyHandler.

El uso de Qt WebEngine

Qt WebEngine proporciona un motor de navegador web para incrustar contenido web directamente en la aplicación Qt.

Junto con las características principales de control, viene con vistas fáciles de usar tanto para aplicaciones QtWidgets como QtQuick. Estas vistas pueden utilizarse como user-agent en una autorización OAuth2. Qt WebEngine es un módulo grande y versátil, y el foco de esta documentación está en usarlo con la autorización OAuth2.

Hay muchas maneras de incrustar el Qt WebEngine como parte de la aplicación. Desde un punto de vista práctico las principales consideraciones son:

• Aplicaciones QtQuick vs QtWidgets. Esto impacta en cómo configurar la integración necesaria con las clases de QtNetworkAuth.
• Esquema URI de redirección. Esto afecta a qué clases de respuesta QtNetworkAuth utilizar, y cómo (ver OAuth 2.0 Overview).

Aplicaciones QtQuick y QtWidgets

Qt WebEngine puede utilizarse con aplicaciones QtQuick y QtWidgets para la autorización OAuth2. La principal diferencia está en cómo configurar los pocos habilitadores necesarios.

A continuación se ilustra una configuración simplificada de QWebEngineView (QtWidget). El manejo de errores y cualquier configuración Qt WebEngine configuración se omite por brevedad.

Asumiendo los siguientes widgets:

QWebEngineView *webView = nullptr;
QMainWindow mainWindow;

En lugar de abrir el navegador del sistema, utilizamos 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 aplicaciones QtQuick el flujo es en principio el mismo, pero en lugar del widget QWebEngineView usamos WebEngineView elemento QML:

WebEngineView {
    id: authorizationWebView
    anchors.fill: parent
    visible: false
}

Este ejemplo simplificado expone las APIs necesarias de 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 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 URI de redirección

La elección del esquema URI de redirección (esquemahttp, https, o custom-uri ) tiene un impacto en cómo utilizar Qt WebEngine.

URI de bucle de retorno http

Con http loopback redirect URI y QOAuthHttpServerReplyHandler el manejo funciona de forma similar al navegador del sistema. Qt WebEngine redirige la autorización al servidor localhost del gestor de respuestas de forma similar al navegador del sistema.

URI de esquema personalizado

Con URIs de esquema personalizado (como com.example.myqtapp:/redirect) y QOAuthUriSchemeReplyHandler el flujo funciona también de forma similar al navegador del sistema.

La principal diferencia es que la aplicación no necesita ser configurada de forma similar a los Universal Links en iOS/macOS o App Links en Android, 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 manera que Qt WebEngine llama a la QDesktopServices::openUrl() para URI-esquemas no manejados, cuya contraparte QOAuthUriSchemeReplyHandler escucha a.

https URIs

Con https URIs y QOAuthUriSchemeReplyHandler la lógica cambia ligeramente. Al igual que con los URIs de esquema personalizado, no es necesario configurar la aplicación, pero tenemos que proporcionar la redirección al final de la etapa de autorización al motor web.

connect(webView, &QWebEngineView::urlChanged, this, [this](const QUrl &url){
    m_handler.handleAuthorizationRedirect(url);
});

Esto debe hacerse porque desde el punto de vista Qt WebEngine la URL de redirección es una URL válida de https, y por defecto intentará navegar a ella.

Para evitar estos intentos de navegación y la exposición accidental del código de autorización (considere el caso de que el dominio de la URL de redirección no esté bajo su control), debería utilizarse un filtrado más complejo. También 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();
    }
});