Qt OAuth2 概述

OAuth2

RFC 6749 OAuth 2.0定义了一个授权框架，可在不暴露密码等敏感用户凭证的情况下实现资源授权。

OAuth2 框架定义了几种客户端类型（公开和保密）以及流程（隐式、授权代码和其他几种）。对于典型的 Qt 应用程序，客户端类型应视为公共本地应用程序。公开意味着该应用程序不被信任，不会在已发布的二进制文件中保留密码等机密。

RFC 8252 OAuth 2.0 for Native Apps进一步定义了此类应用程序的最佳实践。QtNetworkAuth 提供了该流程的具体实现，它也是本文档的重点。

Qt OAuth2 类

QtNetworkAuth 提供了具体和抽象的 OAuth2 类。抽象类用于实现自定义流，而具体类则提供具体实现。

要使用QtNetworkAuth 实现 OAuth2 流程，需要两个类：

• 一个OAuth2 流程实现类提供主要 API，是流程的协调者。它通常拥有一个回复处理程序。抽象类是QAbstractOAuth2 ，具体实现是QOAuth2AuthorizationCodeFlow 。
• 回复处理程序类用于处理来自授权服务器的回复。授权代码流包括授权、访问令牌请求和访问令牌刷新。处理回复的结果由流程类进一步处理。回复处理程序的抽象类是QAbstractOAuthReplyHandler ，具体类是QOAuthHttpServerReplyHandler 和QOAuthUriSchemeReplyHandler 。

授权代码流程

授权代码流是 推荐用于本地应用程序（如 Qt 应用程序）的OAuth2 流程。

以下代码片段提供了一个设置示例：

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

阶段

授权代码流有两个主要阶段：资源授权（包括任何必要的用户身份验证）和访问令牌请求。随后是使用访问令牌和刷新访问令牌。下图说明了这些阶段：

• 在授权阶段，用户通过身份验证，并授权访问资源。这需要用户与浏览器交互。
• 授权后，收到的授权码将用于申请访问令牌，也可用于申请刷新令牌。
• 一旦获得访问令牌，应用程序就可以使用它访问感兴趣的资源。访问令牌包含在资源请求中，由资源服务器来验证令牌的有效性。在请求中包含令牌有多种方法，但在HTTPAuthorization 标头中包含令牌可以说是最常见的方法。
• 刷新访问令牌。访问令牌的过期时间通常相对较短，比如一小时后。如果应用程序除访问令牌外还收到了刷新令牌，则可使用刷新令牌请求新的访问令牌。刷新令牌的有效期较长，应用程序可将其持久化，以避免进入新的授权阶段（从而再次与浏览器交互）。

细节和定制

OAuth2 流程是动态的，一开始很难了解其细节。下图说明了成功授权代码流的主要细节。

为了清晰起见，图中省略了一些不常用的信号，但总的来说说明了细节和主要定制点。自定义点是应用程序可以捕捉（和调用）的各种信号/插槽，以及可通过QAbstractOAuth::setModifyParametersFunction() 设置的回调。

选择回复处理程序

决定使用或实施哪种回复处理程序取决于所使用的redirect_uri。redirect_uri 是浏览器在授权阶段结束后的重定向位置。

在本地应用程序中，RFC 8252 概述了三种主要的 URI 方案：loopback、https 和私人使用。

• 私人使用 URI：如果操作系统允许应用程序注册自定义 URI 方案，则可以使用。尝试打开带有此类自定义方案的 URL 时，将打开相关的本地应用程序。请参见QOAuthUriSchemeReplyHandler 。
• HTTPS URI：如果操作系统允许应用程序注册自定义 HTTPS URL，则可以使用该 URL。尝试打开此 URL 将打开相关本地应用程序。如果操作系统支持，建议使用此方案。请参见QOAuthUriSchemeReplyHandler 。
• 环回接口：这些接口通常用于桌面应用程序和开发过程中的应用程序。QOAuthHttpServerReplyHandler 设计用于通过设置本地服务器来处理这些 URI，以处理重定向。

选择取决于以下几个因素

• 授权服务器供应商支持的重定向 URI。各厂商的支持不尽相同，而且通常针对特定的客户端类型和操作系统。此外，支持情况可能因应用程序是否发布而异。
• 目标平台支持的重定向 URI 方案。
• 应用程序特定的可用性、安全性和其他要求。

与其他方法相比，RFC 8252 建议使用https 方案，以获得安全性和可用性方面的优势。