OAuth for Data Plan Agent API

相关文档

OAuth 2.0 标准化为 RFC 6749。如需查看详细文档，请访问 https://oauth.net/2。HTTP 基本身份验证在 RFC 2617 第 2 节中定义。

概览

通常，为了向第三方应用授予访问受限资源（例如流量套餐和电子钱包详细信息）的权限，最终用户（资源所有者）需要与第三方共享其凭据。这会带来多个问题和限制，例如凭据存储、密码身份验证、对最终用户资源的广泛访问以及密码泄露等。OAuth2.0 通过引入授权层来解决这些问题，从而保护和限制对最终用户的受保护资源的访问。

GTAF 会获取访问令牌，而不是使用最终用户的凭据来访问受保护的资源（例如流量套餐详情）。访问令牌会代表 GTAF 的凭据颁发给 GTAF。然后，GTAF 会使用访问令牌访问由 DPA 托管的流量套餐详情。

下图提供了简要的信息流：

图 1：抽象化的 OAuth 流程。

访问令牌

访问令牌是 GTAF 用于从运营商的 DPA 访问流量套餐详情的凭据。访问令牌是一个字符串，表示向 GTAF 发出的授权。该字符串通常对 GTAF 不透明。令牌代表最终用户授予运营商的具体访问权限范围和持续时间，并由 DPA 和运营商的 OAuth 服务器强制执行。

访问令牌提供一个抽象层，将不同的授权构造（例如，用户名和密码）替换为 DPA 理解的单个令牌。相较于用于获取访问令牌的授权授权，这种抽象化的机制让颁发访问令牌更为严格，并且 DPA 不再需要各种身份验证方法。

根据运营商的安全要求，访问令牌可以有不同的格式、结构和利用率方法（例如加密属性）。GTAF 仅支持 [RFC6750] 中定义的不记名类型访问令牌。

客户端身份验证

GTAF 可作为“机密客户端”使用，并且能够确保密码安全。GTAF 目前仅支持 HTTP 基本身份验证，以便通过 DPA 进行身份验证。客户端标识符使用“application/x-www-form-urlencoded”编码算法进行编码，并使用编码值作为用户名；密码和算法使用相同的密码和密码。

颁发客户端凭据的机密客户端（如 GTAF）在向令牌端点发出请求时，使用运营商的 OAuth 服务器进行身份验证。客户端身份验证的用途：\

• 通过停用客户端或更改其凭据来恢复被盗用的客户端，从而防止攻击者滥用刷新令牌。更改一组客户端凭据比撤消整组刷新令牌的速度要快得多。
• 实施需要定期凭据轮替的身份验证管理最佳做法。

在向令牌端点发送请求时，GTAF 使用“client_id”请求参数标识自己。

特别重要的是能够轮替客户端凭据。OAuth 服务器必须能够支持轮替期间同时存在两对凭据，并且能够停用凭据。在典型的凭据轮替中：

1. 运营商在 OAuth 服务器上创建新凭据，并以安全方式将凭据提供给其技术支持客户经理。
2. Google 会测试新凭据，并将 GTAF 配置更改为使用新凭据。
3. Google 会通知运营商旧凭据可能已停用。
4. 运营商停用凭据并将通知 Google
5. Google 会验证旧凭据是否失效

OAuth 服务器必须能够支持上述轮替过程。

令牌端点

GTAF 使用令牌端点通过显示授权授权或刷新令牌来获取访问令牌。令牌端点用于每个授权授权（隐式授权类型除外），因为访问令牌直接颁发。

在配置令牌端点时，您需要考虑以下几点：

• 应在服务文档中提供令牌端点的位置。
• 端点 URI 可能包含一个“application/x-www-form-urlencoded”格式的查询组件，在添加其他查询参数时必须保留该组件。端点 URI 不得包含 fragment 组件。
• 由于向令牌端点发出的请求会导致传输明文凭据（在 HTTP 请求和响应中），因此运营商的 OAuth 服务器必须使用 TLS 向令牌端点发送请求。
• 发出访问令牌请求时，GTAF 会使用 HTTP“POST”方法。
• 如果发送的参数没有值，则必须将其视为请求中省略的参数。 OAuth 服务器必须忽略无法识别的请求参数。请求和响应参数不得超过一次。
• GTAF 仅支持不记名类型的访问令牌。

访问令牌范围

授权和令牌端点允许客户端使用 &scope 请求参数指定访问请求的范围。反过来，授权服务器会使用“范围”响应参数告知客户端所颁发的访问令牌范围。

范围参数的值表示为以空格分隔且区分大小写的字符串列表。字符串由授权服务器定义。如果值包含多个空格分隔的字符串，则它们的顺序无关紧要，并且每个字符串都会向请求的范围添加一个额外的访问范围。

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF 不需要实现范围，但支持此功能。如需了解详情，请参阅 RFC 6749 的第 3.3 节。

颁发访问令牌

如果 GTAF 发送的访问令牌请求有效且已获得授权，OAuth 服务器就会发出访问令牌和可选的刷新令牌。如果请求未通过客户端身份验证或无效，OAuth 服务器将返回错误响应，如下一部分中所述。

