Back to Qt.io
Contact Us Blog Download Qt

QOAuthUriSchemeReplyHandler Class

处理私有/自定义和 https URI 方案重定向。更多

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

属性

公共功能

QOAuthUriSchemeReplyHandler()
QOAuthUriSchemeReplyHandler(QObject *parent)
QOAuthUriSchemeReplyHandler(const QUrl &redirectUrl, QObject *parent = nullptr)
virtual ~QOAuthUriSchemeReplyHandler() override
void close()
(since 6.9) bool handleAuthorizationRedirect(const QUrl &url)
bool isListening() const
bool listen()
QUrl redirectUrl() const
void setRedirectUrl(const QUrl &url)

信号

void redirectUrlChanged()

详细说明

该类是使用私有/自定义或 HTTPS URI 方案进行重定向的OAuth 2.0授权流程的回复处理程序。它负责管理授权重定向的接收（也称为回调）以及访问令牌的后续获取。

一旦流程的授权部分完成，重定向 URI就是授权服务器重定向用户代理（通常最好是系统浏览器）的位置。

使用特定的 URI 方案需要在操作系统层面进行配置，以便将 URI 与正确的应用程序关联起来。设置这种关联的方法因操作系统而异。参见Platform Support and Dependencies 。

该类是QOAuthHttpServerReplyHandler 的补充，后者通过设置本地主机服务器来处理http 方案。

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

QOAuth2AuthorizationCodeFlow m_oauth;
QOAuthUriSchemeReplyHandler m_handler;

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

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

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_handler.setRedirectUrl(QUrl{"com.example.myqtapp://oauth2redirect"_L1});
m_oauth.setReplyHandler(&m_handler);

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

私有/自定义 URI 方案

自定义 URI 方案通常使用反向域符号，后跟路径，有时也使用主机/主机+路径：

// Example with path:
com.example.myapp:/oauth2/callback
// Example with host:
com.example.myapp://oauth2.callback

HTTPS URI 方案

对于 HTTPS URI 方案，重定向 URL 是普通的 https 链接：

https://myapp.example.com/oauth2/callback

这些链接在 iOS 上称为通用链接，在 Android 上称为应用链接。

建议使用 https 方案，因为它能提供额外的安全性，迫使应用程序开发人员证明所使用 URL 的所有权。这种证明是通过托管关联文件来完成的，操作系统在进行内部 URL 调度时会参考该文件。

该文件的内容将应用程序和使用的 URL 关联起来。关联文件必须是可公开访问的，没有任何 HTTP 重定向。此外，托管网站必须有有效的证书，而且至少在安卓系统中，该文件必须以application/json content-type 类型提供（请参阅服务器配置指南）。

此外，https 链接还能带来一些可用性方面的好处：

  • https URL 可作为普通的 https 链接。如果用户尚未安装应用程序（因为 URL 并非由任何应用程序处理），https 链接可以提供安装说明。
  • 这样就避免了打开 URL 的应用程序选择对话，而是自动打开你的应用程序。

这样做的代价是需要额外的设置，因为你需要设置这个公开托管的关联文件。

平台支持和依赖性

目前支持的平台有安卓、iOS 和 macOS。

URI 方案监听基于QDesktopServices::setUrlHandler() 和QDesktopServices::unsetUrlHandler() 。这些功能目前由 Qt::Gui 模块提供，因此QtNetworkAuth 模块依赖于 Qt::GUI。如果QtNetworkAuth 的构建不包含 Qt::GUI，则不会包含 QOAuthUriSchemeReplyHandler。

安卓系统

在Android上，URI 方案要求

另请参阅Qt Android 清单文件配置。

iOS 和 macOS

在iOS和macOS上，URI 方案要求

Windows、Linux

目前不支持。不过，支持 Qt WebEngine的平台和用例仍可使用此回复处理程序--详情请参阅Qt OAuth2 浏览器支持。

属性文档

redirectUrl : QUrl

该属性包含用于接收授权重定向/响应的 URL。

该属性用作OAuth2 redirect_uri 参数，作为授权请求的一部分发送。redirect_uri 可通过调用带有默认选项的QUrl::toString() 获取。

该 URL 必须与在授权服务器上注册的 URL 匹配，因为授权服务器可能会拒绝任何不匹配的 redirect_uri。

同样，当该处理程序收到重定向时，重定向 URL 必须与此处设置的 URL 匹配。处理程序会比较方案、主机、端口、路径和本方法设置的 URL 中的任何查询项。

只有全部匹配后，URL 才会被处理。查询参数的比较不包括服务器端可能设置的任何其他查询参数，因为这些参数包含实际的相关数据。

访问功能：

QUrl redirectUrl() const
void setRedirectUrl(const QUrl &url)

Notifier 信号：

void redirectUrlChanged()

成员函数文档

QOAuthUriSchemeReplyHandler::QOAuthUriSchemeReplyHandler()

构造一个 QOAuthUriSchemeReplyHandler 对象，该对象的callback()/redirectUrl() 为空，且无父对象。构建的对象不会自动监听。

[explicit] QOAuthUriSchemeReplyHandler::QOAuthUriSchemeReplyHandler(QObject *parent)

构造一个 QOAuthUriSchemeReplyHandler 对象，包含parent 和空callback()/redirectUrl()。构建的对象不会自动监听。

[explicit] QOAuthUriSchemeReplyHandler::QOAuthUriSchemeReplyHandler(const QUrl &redirectUrl, QObject *parent = nullptr)

构造一个 QOAuthUriSchemeReplyHandler 对象，并将parent 设置为父对象，将redirectUrl 设置为重定向 URL。构建的对象会自动尝试监听。

另请参阅 redirectUrl()、setRedirectUrl()、listen() 和isListening()。

[override virtual noexcept] QOAuthUriSchemeReplyHandler::~QOAuthUriSchemeReplyHandler()

销毁QOAuthUriSchemeReplyHandler 对象。关闭该处理程序。

另请参阅 close().

void QOAuthUriSchemeReplyHandler::close()

告诉该处理程序停止监听传入的 URL。

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

[since 6.9] bool QOAuthUriSchemeReplyHandler::handleAuthorizationRedirect(const QUrl &url)

该函数用于提供授权服务器在授权阶段结束时提供的重定向 URL。所提供的url 会进行与redirectUrl 中所述相同的 URL 匹配。

如果重定向 URL 是通过其他方式捕获的，例如使用 Qt WebEngine或通过其他自定义安排捕获重定向 URL 的情况下，提供 URL 将非常有用。这样，此类代理的使用就可以与 OAuth2 流程的其他部分集成。

该处理程序无需监听，因此建议使用close() 来避免不必要的监听。

如果 URL 匹配并已处理，则返回true ，否则返回false 。

另请参阅 Qt WebEngine 重定向 URI 方案。

此函数在 Qt 6.9 中引入。

[noexcept] bool QOAuthUriSchemeReplyHandler::isListening() const

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

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

bool QOAuthUriSchemeReplyHandler::listen()

告诉此处理程序监听传入的 URL。如果监听成功，则返回true ，否则返回false 。

处理程序将把 URL 与redirectUrl() 匹配。如果收到的 URL 不匹配，则会转发到 QDesktopServices::openURL()。

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

建议在成功授权后关闭监听器。acquiring access tokens 不需要监听。

© 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.