Qt OAuth2 Überblick

OAuth2

RFC 6749 OAuth 2.0 definiert ein Autorisierungs-Framework, das die Autorisierung von Ressourcen ermöglicht, ohne sensible Benutzerdaten wie Passwörter preiszugeben.

Das OAuth2-Framework definiert verschiedene Client-Typen (öffentlich und vertraulich) sowie Abläufe (implizit, Autorisierungscode und verschiedene andere). Für typische Qt-Anwendungen sollte der Client-Typ als öffentliche native Anwendung betrachtet werden. Öffentlich bedeutet, dass der Anwendung nicht zugetraut wird, dass sie Geheimnisse, wie z. B. Passwörter, in der ausgelieferten Binärdatei enthält.

RFC 8252 OAuth 2.0 for Native Apps definiert die Best Practices für solche Anwendungen weiter. Unter anderem wird der Authorization Code Flow als empfohlener Fluss definiert. QtNetworkAuth bietet eine konkrete Implementierung für diesen Fluss, die auch im Mittelpunkt dieser Dokumentation steht.

Qt OAuth2-Klassen

QtNetworkAuth bietet sowohl konkrete als auch abstrakte OAuth2-Klassen. Die abstrakten Klassen sind für die Implementierung benutzerdefinierter Abläufe gedacht, während die konkreten Klassen eine konkrete Implementierung bieten.

Um einen OAuth2-Flow mit QtNetworkAuth zu implementieren, werden zwei Klassen benötigt:

• Eine OAuth2-Flow-Implementierungsklasse stellt die Haupt-API bereit und ist der Orchestrator des Flows. Sie besitzt normalerweise einen Antwort-Handler. Die abstrakte Klasse ist QAbstractOAuth2, und die konkrete Implementierung ist QOAuth2AuthorizationCodeFlow.
• Eine Reply-Handler-Klasse, die Antworten von einem Autorisierungsserver verarbeitet. Beim Autorisierungscodefluss sind dies die Autorisierung, die Anforderung des Zugriffstokens und die Aktualisierung des Zugriffstokens. Die Ergebnisse der Verarbeitung einer Antwort werden von der Flow-Klasse weiterverarbeitet. Die abstrakte Klasse des Reply-Handlers ist QAbstractOAuthReplyHandler, und die konkreten Klassen sind QOAuthHttpServerReplyHandler und QOAuthUriSchemeReplyHandler.

Autorisierungscodefluss

Der Autorisierungscodefluss ist der empfohlene OAuth2-Fluss für native Anwendungen wie Qt-Anwendungen.

Der folgende Codeschnipsel zeigt ein Beispiel für die Einrichtung:

QOAuth2AuthorizationCodeFlow m_oauth;
QOAuthUriSchemeReplyHandler m_handler;
m_oauth.setAuthorizationUrl(QUrl("https://some.authorization.service/v3/authorize"_L1));
m_oauth.setAccessTokenUrl(QUrl("https://some.authorization.service/v3/access_token"_L1));
m_oauth.setClientIdentifier("a_client_id"_L1);
m_oauth.setScope("read"_L1);

connect(&m_oauth, &QAbstractOAuth::authorizeWithBrowser, this, &QDesktopServices::openUrl);
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();
});
m_handler.setRedirectUrl(QUrl{"com.my.app:/oauth2redirect"_L1});
m_oauth.setReplyHandler(&m_handler);

// Initiate the authorization
if (m_handler.listen()) {
    m_oauth.grant();
}

Stages

Der Authorization Code Flow besteht aus zwei Hauptphasen: Ressourcenautorisierung (einschließlich der erforderlichen Benutzerauthentifizierung), gefolgt von einer Access-Token-Anforderung. Darauf folgen optional die Verwendung des Zugangstokens und die Aktualisierung des Zugangstokens. Die folgende Abbildung veranschaulicht diese Phasen:

