Back to Qt.io
Contact Us Blog Download Qt

QOAuthHttpServerReplyHandler Class

Erledigt Loopback-Umleitungen, indem er einen lokalen HTTP-Server einrichtet. Mehr...

Kopfzeile: #include <QOAuthHttpServerReplyHandler>
CMake: find_package(Qt6 REQUIRED COMPONENTS NetworkAuth)
target_link_libraries(mytarget PRIVATE Qt6::NetworkAuth)
qmake: QT += networkauth
Erbt: QOAuthOobReplyHandler

Öffentliche Funktionen

QOAuthHttpServerReplyHandler(QObject *parent = nullptr)
QOAuthHttpServerReplyHandler(quint16 port, QObject *parent = nullptr)
QOAuthHttpServerReplyHandler(const QHostAddress &address, quint16 port, QObject *parent = nullptr)
virtual ~QOAuthHttpServerReplyHandler()
(since 6.9) QString callbackHost() const
QString callbackPath() const
QString callbackText() const
void close()
bool isListening() const
bool listen(const QHostAddress &address = QHostAddress::Any, quint16 port = 0)
bool listen(const QSslConfiguration &configuration, const QHostAddress &address = QHostAddress::Any, quint16 port = 0)
quint16 port() const
(since 6.9) void setCallbackHost(const QString &host)
void setCallbackPath(const QString &path)
void setCallbackText(const QString &text)

Detaillierte Beschreibung

Diese Klasse dient als Antwort-Handler für OAuth 2.0-Autorisierungsprozesse, die eine Loopback-Umleitung verwenden.

Der Redirect-URI ist der Ort, an den der Autorisierungsserver den User-Agent (typischerweise und vorzugsweise den Systembrowser) umleitet, sobald der Autorisierungsteil des Ablaufs abgeschlossen ist. Loopback-Redirect-URIs verwenden http als Schema und entweder localhost oder ein IP-Adressliteral als Host (siehe IPv4 and IPv6).

QOAuthHttpServerReplyHandler richtet einen localhost-Server ein. Sobald der Autorisierungsserver den Browser an diese localhost-Adresse umleitet, analysiert der Reply-Handler die Abfrageparameter des Umleitungs-URIs und signalisiert dann den Abschluss der Autorisierung mit a signal.

Für die Behandlung anderer Umleitungs-URI-Schemata siehe QOAuthUriSchemeReplyHandler.

Der folgende Code veranschaulicht die Verwendung. Zunächst die benötigten Variablen:

QOAuth2AuthorizationCodeFlow m_oauth;
QOAuthHttpServerReplyHandler *m_handler = nullptr;

Gefolgt von der OAuth-Einrichtung (Fehlerbehandlung der Kürze halber weggelassen):

m_oauth.setAuthorizationUrl(QUrl(authorizationUrl));
m_oauth.setTokenUrl(QUrl(accessTokenUrl));
m_oauth.setClientIdentifier(clientIdentifier);
m_oauth.setRequestedScopeTokens({scope});

m_handler = new QOAuthHttpServerReplyHandler(1234, this);

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

Schließlich richten wir den URI-Schema-Antwort-Handler ein:

m_oauth.setReplyHandler(m_handler);

// Initiate the authorization
if (m_handler->isListening()) {
    m_oauth.grant();
}

IPv4 und IPv6

Handelt es sich bei dem Handler um einen Handler für beliebige Adressen (AnyIPv4, AnyIPv6, or Any), so hat der verwendete Callback die Form http://localhost:{port}/{path}. Der Handler versucht zunächst, die IPv4-Loopback-Adresse abzuhören und dann die IPv6-Adresse. localhost wird verwendet, weil es sowohl auf IPv4- als auch auf IPv6-Schnittstellen korrekt aufgelöst wird.

Für Loopback-Adressen (LocalHost or LocalHostIPv6) werden die IP-Literale (127.0.0.1 und ::1) verwendet.

Für spezifische IP-Adressen wird das angegebene IP-Literal direkt verwendet, z. B.: http://192.168.0.123:{port}/{path} im Falle einer IPv4-Adresse.

