Support du navigateur Qt OAuth2

User-Agents OAuth2

L 'étape d'autorisation d' OAuth2 repose sur un user-agent, qui est typiquement soit le navigateur du système, soit un user-agent intégré tel que Qt WebEngine.

Le choix entre le navigateur système et un user-agent intégré dépend de plusieurs facteurs. Les points suivants décrivent les principales considérations :

• Le navigateur du système peut déjà avoir des connexions actives de la part de l'utilisateur. Par conséquent, l'authentification de l'utilisateur au cours de la phase d'autorisation peut être plus simple car le login existant peut être utilisé. En revanche, dans le cas d'un agent utilisateur intégré, l'utilisateur doit généralement procéder à une nouvelle connexion. D'un autre côté, il n'est pas toujours souhaitable de laisser une session de connexion dans le navigateur du système. Les navigateurs système peuvent également partager les données d'utilisation des applications avec d'autres parties.
• Le navigateur système est généralement familier à l'utilisateur et lui offre une expérience familière de connexion. D'autre part, bien qu'un user-agent intégré puisse offrir un aspect et une sensation moins familiers, le développeur de l'application est en mesure d'intégrer l'interaction de connexion dans la fenêtre de l'application, plutôt que dans une fenêtre de navigateur séparée. En outre, le développeur d'applications peut automatiser la fermeture de l'agent utilisateur intégré lorsqu'il n'est plus nécessaire.
• Les navigateurs système fournissent à l'utilisateur des éléments visuels de sécurité familiers, tels que la barre d'adresse et la validation du certificat. Ces éléments peuvent ne pas être visibles sur un user-agent intégré. En outre, les navigateurs système peuvent mieux exploiter les fonctions de sécurité du système d'exploitation sous-jacent.
• Un user-agent intégré a potentiellement accès à toutes les données d'identification de sécurité saisies par l'utilisateur.
• Toutes les plateformes ne prennent pas en charge la gestion de https ou des URL de redirection des uri-schemes personnalisés (voir QOAuthUriSchemeReplyHandler). Avec ces plateformes, un user-agent intégré peut être utilisé pour contourner cette limitation.
• L'intégration d'un user-agent dans l'application est généralement un composant volumineux, qui augmente l'empreinte de stockage de l'application. D'autre part, il se peut que le navigateur système ne soit pas disponible dans tous les cas d'utilisation, ou que l'application utilise déjà un user-agent intégré à d'autres fins.

Compte tenu de ces considérations, l'utilisation du navigateur système est recommandée pour les applications natives. Mais comme le suggèrent certains des points ci-dessus, il peut toujours y avoir des cas d'utilisation valables pour l'utilisation d'un user-agent intégré.

Utilisation du navigateur système

Pour utiliser le navigateur système, il faut l'ouvrir et naviguer jusqu'à l'URL d'autorisation configurée par l'application. L'utilisation typique se présente comme suit :

connect(&m_oauth, &QAbstractOAuth::authorizeWithBrowser, this, &QDesktopServices::openUrl);

Le code connecte le signal QAbstractOAuth::authorizeWithBrowser et l'emplacement QDesktopServices::openUrl. Cela ouvre le navigateur du système, où l'utilisateur effectue les opérations d'authentification et d'autorisation nécessaires. L'application ou les bibliothèques Qt n'ont pas de contrôle direct sur le navigateur du système, et celui-ci reste généralement ouvert une fois l'autorisation terminée.

Pour plus de détails et les schémas d'URL de redirection pris en charge avec le navigateur système, veuillez consulter OAuth 2.0 Overview, QOAuthHttpServerReplyHandler, et QOAuthUriSchemeReplyHandler.

L'utilisation de Qt WebEngine

Qt WebEngine fournit un moteur de navigateur web pour intégrer du contenu web directement dans l'application Qt.

Outre les fonctions de contrôle de base, il est livré avec des vues faciles à utiliser pour les applications QtWidgets et QtQuick. Ces vues peuvent être utilisées comme user-agent dans une autorisation OAuth2. Qt WebEngine QtQuick est un module vaste et polyvalent, et cette documentation se concentre sur son utilisation avec l'autorisation OAuth2.

