Qt OAuth2-Browser-Unterstützung

OAuth2-User-Agents

Die OAuth2 -Autorisierungsphase stützt sich auf einen User-Agent, bei dem es sich typischerweise entweder um den Systembrowser oder um einen eingebetteten User-Agent wie Qt WebEngine.

Die Wahl zwischen dem Systembrowser und einem eingebetteten User-Agent hängt von mehreren Faktoren ab. Im Folgenden werden einige wichtige Überlegungen beschrieben:

• Im Systembrowser sind möglicherweise bereits aktive Anmeldungen des Benutzers vorhanden. Daher kann die Benutzerauthentifizierung während der Autorisierungsphase einfacher sein, da die bestehende Anmeldung genutzt werden kann. Im Gegensatz dazu muss sich der Benutzer bei einem eingebetteten User-Agent in der Regel neu anmelden. Andererseits ist es möglicherweise nicht immer wünschenswert, eine Anmeldesitzung im Systembrowser offen zu lassen. Systembrowser können zudem Daten zur Anwendungsnutzung an Dritte weitergeben.
• Der Systembrowser ist dem Nutzer in der Regel vertraut und bietet eine vertraute Benutzererfahrung bei der Anmeldung. Andererseits bietet ein eingebetteter User-Agent zwar möglicherweise ein weniger vertrautes Erscheinungsbild, doch kann der Anwendungsentwickler den Anmeldevorgang als Teil des Anwendungsfensters integrieren, anstatt ihn in einem separaten Browserfenster stattfinden zu lassen. Darüber hinaus kann der Anwendungsentwickler das Schließen des eingebetteten User-Agents automatisieren, wenn dieser nicht mehr benötigt wird.
• Systembrowser bieten dem Nutzer vertraute Sicherheitselemente wie die Adressleiste und die Zertifikatsüberprüfung. Diese sind bei einem eingebetteten User-Agent möglicherweise nicht sichtbar. Zudem können Systembrowser die Sicherheitsfunktionen des zugrunde liegenden Betriebssystems besser nutzen.
• Ein eingebetteter User-Agent hat potenziell Zugriff auf alle Sicherheitsdaten, die der Benutzer eingibt.
• Nicht alle Plattformen unterstützen die Verarbeitung von https oder benutzerdefinierten Umleitungs-URLs mit eigenen URI-Schemas (siehe QOAuthUriSchemeReplyHandler). Bei diesen Plattformen kann ein eingebetteter User-Agent genutzt werden, um diese Einschränkung zu umgehen.
• Die Einbindung eines eingebetteten User-Agents als Teil der Anwendung ist in der Regel eine umfangreiche Komponente, die den Speicherbedarf der Anwendung erhöht. Andererseits steht möglicherweise nicht in allen Anwendungsfällen ein Systembrowser zur Verfügung, oder die Anwendung nutzt einen eingebetteten User-Agent bereits für andere Zwecke.

Angesichts dieser Überlegungen wird für native Anwendungen die Verwendung des Systembrowsers empfohlen. Wie jedoch einige der oben genannten Punkte andeuten, kann es dennoch berechtigte Anwendungsfälle für die Verwendung eines eingebetteten User-Agents geben.

Verwendung des Systembrowsers

Um den Systembrowser zu nutzen, muss dieser geöffnet und die von der Anwendung konfigurierte Autorisierungs-URL aufgerufen werden. Eine typische Verwendung sieht wie folgt aus:

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

Der Code verbindet das Signal „ QAbstractOAuth::authorizeWithBrowser “ mit dem Slot „ QDesktopServices::openUrl “. Dadurch wird der Systembrowser geöffnet, in dem der Benutzer die erforderliche Authentifizierung und Autorisierung durchführt. Die Anwendung oder die Qt-Bibliotheken haben keine direkte Kontrolle über den Systembrowser, und dieser bleibt in der Regel geöffnet, sobald die Autorisierung abgeschlossen ist.

Weitere Details sowie die vom Systembrowser unterstützten URL-Schemas für Weiterleitungen finden Sie unter „OAuth 2.0 – Überblick“, QOAuthHttpServerReplyHandler und QOAuthUriSchemeReplyHandler.

Die Verwendung von Qt WebEngine

Qt WebEngine bietet eine Webbrowser-Engine, um Webinhalte direkt in die Qt-Anwendung einzubetten.

