使用 PKCE 的 OAuth 2.0 授权代码流程

​

使用 PKCE 的 OAuth 2.0 授权码流程

​

介绍

OAuth 2.0 是业界标准的授权协议，可对应用的访问范围进行更精细的控制，并支持跨多设备的授权流程。OAuth 2.0 允许你选择更细粒度的 scope，以便代表用户授予特定权限。 

要在你的 App 中启用 OAuth 2.0，你需要在开发者门户的 App 设置中，打开该 App 的身份验证设置并将其启用。

​

我的凭据会有效多久？  

默认情况下，除非你使用了 offline.access scope，否则通过带有 PKCE 的 Authorization Code Flow 创建的 access token 仅在两小时内有效。

​

刷新令牌

刷新令牌使应用能够通过刷新令牌流程，在不打扰用户的情况下获取新的 access token。

如果应用了 offline.access 范围（scope），将签发一个 OAuth 2.0 刷新令牌。使用该刷新令牌即可获取 access token。若未传入该范围，则不会生成刷新令牌。

以下是使用刷新令牌获取新的 access token 的请求示例：

POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=bWRWa3gzdnk3WHRGU1o0bmRRcTJ5VUxWX1lZTDdJSUtmaWcxbTVxdEFXcW5tOjE2MjIxNDc3NDM5MTQ6MToxOnJ0OjE' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ

​

App 设置

你可以将 App 的身份验证设置为 OAuth 1.0a 或 OAuth 2.0。你也可以启用 App 同时使用 OAuth 1.0a 和 OAuth 2.0。

OAuth 2.0 仅适用于 X API v2。如果你选择了 OAuth 2.0，你将在 App 的“Keys and Tokens”部分看到一个 Client ID。 

​

机密客户端

机密客户端 能以安全方式保存凭证，不会将其暴露给未授权方，并可与授权服务器安全进行认证，从而保护你的客户端密钥。公共客户端由于通常在浏览器或移动设备上运行，无法使用你的客户端密钥。如果你选择的 App 类型是机密客户端，你将获得一个客户端密钥（client secret）。

如果你在开发者门户中选择的客户端类型是机密客户端，你也可以看到一个客户端密钥。可选类型包括 Native App、Single Page App、Web App、Automated App 或 bot。Native App 和 Single Page App 属于公共客户端，而 Web App、Automated App 和 bot 属于机密客户端。

对于具有有效 Authorization Header 的机密客户端，你无需提供客户端 id。对于公共客户端的请求，你仍需在请求体中包含 client id。 

​

作用域

作用域允许你为 App 设置更细粒度的访问控制，确保 App 仅具有所需的权限。要了解各作用域与哪些 endpoint 对应，请查看我们的身份验证映射指南。

Scope	Description
tweet.read	你可查看的所有 Tweets，包括受保护账号的 Tweets。
tweet.write	代表你发布 Tweet 和 转发。
tweet.moderate.write	隐藏或取消隐藏对你 Tweets 的回复。
users.email	已认证用户的电子邮件地址。
users.read	你可查看的任何账号，包括受保护账号。
follows.read	关注你的人以及你关注的人。
follows.write	代表你关注或取消关注他人。
offline.access	在你撤销授权前保持与账号的连接。
space.read	你可查看的所有 Spaces。
mute.read	你已静音的账号。
mute.write	代表你静音或取消静音账号。
like.read	你已 like 的 Tweets 以及你可查看的 likes。
like.write	代表你对 Tweets 执行 like 或取消 like。
list.read	你创建或加入的 Lists 的列表、成员和关注者，包括私有列表。
list.write	代表你创建和管理 Lists。
block.read	你已屏蔽的账号。
block.write	代表你屏蔽或取消屏蔽账号。
bookmark.read	获取已认证用户加书签的 Tweets。
bookmark.write	为 Tweets 添加或移除书签。
media.write	上传媒体。

​

请求速率限制

在大多数情况下，请求速率限制与使用 OAuth 1.0a 进行身份验证时相同，唯有 Tweets 查询和 Users 查询例外。对于 Tweet 查询和用户查询，在使用 OAuth 2.0 时，我们将每个 App 的限制从每 15 分钟 300 次请求提升至每 15 分钟 900 次请求。欲了解更多，请查看我们的请求速率限制文档。

​

授权类型

在此次初始发布中，我们仅支持带有 PKCE 的授权码和刷新令牌这两种授权类型。未来我们可能会提供更多授权类型。

​

OAuth 2.0 流程

OAuth 2.0 的流程与我们目前在 OAuth 1.0a 中使用的流程相似。您可以在我们的相关文档中查看示意图和详细说明。 

​

术语表

术语	说明
授权类型（grant types）	OAuth 框架为不同用例规定了多种授权类型，并提供了创建新授权类型的机制。示例包括 authorization code、client credentials、device code 和 refresh token。
机密客户端（confidential client）	指能够与授权服务器安全进行身份验证的应用，例如可安全保管其注册的 client secret。
公共客户端（public client）	指无法使用已注册 client secret 的客户端，例如在浏览器或移动设备上运行的应用。
Authorization code 流程	由机密客户端和公共客户端使用，用于将 authorization code 交换为 access token。
PKCE	对 authorization code 流程的扩展，用于防御多种攻击，并使公共客户端能够安全地执行 OAuth 交换。
Client ID	可在开发者门户的“密钥和令牌”部分、标题为“Client ID”的位置找到。若未看到该项，请直接联系团队。生成 authorize URL 时需要使用 Client ID。
Redirect URI	你的回调 URL。你需要通过精确匹配校验。
Authorization code	允许应用代表用户调用 API。亦称 auth_code。一旦 App 所有者收到用户批准的 auth_code，该 auth_code 的有效期为 30 秒。你必须在 30 秒内将其交换为 access token，否则 auth_code 将过期。
Access token	Access tokens 是应用代表用户发起 API 请求时使用的令牌。
Refresh token	允许应用通过 refresh token 流程在无需提示用户的情况下获取新的 access token。
Client Secret	如果你选择的 App 类型为机密客户端，你将在 App 的“密钥和令牌”部分、“Client ID”下获得“Client Secret”。

​

参数

要构建 OAuth 2.0 授权 URL，你需要确保在授权 URL 中包含以下参数。

Parameter	Description
response_type	需要将该值设置为“code”，表示使用授权码。
client_id	可在开发者门户中“Client ID”项下找到。
redirect_uri	你的回调 URL。该值必须与 App 设置中定义的某个 Callback URL 精确匹配。对于 OAuth 2.0，回调 URL 需通过精确匹配校验。
state	你用于防范CSRF 攻击的随机字符串。长度最多 500 个字符。
code_challenge	一个 PKCE 参数，即为每次请求生成的随机机密。
code_challenge_method	指定生成 code_challenge 的方法（S256 或 plain）。

​

授权 URL

在 OAuth 2.0 中，你需要创建一个授权 URL，用于通过认证流程让用户完成身份验证，类似于使用 X 的“登录”。

你将创建的 URL 示例如下：

https://x.com/i/oauth2/authorize?response_type=code&client_id=M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ&redirect_uri=https://www.example.com&scope=tweet.read%20users.read%20account.follows.read%20account.follows.write&state=state&code_challenge=challenge&code_challenge_method=plain

要让此 URL 正常工作，您需要使用正确的编码；请务必查阅我们关于百分号编码的文档。