Es ist auch möglich, den Host-Teil der Callback-URL manuell mit setCallbackHost() anzugeben. Sie können den Rückruf zum Beispiel als localhost.localnet angeben. Natürlich müssen Sie sicherstellen, dass diese Adresse bei der Umleitung erreichbar ist.

auto replyHandler = new QOAuthHttpServerReplyHandler(QHostAddress::LocalHost, 1337, this);
replyHandler->setCallbackHost("localhost.localnet"_L1);

HTTP- und HTTPS-Rückrufe

Seit Qt 6.9 ist es möglich, den Handler so zu konfigurieren, dass er das URI-Schema https anstelle von http verwendet. Dies geschieht durch die Angabe eines entsprechenden QSslConfiguration beim Aufruf von listen(). Intern verwendet der Handler dann QSslServer, und der Callback (Redirect URL) hat die Form https://{host}:{port}/{path}.

Das folgende Beispiel veranschaulicht dies:

// Lesen von Zertifikat und privatem Schlüsselauto certificates = QSslCertificate::fromPath(sslCertificateFile);QFile keyFile(sslPrivateKeyFile);if (!keyFile.open(QFile::ReadOnly)) {    qWarning("Cannot open key file");
   return; }QSslKey privateKey(&keyFile, QSsl::Rsa, QSsl::Pem);if (certificates.size() == 0 || privateKey.isNull()) {    qWarning("SSL certificate data invalid");
   return; }// SSL-Konfiguration erstellenQSslConfiguration configuration = QSslConfiguration::defaultConfiguration(); configuration.setLocalCertificate(certificates.at(0)); configuration.setPrivateKey(privateKey);// Handler mit der SSL-Konfiguration instanziierenm_handler = new QOAuthHttpServerReplyHandler(1234, this);  m_handler->listen(configuration);

Wenn möglich, wird empfohlen, andere Redirect-URI-Optionen zu verwenden, siehe Auswahl eines Reply-Handlers und Qt OAuth2 Browser Support.

Die primären Anwendungsfälle für einen localhost https Handler sollten auf die Entwicklungszeit oder streng kontrollierte und bereitgestellte Umgebungen beschränkt sein. Zum Beispiel erlauben einige Autorisierungsserver überhaupt keine einfachen http Redirect-URIs, in diesem Fall kann dies den Entwicklungskomfort erhöhen.

Aus der Sicherheitsperspektive verschlüsselt die Verwendung von SSL/TLS zwar den Localhost-Datenverkehr, aber OAuth2 verfügt auch über andere Sicherheitsmechanismen wie PKCE. Unter keinen Umständen sollten Sie private Zertifikatsschlüssel zusammen mit der Anwendung weitergeben.

Hinweis: Browser geben strenge Warnungen aus, wenn das Zertifikat nicht vertrauenswürdig ist. Dies ist typisch für selbstsignierte Zertifikate, deren Verwendung auf die Entwicklungszeit beschränkt werden sollte.

Dokumentation der Mitgliedsfunktionen

[explicit] QOAuthHttpServerReplyHandler::QOAuthHttpServerReplyHandler(QObject *parent = nullptr)

Konstruiert ein QOAuthHttpServerReplyHandler-Objekt mit parent als übergeordnetes Objekt. Ruft listen() mit Port 0 und Adresse LocalHost auf.

Siehe auch listen().

[explicit] QOAuthHttpServerReplyHandler::QOAuthHttpServerReplyHandler(quint16 port, QObject *parent = nullptr)

Konstruiert ein QOAuthHttpServerReplyHandler-Objekt mit parent als übergeordnetes Objekt. Ruft listen() mit port und der Adresse LocalHost auf.

Siehe auch listen().

[explicit] QOAuthHttpServerReplyHandler::QOAuthHttpServerReplyHandler(const QHostAddress &address, quint16 port, QObject *parent = nullptr)

Konstruiert ein QOAuthHttpServerReplyHandler-Objekt mit parent als übergeordnetes Objekt. Ruft listen() mit address und port auf.

Siehe auch listen().

[virtual noexcept] QOAuthHttpServerReplyHandler::~QOAuthHttpServerReplyHandler()