Neben zentralen Steuerungsfunktionen enthält es benutzerfreundliche Ansichten sowohl für QtWidgets- als auch für QtQuick-Anwendungen. Diese Ansichten können als User-Agent bei einer OAuth2-Autorisierung verwendet werden. Qt WebEngine ist ein umfangreiches und vielseitiges Modul, und der Schwerpunkt dieser Dokumentation liegt auf der Verwendung mit der OAuth2-Autorisierung.

Es gibt viele Möglichkeiten, den „ Qt WebEngine “ als Teil der Anwendung einzubetten. Aus praktischer Sicht sind folgende Punkte besonders zu beachten:

• QtQuick- vs. QtWidgets-Anwendungen. Dies beeinflusst, wie die erforderliche Integration mit den „ QtNetworkAuth “-Klassen eingerichtet wird.
• Redirect-URI-Schema. Dies beeinflusst, welche Antwort-Handler-Klassen von „ QtNetworkAuth “ verwendet werden sollen und wie (siehe „OAuth 2.0 – Überblick“).

QtQuick- und QtWidgets-Anwendungen

Qt WebEngine kann sowohl mit QtQuick- als auch mit QtWidgets-Anwendungen für die OAuth2-Autorisierung verwendet werden. Der Hauptunterschied liegt in der Einrichtung der wenigen erforderlichen Enabler.

Im Folgenden wird eine vereinfachte Konfiguration für „ QWebEngineView “ (QtWidget) veranschaulicht. Die Fehlerbehandlung sowie etwaige Qt WebEngine Konfigurationen wurden der Kürze halber weggelassen.

Angenommen, es gibt folgende Widgets:

QWebEngineView *webView = nullptr;
QMainWindow mainWindow;

Anstatt den Systembrowser zu öffnen, verwenden wir das „ QWebEngineView “, um die Autorisierung durchzuführen:

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

Sobald die Autorisierung abgeschlossen ist, schließen wir die Ansicht:

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

Bei QtQuick-Anwendungen ist der Ablauf im Prinzip derselbe, allerdings verwenden wir anstelle des Widgets „ QWebEngineView “ das QML-Element „ WebEngineView “:

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

Dieses vereinfachte Beispiel stellt die erforderlichen APIs aus einer C++-Klasse bereit

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

Diese werden dann auf der QML-Seite verwendet, um ` WebEngineView ` zum Abwickeln der Autorisierung aufzurufen:

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

Umleitungs-URI-Schemata

Die Wahl des Redirect-URI-Schemas (http, https oder custom-uri ) hat Auswirkungen darauf, wie Qt WebEngine.

http-Loopback-URIs

Bei den Loopback-Weiterleitungs-URIs http und QOAuthHttpServerReplyHandler funktioniert die Handhabung ähnlich wie beim Systembrowser. Qt WebEngine leitet die Autorisierung ähnlich wie der Systembrowser an den Localhost-Server des Antwort-Handlers weiter.

URIs mit benutzerdefiniertem Schema

Bei URIs mit benutzerdefiniertem Schema (wie z. B. com.example.myqtapp:/redirect) und QOAuthUriSchemeReplyHandler verläuft der Ablauf ebenfalls ähnlich wie beim Systembrowser.

Der Hauptunterschied besteht darin, dass die Anwendung nicht wie die Universal Links unter iOS/macOS oder die App Links unter Android konfiguriert werden muss, wie in der Dokumentation unter QOAuthUriSchemeReplyHandler beschrieben.

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

Technisch funktioniert dies so, dass Qt WebEngine die Funktion QDesktopServices::openUrl() für nicht behandelte URI-Schemas aufruft, auf die das Gegenstück QOAuthUriSchemeReplyHandler wartet.

https-URIs

Bei https -URIs und QOAuthUriSchemeReplyHandler ändert sich die Logik geringfügig. Ähnlich wie bei URIs mit benutzerdefinierten Schemata muss die Anwendung nicht konfiguriert werden, aber wir müssen die Weiterleitung am Ende der Autorisierungsphase an die Web-Engine übergeben.

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

Dies ist erforderlich, da aus Qt WebEngine die Weiterleitungs-URL aus Sicht der Web-Engine eine gültige „ https “-URL ist und standardmäßig versucht wird, dorthin zu navigieren.

Um solche Navigationsversuche und eine versehentliche Offenlegung des Autorisierungscodes zu verhindern (man denke an den Fall, dass die Domain der Weiterleitungs-URL nicht unter Ihrer Kontrolle steht), sollte eine umfassendere Filterung verwendet werden. Zudem wird die Verwendung von QOAuth2AuthorizationCodeFlow::PkceMethod dringend empfohlen, da dies die Auswirkungen eines Autorisierungscode-Hijackings mindert.

Beispiel:

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