# 身份与 SSO

Acahti 依据实例的用户目录对人和 Agent 进行认证。登录成功只表明识别出了一个账号；能否访问仓库、组织、团队和其他服务，仍取决于它们各自的授权规则。

## MCP 客户端的 OAuth

通过实例的 `/.well-known/oauth-authorization-server` 元数据找到授权、令牌和注册端点。MCP 客户端注册自己的回调地址，使用带 PKCE S256 的授权码流程，返回时校验自己的 `state`，再用 verifier 兑换一次性授权码。需要认证的 MCP 资源是 `<instance>/mcp`。

令牌请求要带上已注册的 `client_id`，刷新请求也要带同一个 ID。重定向地址必须与已注册的 URI 一致；本机回环（loopback）客户端可以换用不同端口，但协议、主机、路径和查询参数必须与注册时相同。PKCE verifier 由 43–128 个非保留字符组成。

授权码五分钟后过期，且只能兑换一次。服务器目前签发的访问令牌有效期为 90 天，刷新令牌为 400 天；请以令牌响应中的 `expires_in` 为准，并把两种令牌都当作凭据妥善保护。第一方 Web 应用使用服务器配置的客户端标识和精确的回调 URL。通过 `/oauth/register` 注册只面向 MCP 客户端，不会创建第一方 Web 应用。

OAuth 访问令牌代表账号本身的权限。当前的 `mcp` scope 并不是细粒度的权限授予。不要把这些令牌发给其他服务，也不要假定每个任务的 scope 相互隔离。

令牌端点接受 `authorization_code` 和 `refresh_token` 两种授权类型。服务器把已注册的客户端、未兑换的授权码和刷新令牌保存在网关数据目录中；访问令牌经签名后直接验证，不保存记录。

## Shell Agent

每位成员从头像菜单中创建自己的个人「访问令牌」。在 Benchyard 中，把 `ACAHTI_ROOT_URL` 和 `ACAHTI_TOKEN` 设置在「密钥」里，并限定到实例主机。直接使用环境变量即可；绑定主机的占位值不得打印、复制到文件或转发给其他主机。参见 [Agent 访问](/docs/agents/)和 [CLI](/docs/cli/)。

## 第一方服务

Phaevo 使用配置好的回调地址，以及一个单独的、有效期 90 秒的签名身份断言。该断言绑定到一个 challenge 和设备密钥，在实时核验团队成员身份后，由 `POST /acahti/v1/phaevo/ticket` 签发。Phaevo 的控制平面会验证该断言，并应用它自己的环境授权。仅配置 SSO 并不会授予网络访问权限。签发方和网关的配置请参阅 Phaevo 的访问文档。

账号和团队成员关系的变更必须在 Acahti 中进行。OAuth 客户端配置、签发方密钥、会话密钥和刷新令牌都应当作凭据加以保护。升级前请按照[工作原理](/docs/how-it-works/)中的说明备份 Acahti 数据目录。