身份验证与授权
Glossia 如何验证用户身份并授权 API 访问权限。
认证方法
Glossia 根据上下文支持两种认证方法。
浏览器会话
当您通过 Web 界面登录时，Glossia 使用基于会话的认证。您通过第三方提供商（GitHub 或 GitLab）进行身份验证，使用 Assent 库。成功登录后，将设置会话 cookie 并用于后续请求。
授权令牌 (OAuth 2.1)
对于 API 访问（例如来自 CLI 或其他工具），Glossia 使用授权码流程和 PKCE 实现 OAuth 2.1。客户端获取授权令牌并将其包含在 Authorization 标题：
Authorization: Bearer <access_token>
OAuth 2.1 流程
1. 动态客户端注册
客户端通过调用 POST /oauth/register 及其元数据。这遵循 RFC 7591.
{
"client_name": "My Tool",
"redirect_uris": ["http://localhost:8080/callback"],
"grant_types": ["authorization_code"]
}
服务器返回 client_id 和 client_secret.
2. 授权请求
客户端将用户重定向到 /oauth/authorize 带有 PKCE 参数：
GET /oauth/authorize?response_type=code&client_id=<id>&redirect_uri=<uri>&code_challenge=<challenge>&code_challenge_method=S256&state=<state>
所有客户端都必须使用 PKCE。 仅 S256 支持挑战方法。
3. 令牌交换
用户批准后，客户端将授权代码交换为令牌 在 POST /oauth/token:
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=<code>&redirect_uri=<uri>&client_id=<id>&code_verifier=<verifier>
响应包括访问令牌和可选的刷新令牌。
4. 令牌刷新
访问令牌过期时，请使用刷新令牌：
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=<token>&client_id=<id>&client_secret=<secret>
作用域
作用域控制令牌可以执行的操作。它们遵循 object:action 模式。
| 范围 | 描述 |
|---|---|
user:read |
查看用户个人资料信息 |
user:write |
更新用户个人资料 |
account:read |
列出您有权访问的组织账户 |
organization:read |
查看组织详情（并列出您的组织） |
organization:write |
创建或更新组织 |
organization:delete |
删除组织 |
organization:admin |
组织管理操作 |
members:read |
读取组织成员和邀请 |
members:write |
管理组织成员和邀请 |
project:read |
读取项目 |
project:write |
创建或更新项目 |
project:admin |
项目管理的操作 |
project:delete |
删除项目 |
voice:read |
读取语音配置 |
voice:write |
创建或更新语音配置 |
voice:admin |
管理语音操作 |
glossary:read |
查看术语条目 |
glossary:write |
创建或更新术语条目 |
glossary:admin |
管理术语设置 |
授权模型
Glossia 强制执行 两层 针对 REST API 和 MCP 服务器：
- 作用域检查: 访问令牌必须包含所需的
object:action作用域。 - 资源级别策略: 当前用户必须对特定资源进行授权，通过
Glossia.Policy。
作用域代表 最大 令牌的能力。策略系统强制执行 实际 特定资源的权限。
角色
| 角色 | 说明 |
|---|---|
self |
访问自己资源的用户 |
organization_member |
资源所属组织的成员 |
organization_admin |
资源所属组织的管理员 |
public_account |
该账户为公开（仅读） |
角色权限
| 范围 | 自身 | 组织成员 | 组织管理员 | 公共账户 |
|---|---|---|---|---|
user:read |
是 | 是 | ||
user:write |
是 | |||
account:read |
是 | 是 | 是 | |
organization:read |
是 | 是 | ||
organization:write |
是 | |||
organization:delete |
是 | |||
organization:admin |
是 | |||
members:read |
是 | 是 | ||
members:write |
是 | |||
project:read |
是 | 是 | 是 | |
project:write |
是 | |||
project:admin |
是 | |||
project:delete |
是 | |||
voice:read |
是 | 是 | 是 | |
voice:write |
是 | |||
voice:admin |
是 | |||
glossary:read |
是 | 是 | ||
glossary:write |
是 | |||
glossary:admin |
是 |
发现端点
Glossia 在标准知名 URL 处发布元数据，以便客户端能够自动发现端点。
OAuth 授权服务器元数据 (RFC 8414)
GET /.well-known/oauth-authorization-server
返回颁发者、端点、支持的作用域、授权类型以及代码挑战方法。
受保护资源元数据 (RFC 9728)
GET /.well-known/oauth-protected-resource
返回资源标识符、授权服务器、支持的作用域以及令牌方法。
限流
OAuth 端点按 IP 地址限制速率：
| 端点 | 限制 |
|---|---|
POST /oauth/register |
每分钟 5 次请求 |
POST /oauth/token |
每分钟 30 次请求 |
POST /oauth/revoke |
每分钟 30 次请求 |
POST /oauth/introspect |
每分钟 30 次请求 |
当受到速率限制时，服务器将返回 HTTP 429（请求过多）。