使用 PKCE 的 OAuth 2.0 授权码流程

​

使用 PKCE 的 OAuth 2.0 授权码流程

​

介绍

OAuth 2.0 是业界标准的授权协议，可让你更细致地控制应用的权限范围（scope），并支持跨多设备的授权流程。OAuth 2.0 允许你选择更细粒度的 scope，从而代表用户获取相应的特定权限。 

要在你的应用中启用 OAuth 2.0，你需要在开发者门户的应用设置中找到该应用的认证设置并将其开启。

​

我的凭据能保持有效多久？  

默认情况下，除非你使用了 offline.access 作用域，否则你通过带有 PKCE 的授权码流程创建的 access token 仅在两小时内有效。

​

刷新令牌

刷新令牌使应用能够通过刷新令牌流程在无需打扰用户的情况下获取新的访问令牌。

如果应用了 offline.access 作用域，将签发一个 OAuth 2.0 刷新令牌。使用该刷新令牌即可获取访问令牌；如果未包含此作用域，我们将不会生成刷新令牌。

使用刷新令牌获取新访问令牌的请求示例如下：

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

​

应用设置

你可以将应用的认证设置为 OAuth 1.0a 或 OAuth 2.0。也可以启用应用同时使用 OAuth 1.0a 和 OAuth 2.0。

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

​

机密客户端

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

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

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

​

作用域

作用域允许你为应用设置更细粒度的访问控制，使其仅具有所需的权限。要了解各作用域与哪些端点对应，请参阅我们的认证映射指南。

作用域	说明
tweet.read	你可查看的所有 Tweet，包括受保护账户的 Tweet。
tweet.write	代表你发布 Tweet 和转推（Retweet）。
tweet.moderate.write	隐藏或取消隐藏对你 Tweet 的回复。
users.email	已认证用户的电子邮件地址。
users.read	你可查看的任何账户，包括受保护账户。
follows.read	关注你的人以及你关注的人。
follows.write	代表你关注或取消关注他人。
offline.access	在你撤销访问前保持与你账户的连接。
space.read	你可查看的所有 Space。
mute.read	你已静音的账户。
mute.write	代表你静音或取消静音账户。
like.read	你点赞过的 Tweet 以及你可查看的点赞。
like.write	代表你点赞或取消点赞 Tweet。
list.read	你创建或加入的列表、列表成员和列表关注者，包括私密列表。
list.write	代表你创建和管理列表。
block.read	你已屏蔽的账户。
block.write	代表你屏蔽或取消屏蔽账户。
bookmark.read	获取已认证用户已加书签的 Tweet。
bookmark.write	为 Tweet 添加书签或移除书签。
media.write	上传媒体。

​

速率限制

在大多数情况下，速率限制与使用 OAuth 1.0a 进行身份验证时相同，但对 Tweet 查询和用户查询有例外。使用 OAuth 2.0 执行 Tweet 查询和用户查询时，我们将每个应用的限制从每 15 分钟 300 次请求提高到 900 次请求。要了解更多信息，请务必查看我们的速率限制文档。

​

授权类型

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

​

OAuth 2.0 流程

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

​

术语表

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

​

参数

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

参数	说明
response_type	需要使用“code”指明这是授权码。
client_id	可在开发者门户中 “Client ID” 标题下找到。
redirect_uri	你的回调 URL。该值必须与在你的应用设置中定义的某个回调 URL 完全一致。对于 OAuth 2.0，你需要对回调 URL 进行精确匹配验证。
state	你提供的用于防范CSRF 攻击的随机字符串。该字符串长度最多可达 500 个字符。
code_challenge	一个PKCE参数，为你发起的每个请求提供的随机密钥。
code_challenge_method	指定你用于发起请求的方法（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 正常工作，你需要使用正确的编码；请务必查看我们关于百分号编码的文档。