150 lines
5.6 KiB
Markdown
150 lines
5.6 KiB
Markdown
# 使用 API 进行身份验证
|
||
|
||
使用客户端 API 需要进行身份验证。本页记录了如何获取身份验证令牌的通用流程，并提供了使用 `curl` 在命令行界面进行操作的示例。
|
||
|
||
## 创建新应用
|
||
|
||
我们需要注册一个新应用，以便请求 OAuth 令牌。这可以通过向 `/api/v1/apps` 端点发送 `POST` 请求来完成。注意将下面命令中的 `your_app_name` 替换为你想使用的应用名称：
|
||
|
||
```bash
|
||
curl \
|
||
-X POST \
|
||
-H 'Content-Type:application/json' \
|
||
-d '{
|
||
"client_name": "your_app_name",
|
||
"redirect_uris": "urn:ietf:wg:oauth:2.0:oob",
|
||
"scopes": "read"
|
||
}' \
|
||
'https://example.org/api/v1/apps'
|
||
```
|
||
|
||
字符串 `urn:ietf:wg:oauth:2.0:oob` 表示一种称为带外身份验证的技术，这是一种用于多因素身份验证的技术，旨在减少恶意行为者干扰身份验证过程的途径。在此情况下，它允许我们查看并手动复制生成的令牌以便继续使用。
|
||
|
||
注意，`scopes` 可以是以下任意空格分隔的组合：
|
||
|
||
- `read`
|
||
- `write`
|
||
- `admin`
|
||
|
||
!!! warning
|
||
GoToSocial 目前不支持范围授权令牌，因此在此过程中获得的任何令牌都可以代表你执行所有操作，包括如果你的账户具有管理员权限时的管理员操作。然而，始终以最低权限授予你的应用是一个好习惯。例如，如果你的应用不会发布贴文，请使用 scope=read。
|
||
|
||
本着这种精神，上述示例使用了`read`，这意味着当未来支持范围令牌时，应用将仅限于执行`read`操作。
|
||
|
||
你可以在[此处](https://github.com/superseriousbusiness/gotosocial/issues/2232)阅读更多关于计划中 OAuth 安全功能的信息。
|
||
|
||
成功调用会返回一个带有 `client_id` 和 `client_secret` 的响应，我们将在后续流程中需要使用这些信息。它看起来像这样：
|
||
|
||
```json
|
||
{
|
||
"id": "01J1CYJ4QRNFZD6WHQMZV7248G",
|
||
"name": "your_app_name",
|
||
"redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
|
||
"client_id": "YOUR_CLIENT_ID",
|
||
"client_secret": "YOUR_CLIENT_SECRET"
|
||
}
|
||
```
|
||
|
||
!!! tip
|
||
确保将 `client_id` 和 `client_secret` 的值保存到某个位置，以便在需要时参考。
|
||
|
||
## 授权你的应用代表你操作
|
||
|
||
我们已经在 GoToSocial 注册了一个新应用，但它尚未与你的账户连接。现在，我们需要告知 GoToSocial 这个新应用将代表你操作。为此，我们需要通过浏览器进行实例认证，以启动登录和权限授予过程。
|
||
|
||
创建一个带查询字符串的 URL，如下所示，将 `YOUR_CLIENT_ID` 替换为你在上一步收到的 `client_id`，然后将 URL 粘贴到浏览器中：
|
||
|
||
```text
|
||
https://example.org/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&scope=read
|
||
```
|
||
|
||
!!! tip
|
||
如果你在注册应用时使用了不同的范围，在上面的 URL 中将 `scope=read` 替换为你注册时使用的加号分隔的范围列表。例如，如果你注册你的应用时使用了 `scopes` 值 `read write`，那么你应该将上面的 `scope=read` 改为 `scope=read+write`。
|
||
|
||
将 URL 粘贴到浏览器后，你会被引导到实例的登录表单，提示你输入邮箱地址和密码以将应用连接到你的账户。
|
||
|
||
提交凭据后，你会到达一个页面，上面写着类似这样的内容：
|
||
|
||
```
|
||
嗨嗨，`your_username`!
|
||
|
||
应用 `your_app_name` 申请以你的名义执行操作，申请的权限范围是 *`read`*.
|
||
如果选择允许，应用将跳转到： urn:ietf:wg:oauth:2.0:oob 继续操作
|
||
```
|
||
|
||
点击 `允许`，你将到达这样一个页面：
|
||
|
||
```text
|
||
Here's your out-of-band token with scope "read", use it wisely:
|
||
YOUR_AUTHORIZATION_TOKEN
|
||
```
|
||
|
||
复制带外授权令牌到某个地方，因为你将在下一步中需要它。
|
||
|
||
## 获取访问令牌
|
||
|
||
下一步是用刚刚收到的带外授权令牌交换一个可重用的访问令牌，该令牌可以在以后所有的 API 请求中发送。
|
||
|
||
你可以通过另一个 `POST` 请求来完成这项操作，如下所示：
|
||
|
||
```bash
|
||
curl \
|
||
-X POST \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
|
||
"client_id": "YOUR_CLIENT_ID",
|
||
"client_secret": "YOUR_CLIENT_SECRET",
|
||
"grant_type": "authorization_code",
|
||
"code": "YOUR_AUTHORIZATION_TOKEN"
|
||
}' \
|
||
'https://example.org/oauth/token'
|
||
```
|
||
|
||
确保替换：
|
||
|
||
- `YOUR_CLIENT_ID` 为第一步中收到的客户端 ID。
|
||
- `YOUR_CLIENT_SECRET` 为第一步中收到的客户端密钥。
|
||
- `YOUR_AUTHORIZATION_TOKEN` 为在第二步中收到的带外授权令牌。
|
||
|
||
你会收到一个包含访问令牌的响应，看起来像这样：
|
||
|
||
```json
|
||
{
|
||
"access_token": "YOUR_ACCESS_TOKEN",
|
||
"created_at": 1719577950,
|
||
"scope": "read",
|
||
"token_type": "Bearer"
|
||
}
|
||
```
|
||
|
||
将你的访问令牌复制并安全保存。
|
||
|
||
## 验证
|
||
|
||
为了确保一切正常，尝试查询 `/api/v1/verify_credentials` 端点，在请求头中添加你的访问令牌作为 `Authorization: Bearer YOUR_ACCESS_TOKEN`。
|
||
|
||
请参考以下示例：
|
||
|
||
```bash
|
||
curl \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
|
||
'https://example.org/api/v1/accounts/verify_credentials'
|
||
```
|
||
|
||
如果一切顺利，你应该会得到用户资料的 JSON 响应。
|
||
|
||
## 最后说明
|
||
|
||
现在你拥有了访问令牌，可以在每次 API 请求中重复使用该令牌进行授权。你不需要每次都执行整个令牌交换过程！
|
||
|
||
例如，你可以使用相同的访问令牌向 API 发送另一个 `GET` 请求以获取通知，如下所示：
|
||
|
||
```bash
|
||
curl \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
|
||
'https://example.org/api/v1/notifications'
|
||
```
|