Zerstört das Objekt QOAuthHttpServerReplyHandler. Hört auf, auf Verbindungen / Umleitungen zu warten.

Siehe auch close().

[since 6.9] QString QOAuthHttpServerReplyHandler::callbackHost() const

Gibt den Namen zurück, der als Host-Komponente des callback() / OAuth2 redirect_uri Parameters verwendet wird.

Diese Funktion wurde in Qt 6.9 eingeführt.

Siehe auch setCallbackHost().

QString QOAuthHttpServerReplyHandler::callbackPath() const

Gibt den Pfad zurück, der als Pfadkomponente des callback() / OAuth2 redirect_uri Parameters verwendet wird.

Siehe auch setCallbackPath().

QString QOAuthHttpServerReplyHandler::callbackText() const

Gibt den Text zurück, der als Antwort auf die Umleitung am Ende der Autorisierungsphase verwendet wird.

Der Text ist in eine einfache HTML-Seite verpackt und wird dem Benutzer von dem Browser / User-Agent angezeigt, der die Umleitung vorgenommen hat.

Der Standardtext lautet

Callback received. Feel free to close this page.

Siehe auch setCallbackText().

void QOAuthHttpServerReplyHandler::close()

Sagt diesem Handler, dass er aufhören soll, auf Verbindungen/Umleitungen zu warten.

Siehe auch listen().

bool QOAuthHttpServerReplyHandler::isListening() const

Gibt true zurück, wenn dieser Handler gerade lauscht, und andernfalls false.

Siehe auch listen() und close().

bool QOAuthHttpServerReplyHandler::listen(const QHostAddress &address = QHostAddress::Any, quint16 port = 0)

Weist diesen Handler an, auf address und port auf eingehende Verbindungen / Weiterleitungen zu warten. Gibt true zurück, wenn das Abhören erfolgreich ist, und andernfalls false.

Aktives Abhören ist nur während der anfänglichen Autorisierungsphase erforderlich, die normalerweise durch einen QOAuth2AuthorizationCodeFlow::grant()-Aufruf eingeleitet wird.

Es wird empfohlen, den Listener nach erfolgreicher Autorisierung zu schließen. Das Abhören ist nicht erforderlich für requesting access tokens oder deren Auffrischung.

Wenn diese Funktion mit Null als address aufgerufen wird, versucht der Handler, LocalHost abzuhören, und wenn dies fehlschlägt, LocalHostIPv6.

Siehe auch IPv4 and IPv6.

Siehe auch close(), isListening(), und QTcpServer::listen().

bool QOAuthHttpServerReplyHandler::listen(const QSslConfiguration &configuration, const QHostAddress &address = QHostAddress::Any, quint16 port = 0)

Weist diesen Handler an, auf eingehende https Verbindungen / Weiterleitungen auf address und port zu lauschen. Gibt true zurück, wenn das Abhören erfolgreich war, und andernfalls false.

Siehe HTTP and HTTPS Callbacks für weitere Informationen.

Siehe auch listen(const QHostAddress &, quint16), close(), isListening(), QSslServer, und QTcpServer::listen().

quint16 QOAuthHttpServerReplyHandler::port() const

Gibt den Port zurück, an dem dieser Handler lauscht, andernfalls wird 0 zurückgegeben.

Siehe auch listen() und isListening().

[since 6.9] void QOAuthHttpServerReplyHandler::setCallbackHost(const QString &host)

Legt fest, dass host als Hostname-Komponente des callback() verwendet wird. Die Angabe eines nicht leeren host setzt das Standardverhalten außer Kraft, siehe IPv4 and IPv6.

Diese Funktion wurde in Qt 6.9 eingeführt.

Siehe auch callbackHost().

void QOAuthHttpServerReplyHandler::setCallbackPath(const QString &path)

Legt fest, dass path als Pfadkomponente von callback() verwendet werden soll.

Siehe auch callbackPath().

void QOAuthHttpServerReplyHandler::setCallbackText(const QString &text)

Legt fest, dass text als Antwort auf die Umleitung am Ende der Genehmigungsphase verwendet werden soll.

Siehe auch callbackText().

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.