Il existe de nombreuses façons d'intégrer Qt WebEngine dans l'application. D'un point de vue pratique, les principales considérations sont les suivantes :

• Applications QtQuick ou QtWidgets. Cela a une incidence sur la manière de mettre en place l'intégration nécessaire avec les classes QtNetworkAuth.
• Schéma d'URI de redirection. Cela a un impact sur les classes de gestionnaire de réponse QtNetworkAuth à utiliser, et comment (voir OAuth 2.0 Overview).

Applications QtQuick et QtWidgets

Qt WebEngine peut être utilisé avec les applications QtQuick et QtWidgets pour l'autorisation OAuth2. La principale différence réside dans la manière de mettre en place les quelques facilitateurs nécessaires.

Ce qui suit illustre une configuration simplifiée de QWebEngineView (QtWidget). La gestion des erreurs et toute configuration potentielle est omise par souci de concision. Qt WebEngine est omise par souci de concision.

En supposant que les widgets suivants soient utilisés :

QWebEngineView *webView = nullptr;
QMainWindow mainWindow;

Au lieu d'ouvrir le navigateur du système, nous utilisons le site QWebEngineView pour effectuer l'autorisation :

connect(&m_oauth, &QAbstractOAuth::authorizeWithBrowser, this, [this](const QUrl &url) {
    mainWindow.show();
    webView->load(url);
    webView->show();
});

Une fois l'autorisation terminée, nous fermons la vue :

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();
});

Pour les applications QtQuick, le flux est en principe le même, mais au lieu du widget QWebEngineView, nous utilisons l'élément QML WebEngineView:

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

Cet exemple simplifié expose les API nécessaires de la classe 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);

qui sont ensuite utilisées côté QML pour invoquer WebEngineView afin de gérer l'autorisation :

onAuthorizeWithBrowser:
    (url) => {
        console.log("Starting authorization with WebView")
        authorizationWebView.url = url
        authorizationWebView.visible = true
    }
onAuthorizationCompleted:
    (success) => {
        console.log("Authorized: " + success);
        authorizationWebView.visible = false
    }

Schémas d'URI de redirection

Le choix de l'URI de redirection (http, https, ou custom-uri ) a un impact sur l'utilisation de l'URI de redirection. Qt WebEngine.

http Loopback URIs

Avec les URI de redirection de bouclage http et QOAuthHttpServerReplyHandler, la manipulation fonctionne de la même manière qu'avec le navigateur système. Qt WebEngine redirige l'autorisation vers le serveur local du gestionnaire de réponse de la même manière qu'avec le navigateur système.

URI personnalisés

Avec les URI à schéma personnalisé (tels que com.example.myqtapp:/redirect) et QOAuthUriSchemeReplyHandler, le flux fonctionne également de la même manière qu'avec le navigateur système.

La principale différence est que l'application n'a pas besoin d'être configurée de la même manière que les liens universels sur iOS/macOS ou les liens applicatifs sur Android, comme décrit dans la documentation 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();
});

Techniquement, cela fonctionne de la manière suivante Qt WebEngine appelle QDesktopServices::openUrl() pour les URI-schemes non gérés, dont l'homologue QOAuthUriSchemeReplyHandler écoute les URI.

URIs https

Avec les URI https et QOAuthUriSchemeReplyHandler, la logique change légèrement. Comme pour les URI personnalisés, l'application n'a pas besoin d'être configurée, mais nous devons fournir la redirection au moteur web à la fin de l'étape d'autorisation.

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

Ceci doit être fait parce que du point de vue de Qt WebEngine l'URL de redirection est une URL https valide et, par défaut, il tentera de naviguer vers elle.

Pour éviter de telles tentatives de navigation et l'exposition accidentelle du code d'autorisation (dans le cas où le domaine de l'URL de redirection n'est pas sous votre contrôle), il convient d'utiliser un filtrage plus poussé. L'utilisation de QOAuth2AuthorizationCodeFlow::PkceMethod est également fortement recommandée car elle atténue l'impact du détournement du code d'autorisation.

Par exemple :

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();
    }
});