成功响应

当 GTAF 发出请求时，OAuth 服务器会发出访问令牌和可选的刷新令牌，并通过将以下参数添加到具有 200 (OK) 状态代码的 HTTP 响应的实体正文中来构建响应：

• access_token：必需。OAuth 服务器发出的访问令牌。GTAF 要求令牌端点返回不记名令牌。
• expires_in：必需。访问令牌的生命周期（以秒为单位）。例如，值“3600”表示访问令牌将在响应生成后的一小时内过期。如果省略此参数，OAuth 服务器应通过其他方式提供过期时间，或记录默认值。
• token_type：必需。所颁发令牌的类型。如需详细了解不同类型的令牌，请参阅 RFC 6749 的第 7.1 节。该值不区分大小写。撰写本文时，GTAF 仅支持不记名令牌。
• refresh_token：可选。刷新令牌，可用于通过相同的授权授权来获取新的访问令牌。
• scope：可选，如果已实现且与 GTAF 请求的范围相同，否则为必需项。

这些参数包含在 HTTP 响应的实体正文中，并使用“application/json”。通过在最高结构级别添加每个参数，这些参数会被序列化为 JavaScript 对象表示法 (JSON) 结构。参数名称和字符串值以 JSON 字符串的形式包含在内。数值作为 JSON 数字包含在内。参数的顺序无关紧要，并且可能会有所不同。

授权服务器必须在包含令牌、凭据或其他敏感信息的任何响应中包括值为“no-store”的 HTTP“Cache-Control”响应标头字段，以及值为“no-cache”的“Pragma”响应标头字段。

例如：

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

以下是需要考虑的一些重要事项：

• GTAF 会忽略响应中无法识别的值的名称。
• 从 OAuth 服务器接收的令牌大小和其他值将保持未定义状态。
• GTAF 应避免对值大小做出假设。OAuth 服务器应记录其发出的所有值的大小。

错误响应

如果授权请求因任何原因（例如重定向 URI 缺失、无效或不匹配）而失败，或者客户端标识符缺失或无效，OAuth 服务器应返回 HTTP 400（错误请求）状态代码（除非另有说明），并且至少应包含“错误响应和代码”部分中列出的一个参数。

GTAF 中的授权

授权授权是表示最终用户授权（访问受保护的资源，例如数据余额信息）的凭据，GTAF 使用该凭据来获取访问令牌。

GTAF 使用 client_credentials 授权类型。在 client_credentials 授权类型中，GTAF 使用 HTTP POST 请求和 HTTP 基本身份验证来请求令牌。所有请求都通过传输层安全协议 (TLS)（即HTTPS）并且没有有效的 TLS 证书，GTAF 无法与 OAuth 服务器集成。GTAF 可以传递可配置的令牌范围，如果未配置，则会传递空范围。

GTAF 要求系统返回一个访问令牌以及“expires_in”值（存留时间）。expires_in 值至少应为 900 秒，且不应超过几个小时。请求新令牌不得导致现有令牌提前过期。

如需详细了解各种授权类型，请参阅 RFC 6749 的第 1.3 节。

请求和响应示例

假设 GTAF 为 OAuth 服务器进行了以下配置：

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

注意：真实 DPA 的客户端密钥必须比示例中显示的密钥安全得多。

为了生成授权字符串，客户端 ID、 ':' 和密码会相互连接并使用 base64 编码。这可以在命令行界面中复制，如下所示：

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

然后，GTAF 使用这些凭据、client_credentials 授权类型和配置的范围向 OAuth 服务器发出 HTTPS POST 请求。在此示例中，GTAF 的请求类似于以下命令生成的请求：

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

GTAF 使用的标头与 curl 发送的标头不匹配，尽管授权标头完全相同。

GTAF 希望收到以下形式的响应：

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

以下是有效响应的示例：

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

注意：响应必须是有效的 JSON。

错误响应和代码

如果来自 GTAF 的授权请求因“错误响应”部分中所述的任何原因失败，OAuth 服务器必须以 HTTP 400（错误请求）状态代码进行响应（除非另有指定），并在响应中包含以下参数之一：

例如：\

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF 要求 OAuth 服务器支持以下错误响应：

错误代码	响应	原因
HTTP 400	invalid_request	请求缺少一个必需参数、包含不受支持的参数值（授权类型除外）、重复参数、包含多个凭据、使用多种机制进行 GTAF 身份验证，或者存在格式错误。
HTTP 401	invalid_client	客户端身份验证失败（例如，未知客户端、未包含客户端身份验证或不支持的身份验证方法）。OAuth 服务器可能会返回 HTTP 401（未授权）状态代码，表明支持哪些 HTTP 身份验证方案。如果客户端尝试通过“授权”请求标头字段进行身份验证，OAuth 服务器必须以 HTTP 401（未授权）状态代码进行响应，并包含与客户端使用的身份验证方案匹配的“WWW-Authenticate”响应标头字段。
HTTP 500	OAuth 服务器故障

如需详细了解可用于调试的其他响应，请参阅 RFC 6749 的第 5.2 节。