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 方案 reply-handler：
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);
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 配置
QSslConfiguration configuration=QSslConfiguration::defaultConfiguration();
configuration.setLocalCertificate(certificates.at(0));
configuration.setPrivateKey(privateKey);
// 使用 SSL 配置实例化处理程序
m_handler= newQOAuthHttpServerReplyHandler(1234, this);
m_handler->listen(configuration);在可能的情况下，建议使用其他重定向 URI 选项，请参阅《选择响应处理程序》和《Qt OAuth2 浏览器支持》。
localhosthttps 处理程序的主要用例应仅限于开发阶段，或受严格控制和配置的环境。例如，某些授权服务器完全不允许使用纯http 重定向 URI，在这种情况下，此方法可提高开发便利性。
从安全角度来看，虽然使用 SSL/TLS 确实会加密 localhost 流量，但 OAuth2 还采用了其他安全机制，例如PKCE 。在任何情况下，都不应将私有证书密钥与应用程序一起分发。
注意： 如果证书不受信任，浏览器 会发出严重警告。自签名证书通常会出现这种情况，其使用应仅限于开发阶段。
成员函数文档
[explicit] QOAuthHttpServerReplyHandler::QOAuthHttpServerReplyHandler(QObject *parent = nullptr)
使用parent 作为父对象，构建一个QOAuthHttpServerReplyHandler对象。调用listen()方法，端口为0 ，地址为LocalHost 。
另请参阅 listen()。
[explicit] QOAuthHttpServerReplyHandler::QOAuthHttpServerReplyHandler(quint16 port, QObject *parent = nullptr)
使用parent 作为父对象，构建一个QOAuthHttpServerReplyHandler对象。调用listen()方法，传入port 和地址LocalHost 。
另请参阅 listen()。
[explicit] QOAuthHttpServerReplyHandler::QOAuthHttpServerReplyHandler(const QHostAddress &address, quint16 port, QObject *parent = nullptr)
使用parent 作为父对象，构造一个QOAuthHttpServerReplyHandler对象。调用listen()，并传入address 和port 作为参数。
另请参阅 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 。
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()。
© 2026 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.
