OAuth 2.0介绍
Buddy API使用OAuth 2.0进行身份验证。OAuth 2.0是一种协议，允许外部应用程序在不获取用户密码的情况下请求对用户数据中的私人信息进行授权。令牌可以仅限于特定类型的数据，并且可以由用户随时撤销。所有开发人员都需要在开始之前注册他们的应用程序。已注册的OAuth应用程序分配有唯一的客户端ID和客户端密钥。客户端密钥应妥善保管好而不被泄露。
2022年3月更新
为提高安全性，自2022年3月29日起，新创建的应用程序中的令牌将在8小时后自动过期。
在旧应用程序中，令牌永不过期。如果您的应用程序使用旧类型的令牌，您将在应用程序屏幕上看到此通知：
过期的令牌可以使用刷新令牌重新生成。为旧类型的应用程序重新生成的令牌也附带刷新令牌，即使它们不会过期。
新建OAuth应用
要开始开发，您需要在帐户资料中添加应用程序，需要以下数据：
| 名称 | 描述 |
|---|---|
名称 必填 | Buddy中显示的应用程序名称 |
首页URL 必填 | 应用程序主页的完整URL |
授权回调地址 必填 | 授权后将发送用户应用中的URL |
| 描述 | 向您的应用程序所有用户显示的描述 |
| 徽标 | 您的应用程序列表上显示的徽标 |
添加后，应用程序将包含进一步步骤所需的客户端ID和客户端密钥。
Web应用流程
1. 将用户重定向地址获取访问权限
GET https://api.buddy.works/oauth2/authorize
GET参数
| 名称 | 类型 | 描述 |
|---|---|---|
type 必填 | String | 必须设置为 web_server |
client_id 必填 | String | 客户端ID，注册应用程序时收到。 |
| redirect_uri | String | redirect_uri参数为选填。如果省略，Buddy会将用户重定向到OAuth应用程序设置中配置的回调URI。如果提供，重定向URI的主机和端口必须与回调URI完全匹配。重定向URI的路径必须引用回调URI的子目录。 |
response_type 必填 | String | 必须设置为 code |
scope 必填 | String | 权限范围列表；用 + 字符分隔。 |
| state | String | 一个不可猜测的随机字符串，用于防止跨站点请求伪造攻击。 |
用户将收到一个带有登录表单的网站到您的Buddy工作区。在下一步中，用户可以允许或撤销具有所需范围的应用程序访问权限。
2. 接收验证码
如果用户接受您的应用程序，他将使用两个参数重定向到 redirect_uri (参见上一步)：
| 名称 | 类型 | 描述 |
|---|---|---|
| code | String | 下一步交换访问令牌 |
| state | String | 之前发的状态，必须与原件相同。如果不相同，则应取消身份验证过程。 |
3. 为访问令牌交换验证码
在下一步中，您需要在以下请求中发送code代码：
POST https://api.buddy.works/oauth2/token
Content-Type: application/x-www-form-urlencoded
POST参数
| 名称 | 类型 | 描述 |
|---|---|---|
code 必填 | String | 您在上一步中收到的代码 |
client_id 必填 | String | 客户端ID，注册应用程序时收到。 |
client_secret 必填 | String | 客户端密钥，注册应用程序时收到。 |
| redirect_uri | String | 重要: 如果 redirect_uri 参数包含在授权请求中，则此参数为必填项(如此节中所述)。其值必须相同。 |
grant_type 必填 | String | 必须设置为 authorization_code |
您将收到以下的响应
基本授权
授权主要用于开发人员测试应用程序。只有应用程序开发人员可以进行身份验证。要检索访问令牌，您需要执行以下请求：
POST https://api.buddy.works/oauth2/token
附加此HTTP标头：
'Authorization: Basic ' + base64(client_id + ':' + client_secret)
POST参数
| 名称 | 类型 | 描述 |
|---|---|---|
grant_type 必填 | String | 必须设置为 client_credentials |
scope 必填 | String | 权限范围列表，用空格隔开。 |
身份验证响应
POST https://api.buddy.works/oauth2/token 方法将产生如下响应：
{
"access_token": "732e9e20-50ba-4047-8a7b-c9b17259a2a2",
"expires_in": 28800,
"refresh_token": "p8gUgmrXwe5CT2TMiMMkpIIRlIMlH70aB19dxwGJJkNWp4LthWUjJDmmUmBd7xLPzDq8R5PtCvx0SvAS",
"refresh_token_expires_in": 158112000,
"token_type": "Bearer"
}
| 名称 | 类型 | 描述 |
|---|---|---|
| access_token | String | 用于对API中请求进行身份验证的令牌 |
| expires_in | int | 访问令牌过期的秒数 |
| refresh_token | String | 访问令牌过期后需要刷新 |
| refresh_token_expires_in | int | 刷新令牌过期的秒数 |
| token_type | String | 令牌类型(Buddy目前仅支持bearer) |
刷新令牌
返回的令牌用于在调用API方法时进行身份验证。注：2022年3月29日之前在Buddy中创建的令牌永不过期，在该日期之后生成的令牌在创建后8小时内到期。
如果令牌过期，对 API 的请求将返回以下响应：
401 Unauthorized
{
"errors": [
{
"message": "Wrong authentication data"
}
]
}
在这种情况下，您需要运行此请求来刷新：
POST https://api.buddy.works/oauth2/token
Content-Type: application/x-www-form-urlencoded
POST参数
| 名称 | 类型 | 描述 |
|---|---|---|
| refresh_token | String | 您与前一个令牌一起收到的刷新令牌 |
client_id 必填 | String | 客户端ID，注册应用程序时收到。 |
client_secret 必填 | String | 客户端密钥，注册应用程序时收到。 |
grant_type 必填 | String | 必须设置为 refresh_token |
您将收到以下的响应
- 刷新令牌有效期为6个月。
- 即使令牌尚未过期，也可以刷新令牌。
- 刷新使当前的
access_token和refresh_token无效
支持权限范围
| 名称 | 描述 |
|---|---|
| WORKSPACE | 访问基本工作区信息以及管理成员、群组和成员的权限 |
| PROJECT_DELETE | 删除项目的权限 |
| REPOSITORY_READ | 访问提交和存储仓内容，也允许存储仓分支切换。 |
| REPOSITORY_WRITE | 在存储仓中写入的权限，允许删除文件(包含存储仓读取权限 REPOSITORY_READ)。 |
| EXECUTION_INFO | 访问执行记录 |
| EXECUTION_RUN | 运行和停止执行权限(包含 EXECUTION_INFO 权限) |
| EXECUTION_MANAGE | 添加/编辑流水线权限(包含 EXECUTION_RUN 权限) |
| USER_INFO | 访问授权用户的基本信息 |
| USER_KEY | 访问授权用户的SSH公钥 |
| USER_EMAIL | 访问授权用户的电子邮件列表 |
| INTEGRATION_INFO | 访问授权用户的集成列表 |
| MEMBER_EMAIL | 访问工作区成员的联系信息 |
| MANAGE_EMAILS | 查看和管理用户电子邮件地址的权限(包含 USER_EMAIL 权限) |
| WEBHOOK_INFO | 访问Webhook信息 |
| WEBHOOK_ADD | 获取和添加Webhook权限 |
| WEBHOOK_MANAGE | 添加、编辑和删除Webhook权限 |
| VARIABLE_ADD | 获取和添加环境变量权限 |
| VARIABLE_INFO | 访问环境变量信息 |
| VARIABLE_MANAGE | 添加、编辑和删除环境变量权限 |
| TOKEN_INFO | 访问个人访问令牌信息 |
| TOKEN_MANAGE | 添加和删除个人访问令牌 |