• In der Autorisierungsphase wird der Benutzer authentifiziert, und der Benutzer autorisiert den Zugriff auf die Ressourcen. Dies erfordert eine Browser-Interaktion des Benutzers.
• Nach der Autorisierung wird der erhaltene Autorisierungscode verwendet, um ein Zugriffstoken und optional ein Refresh-Token anzufordern.
• Sobald das Zugriffstoken erworben wurde, verwendet die Anwendung es für den Zugriff auf die gewünschten Ressourcen. Das Zugriffstoken ist in den Ressourcenanforderungen enthalten, und es obliegt dem Ressourcenserver, die Gültigkeit des Tokens zu überprüfen. Es gibt mehrere Möglichkeiten, das Token als Teil der Anfragen einzubinden, aber die Aufnahme in den HTTP Authorization Header ist wohl die gebräuchlichste.
• Auffrischung des Tokens. Zugriffstoken laufen in der Regel relativ schnell ab, z. B. in einer Stunde. Wenn die Anwendung zusätzlich zum Zugriffstoken ein Refresh-Token erhalten hat, kann das Refresh-Token zur Anforderung eines neuen Zugriffstokens verwendet werden. Refresh-Tokens sind langlebig und Anwendungen können sie aufbewahren, um eine neue Autorisierungsphase (und damit eine weitere Browserinteraktion) zu vermeiden.

Details und Anpassungen

OAuth2-Abläufe sind dynamisch, und die Verfolgung der Details kann anfangs schwierig sein. Die nachstehende Abbildung veranschaulicht die wichtigsten Details eines erfolgreichen Autorisierungscodeflusses.

Aus Gründen der Übersichtlichkeit lässt die Abbildung einige weniger genutzte Signale weg, zeigt aber insgesamt die Details und die wichtigsten Anpassungspunkte. Bei den Anpassungspunkten handelt es sich um die verschiedenen Signale/Slots, die die Anwendung abfangen (und aufrufen) kann, sowie um den Callback, der mit QAbstractOAuth::setModifyParametersFunction() einstellbar ist.

Auswahl eines Reply Handlers

Die Entscheidung, welcher Reply Handler verwendet bzw. implementiert werden soll, hängt von der verwendeten redirect_uri ab. Die redirect_uri ist die Adresse, an die der Browser nach Abschluss der Autorisierungsphase weitergeleitet wird.

Im Zusammenhang mit nativen Anwendungen werden in RFC 8252 drei Haupttypen von URI-Schemata beschrieben: loopback, https, und private Nutzung.

• URIs zur privaten Nutzung: Können verwendet werden, wenn das Betriebssystem einer Anwendung erlaubt, ein benutzerdefiniertes URI-Schema zu registrieren. Beim Versuch, eine URL mit einem solchen benutzerdefinierten Schema zu öffnen, wird die entsprechende native Anwendung geöffnet. Siehe QOAuthUriSchemeReplyHandler.
• HTTPS-URIs: Kann verwendet werden, wenn das Betriebssystem der Anwendung erlaubt, eine benutzerdefinierte HTTPS-URL zu registrieren. Beim Versuch, diese URL zu öffnen, wird die zugehörige native Anwendung geöffnet. Dieses Schema wird empfohlen, wenn das Betriebssystem es unterstützt. Siehe QOAuthUriSchemeReplyHandler.
• Loopback-Schnittstellen: Diese werden üblicherweise für Desktop-Anwendungen und Anwendungen während der Entwicklung verwendet. QOAuthHttpServerReplyHandler ist darauf ausgelegt, diese URIs zu handhaben, indem ein lokaler Server eingerichtet wird, der die Umleitung vornimmt.

Die Wahl hängt von mehreren Faktoren ab, wie z.B.:

• Vom Anbieter des Autorisierungsservers unterstützte Umleitungs-URIs. Die Unterstützung variiert von Anbieter zu Anbieter und ist oft spezifisch für einen bestimmten Client-Typ und ein bestimmtes Betriebssystem. Außerdem kann die Unterstützung davon abhängen, ob die Anwendung veröffentlicht ist oder nicht.
• URI-Umleitungsschemata, die von der/den Zielplattform(en) unterstützt werden.
• Anwendungsspezifische Benutzerfreundlichkeit, Sicherheit und andere Anforderungen.

RFC 8252 empfiehlt die Verwendung des https Schemas aufgrund von Sicherheits- und Benutzerfreundlichkeitsvorteilen gegenüber den anderen Methoden.