如何通过带有 PKCE 的 OAuth 2.0 授权码流程连接到端点

​

如何使用带有 PKCE 的 OAuth 2.0 授权码流程连接到端点

​

如何连接到这些端点

要对用户进行身份验证，你的应用需要实现授权流程。该流程会将用户引导至 X 上的授权对话框。随后，X 的核心体验会显示该对话框，并代表你的应用处理授权。用户可以同意授权你的应用，或拒绝授权。用户作出选择后，X 会将其重定向回你的应用；如果用户已授权，你可以用授权码换取访问令牌；如果未授权，则需要处理拒绝情况。

​

使用机密客户端

如果你在使用机密客户端，你需要采用basic authentication方案，在向令牌端点发起请求时，使用 base64 编码生成授权头。

在凭据中的 base64 编码字符串里，userid 和 password 由一个冒号 (”:”) 分隔。

示例如下：

-header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='

如果用户代理希望发送 Client ID “Aladdin” 和密码 “open sesame”，应使用如下头字段：

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

要创建 basic 授权头，你需要对你的 Client ID 和 Client Secret 进行 base64 编码；这些可以从你的应用在开发者门户内的“Keys and Tokens”页面获取。

​

使用 OAuth 2.0 进行连接的步骤

步骤 1：构建 Authorize URL

你的应用需要构建一个指向 X 的 authorize URL，并指明应用所需的授权范围（scopes）。例如，如果你的应用需要查询 Tweets、用户，以及管理关注关系，则应请求以下 scopes：

tweet.read%20users.read%20follows.read%20follows.write

除其他必需参数外，该 URL 还应包含 code_challenge 和 state 参数。在生产环境中，code_challenge 应使用随机字符串。

步骤 2：GET oauth2/authorize

引导用户完成身份验证并向应用发送授权代码（authorization code）。如果你已为应用启用 OAuth 2.0，可以在应用的“Keys and Tokens”页面找到 Client ID。

用于将用户重定向的示例 URL 如下所示：

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

带有 offline_access 的示例 URL 如下：

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

在成功完成认证后，你的 redirect_uri 会收到一个包含 auth_code 参数的请求。你的应用应当验证 state 参数。

来自客户端重定向的示例请求如下：

https://www.example.com/?state=state&code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE

步骤 3：POST oauth2/token - 访问令牌

此时，你可以使用授权代码创建访问令牌和刷新令牌（仅在请求了 offline.access 范围时）。你可以向以下端点发送 POST 请求：

https://api.x.com/2/oauth2/token

你需要在请求头中传入 Content-Type: application/x-www-form-urlencoded。此外，请在请求中包含：code、grant_type、client_id、redirect_uri，以及 code_verifier。

以下是针对公共客户端的示例令牌请求：

curl --location --request POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ' \
--data-urlencode 'redirect_uri=https://www.example.com' \
--data-urlencode 'code_verifier=challenge'

下面是一个使用机密客户端的示例：

curl --location --request POST 'https://api.x.com/2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='\
--data-urlencode 'code=VGNibzFWSWREZm01bjN1N3dicWlNUG1oa2xRRVNNdmVHelJGY2hPWGxNd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://www.example.com' \
--data-urlencode 'code_verifier=challenge'

步骤 4：连接到 API

你现在可以使用 OAuth 2.0 连接到这些端点了。为此，你将像使用 Bearer Token 认证 一样向 API 发起请求。不同的是，你需要使用上一步生成的 access token，而不是传递你的 Bearer Token。作为响应，你应当看到与所请求端点相对应的负载。此请求对于 public 和 confidential 客户端是相同的。 

你将要发起的请求示例如下：

curl --location --request GET 'https://api.x.com/2/tweets?ids=1261326399320715264,1278347468690915330' \
--header 'Authorization: Bearer Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE'

步骤 5：POST oauth2/token - 刷新令牌

刷新令牌使应用无需提示用户即可获取新的访问令牌。你可以通过向以下端点发起 POST 请求来获取刷新令牌：https://api.x.com/2/oauth2/token。你需要在请求头中设置 Content-Type 为 application/x-www-form-urlencoded。此外，还需要传入 refresh_token，将 grant_type 设置为 refresh_token，并指定 client_id。

此请求适用于公共客户端：

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'

以下是一个面向机密客户端的示例：

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

步骤 6：POST oauth2/revoke - 吊销令牌

撤销令牌会使访问令牌或刷新令牌失效。它用于在客户端启用“退出登录”功能，便于清理与授权流程相关且可能已不再需要的任何安全凭据。撤销令牌供应用用于撤销令牌，而非供用户使用。如果应用希望以编程方式撤销其被授予的访问权限，可向以下 URL 发送 POST 请求以创建撤销令牌请求：

https://api.x.com/2/oauth2/revoke

您需要通过请求头传入 Content-Type: application/x-www-form-urlencoded，以及您的令牌和 client_id。

在某些情况下，用户可能希望撤销已授予某个应用的访问权限，他们可以前往已连接的应用页面进行撤销。

curl --location --request POST 'https://api.x.com/2/oauth2/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE' \
--data-urlencode 'client_id=rG9n6402A3dbUJKzXTNX4oWHJ'

此请求适用于机密型客户端：

curl --location --request POST 'https://api.x.com/2/oauth2/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic V1ROclFTMTRiVWhwTWw4M2FVNWFkVGQyTldNNk1UcGphUTotUm9LeDN4NThKQThTbTlKSXQyZm1BanEzcTVHWC1icVozdmpKeFNlR3NkbUd0WEViUA=='\
--data-urlencode 'token=Q0Mzb0VhZ0V5dmNXSTEyNER2MFNfVW50RzdXdTN6STFxQlVkTGhTc1lCdlBiOjE2MjIxNDc3NDM5MTQ6MToxOmF0OjE'