Prise en charge de Qt OAuth2 par les navigateurs

Agents utilisateur OAuth2

La phase d’autorisation OAuth2 repose sur un agent utilisateur, qui est généralement soit le navigateur du système, soit un agent utilisateur intégré tel que Qt WebEngine.

Le choix entre le navigateur du système et un agent utilisateur intégré dépend de plusieurs facteurs. Voici quelques-unes des principales considérations :

• Le navigateur système peut déjà disposer de sessions de connexion actives pour l'utilisateur. L’authentification de l’utilisateur lors de la phase d’autorisation peut donc s’avérer plus simple, car la session existante peut être réutilisée. À l’inverse, avec un agent utilisateur intégré, l’utilisateur doit généralement s’identifier à nouveau. D’un autre côté, il n’est pas toujours souhaitable de laisser une session ouverte dans le navigateur système. Les navigateurs système peuvent également partager des données d’utilisation des applications avec des tiers.
• Le navigateur système est généralement familier à l’utilisateur et offre une expérience d’utilisation familière pour la connexion. En revanche, bien qu’un agent utilisateur intégré puisse offrir une interface moins familière, le développeur d’application est en mesure d’intégrer l’interaction de connexion au sein de la fenêtre de l’application, plutôt que de la faire s’afficher dans une fenêtre de navigateur distincte. De plus, le développeur d’application peut automatiser la fermeture de l’agent utilisateur intégré lorsqu’il n’est plus nécessaire.
• Les navigateurs système offrent à l’utilisateur des éléments visuels de sécurité familiers, tels que la barre d’adresse et la validation des certificats. Ceux-ci peuvent ne pas être visibles sur un agent utilisateur intégré. De plus, les navigateurs système peuvent mieux exploiter les fonctionnalités de sécurité du système d’exploitation sous-jacent.
• Un agent utilisateur intégré peut potentiellement avoir accès à toutes les informations d'identification de sécurité saisies par l'utilisateur.
• Toutes les plateformes ne prennent pas en charge la gestion des URL de redirection de type « https » ou utilisant des schémas URI personnalisés (voir QOAuthUriSchemeReplyHandler). Sur ces plateformes, un agent utilisateur intégré peut être utilisé pour contourner cette limitation.
• L’intégration d’un agent utilisateur intégré à l’application constitue généralement un composant volumineux, ce qui augmente l’empreinte mémoire de l’application. D’un autre côté, un navigateur système n’est pas forcément disponible dans tous les cas d’utilisation, ou l’application peut déjà utiliser un agent utilisateur intégré à d’autres fins.

Compte tenu de ces considérations, il est recommandé d’utiliser le navigateur système pour les applications natives. Cependant, comme le suggèrent certains des points ci-dessus, il peut tout de même exister des cas d’utilisation valables justifiant le recours à un agent utilisateur intégré.

Utilisation du navigateur système

Pour utiliser le navigateur système, il faut l’ouvrir et accéder à l’URL d’autorisation configurée par l’application. Une utilisation typique se présente comme suit :

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

Le code relie le signal ` QAbstractOAuth::authorizeWithBrowser ` au slot ` QDesktopServices::openUrl `. Cela ouvre le navigateur système, dans lequel l’utilisateur effectue l’authentification et l’autorisation nécessaires. L’application ou les bibliothèques Qt XML n’ont aucun contrôle direct sur le navigateur système, et celui-ci reste généralement ouvert une fois l’autorisation terminée.

Pour plus de détails et pour connaître les schémas d’URL de redirection pris en charge par le navigateur système, veuillez consulter la présentation d’OAuth 2.0, QOAuthHttpServerReplyHandler et QOAuthUriSchemeReplyHandler.

L'utilisation de Qt WebEngine

Qt WebEngine fournit un moteur de navigateur Web permettant d’intégrer directement du contenu Web dans l’application Qt.

Outre les fonctionnalités de contrôle de base, il propose des vues faciles à utiliser pour les applications QtWidgets et QtQuick. Ces vues peuvent servir d’agent utilisateur dans le cadre d’une autorisation OAuth 2. Qt WebEngine Il s’agit d’un module complet et polyvalent ; la présente documentation se concentre sur son utilisation avec l’autorisation OAuth2.

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

• Applications QtQuick ou QtWidgets. Cela influe sur la manière de mettre en place l’intégration nécessaire avec les classes d’ QtNetworkAuth.
• Le schéma d’URI de redirection. Cela détermine quelles classes de gestionnaires de réponse d’ QtNetworkAuth utiliser, et comment (voir Présentation d’OAuth 2.0).

Les applications QtQuick et QtWidgets

Qt WebEngine peuvent être utilisées avec les applications QtQuick et QtWidgets pour l’autorisation OAuth 2.0. La principale différence réside dans la manière de configurer les quelques éléments nécessaires.

L’exemple suivant illustre une configuration simplifiée d’ QWebEngineView (QtWidget). La gestion des erreurs et toute configuration potentielle Qt WebEngine configuration éventuelle sont omis par souci de concision.

En supposant les widgets suivants :

QWebEngineView *webView = nullptr;
QMainWindow mainWindow;

Au lieu d'ouvrir le navigateur système, nous utilisons l'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 déroulement 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 à partir d’une 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);

Celles-ci sont ensuite utilisées côté QML pour appeler 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 du schéma d’URI de redirection (http, https ou custom-uri ) a une incidence sur la manière d’utiliser Qt WebEngine.

URI de redirection en boucle http

Avec les URI de redirection en boucle http et QOAuthHttpServerReplyHandler, le traitement fonctionne de manière similaire à celui du navigateur système. Qt WebEngine redirige l'autorisation vers le serveur localhost du gestionnaire de réponse, de la même manière que le navigateur système.

URI à schéma personnalisé

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 réside dans le fait que l’application n’a pas besoin d’être configurée de la même manière que pour les Universal Links sur iOS/macOS ou les App Links sur Android, comme décrit dans la documentation 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 telle sorte que Qt WebEngine appelle la méthode QDesktopServices::openUrl() pour les schémas d’URI non gérés, que la méthode correspondante QOAuthUriSchemeReplyHandler surveille.

URI https

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

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

Cette opération est nécessaire car, du Qt WebEngine du point de vue du navigateur, l’URL de redirection est une URL https valide, et par défaut, celui-ci tentera d’y accéder.

Pour empêcher ces tentatives d’accès et toute exposition accidentelle du code d’autorisation (imaginez que le domaine de l’URL de redirection ne soit 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 de 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();
    }
});