Back to Qt.io
Contact Us Blog Download Qt

QOAuthHttpServerReplyHandler Class

通过设置本地 HTTP 服务器来处理环回重定向。更多

头文件： #include <QOAuthHttpServerReplyHandler>
CMake： find_package(Qt6 REQUIRED COMPONENTS NetworkAuth)
target_link_libraries(mytarget PRIVATE Qt6::NetworkAuth)
qmake： QT += networkauth
继承于QOAuthOobReplyHandler

公共函数

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)

详细说明

该类可作为使用环回重定向的 OAuth 2.0授权流程的回复处理程序。

一旦流程的授权部分完成，重定向 URI就是授权服务器重定向用户代理（通常最好是系统浏览器）的位置。环回重定向 URI 使用http 作为方案，localhost或 IP 地址作为主机（请参阅IPv4 and IPv6 ）。

QOAuthHttpServerReplyHandler 会设置一个 localhost 服务器。一旦授权服务器将浏览器重定向到这个 localhost 地址，回复处理程序就会解析重定向 URI 的查询参数，然后通过a signal 发送授权完成信号。

要处理其他重定向 URI 方案，请参阅QOAuthUriSchemeReplyHandler 。

以下代码说明了使用方法。首先是所需变量：

QOAuth2AuthorizationCodeFlow m_oauth;
QOAuthHttpServerReplyHandler *m_handler = nullptr;

然后是 OAuth 设置（为简洁起见，省略了错误处理）：

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

最后，我们再设置 URI 方案回复处理程序：

m_oauth.setReplyHandler(m_handler);

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

IPv4 和 IPv6

如果处理程序是任意地址处理程序 (AnyIPv4, AnyIPv6, or Any)，则使用的回调形式为http://localhost:{port}/{path} 。处理程序将首先尝试监听 IPv4 环回地址，然后再监听 IPv6 地址。之所以使用localhost ，是因为它在 IPv4 和 IPv6 接口上都能正确解析。

对于环回地址（LocalHost or LocalHostIPv6 ），则使用 IP 字面形式（127.0.0.1 和::1 ）。

对于特定的 IP 地址，则直接使用所提供的 IP 文字，例如：对于 IPv4 地址，使用http://192.168.0.123:{port}/{path}。

也可以使用setCallbackHost() 手动指定回调 URL 的主机部分。例如，您可以将回调指定为localhost.localnet 。当然，您需要确保在重定向时该地址是可以访问的。

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

HTTP 和 HTTPS 回调

自 Qt 6.9 起，可以配置处理程序使用https URI 方案，而不是http 。方法是在调用listen() 时提供适当的QSslConfiguration 。处理程序内部将使用QSslServer ，回调（重定向 URL）的形式为https://{host}:{port}/{path}。

以下示例对此进行了说明：

// 读取证书和私钥autocertificates=QSslCertificate::fromPath(sslCertificateFile)；QFilekeyFile(sslPrivateKeyFile);if(!keyFile.open(QFile::ReadOnly)) {    qWarning("Cannot open key file");
   return; }QSslKeyprivateKey(&keyFile, QSsl::Rsa, QSsl::Pem);if(certificates.size()== 0 ||privateKey.isNull()) {    qWarning("SSL certificate data invalid");
   return; }// 创建 SSL 配置QSslConfiguration配置=QSslConfiguration::defaultConfiguration(); configuration.setLocalCertificate(certificates.at(0)); configuration.setPrivateKey(privateKey);// 使用 SSL 配置实例化处理程序 m_handler = newQOAuthHttpServerReplyHandler(1234, this); m_handler->listen(configuration);

如有可能，建议使用其他重定向 URI 选项，请参阅选择回复处理程序和Qt OAuth2 浏览器支持。

本地主机https 处理程序的主要用例应仅限于开发时间或严格控制和配置的环境。例如，有些授权服务器根本不允许使用纯http 重定向 URI，在这种情况下，这可能会增加开发的便利性。

从安全角度看，虽然使用 SSL/TLS 确实可以加密本地主机流量，但 OAuth2 也有其他安全机制，如PKCE 。在任何情况下，您都不应将私人证书密钥与应用程序一起分发。

注意： 如果证书不可信，浏览器会发出严重警告。这是自签证书的典型情况，其使用应仅限于开发时间。

成员函数文档

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

使用parent 作为父对象，构造一个 QOAuthHttpServerReplyHandler 对象。使用端口0 和地址LocalHost 调用listen() 。

另请参阅 listen()。

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

使用parent 作为父对象，构造 QOAuthHttpServerReplyHandler 对象。使用port 和地址LocalHost 调用listen() 。

另请参阅 listen()。

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

使用parent 作为父对象，构造 QOAuthHttpServerReplyHandler 对象。使用address 和port 调用listen() 。

另请参阅 listen()。

[virtual noexcept] QOAuthHttpServerReplyHandler::~QOAuthHttpServerReplyHandler()

销毁QOAuthHttpServerReplyHandler 对象。停止监听连接/重定向。

另请参见 close().

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

返回用作callback() /OAuth2 redirect_uri 参数主机组件的名称。

此函数在 Qt 6.9 中引入。

另请参阅 setCallbackHost()。

QString QOAuthHttpServerReplyHandler::callbackPath() const

返回用作callback() /OAuth2 redirect_uri 参数路径组件的路径。

另请参阅 setCallbackPath()。

QString QOAuthHttpServerReplyHandler::callbackText() const

返回授权阶段结束时响应重定向的文本。

文本将封装在一个简单的 HTML 页面中，并由执行重定向的浏览器/用户代理显示给用户。

默认文本为

Callback received. Feel free to close this page.

另请参见 setCallbackText()。

void QOAuthHttpServerReplyHandler::close()

告诉此处理程序停止监听连接/重定向。

另请参阅 listen().

bool QOAuthHttpServerReplyHandler::isListening() const

如果该处理程序当前正在监听，则返回true ，否则返回false 。

另请参阅 listen() 和close()。

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

告诉此处理程序监听address 和port 上的传入连接/重定向。如果监听成功，则返回true ，否则返回false 。

只有在执行初始授权阶段（通常由QOAuth2AuthorizationCodeFlow::grant() 调用启动）时，才需要主动监听。

建议在成功授权后关闭监听器。requesting access tokens 或刷新时不需要监听。

如果调用此函数时Null 作为address ，处理程序将尝试监听LocalHost ，如果失败，则监听LocalHostIPv6 。

另请参见IPv4 and IPv6 。

另请参阅 close()、isListening() 和QTcpServer::listen()。

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

告诉此处理程序在address 和port 上监听传入的https 连接/重定向。如果监听成功，则返回true ，否则返回false 。

更多信息请参见HTTP and HTTPS Callbacks 。

另请参阅 listen(const QHostAddress &, quint16),close(),isListening(),QSslServer, 和QTcpServer::listen().

quint16 QOAuthHttpServerReplyHandler::port() const

返回处理程序正在监听的端口，否则返回 0。

另请参阅 listen() 和isListening()。

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

设置host 作为callback() 的主机名组件。提供一个非空的host 会覆盖默认行为，请参见IPv4 and IPv6 。

此函数在 Qt 6.9 中引入。

另请参阅 callbackHost()。

void QOAuthHttpServerReplyHandler::setCallbackPath(const QString &path)

设置path 作为callback() 的路径组件。

另请参阅 callbackPath().

void QOAuthHttpServerReplyHandler::setCallbackText(const QString &text)

设置text ，以响应授权阶段结束时的重定向。

另请参阅 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.