个人 Agent 接入:身份、会话与账号能力
个人 Agent 接入:身份、会话与账号能力
企业接入向导回答"企业要提供什么";本页回答个人 Agent 开发者要准备什么。两者合起来才是完整链路;字段与算法以1.0 规范源文件为准。
你要发布什么
- 客户端元数据与公钥:个人 Agent 通过 HTTPS 提供自己的元数据与公钥,供企业校验你的请求身份。
- 每企业独立的 User ID:每个用户在每家企业使用独立、稳定、不含个人信息的 User ID。不要直接使用邮箱或邮箱散列——它跨企业可关联。
发现与身份
请求企业发现文档时先安全获取(HTTPS、固定来源),再做双向校验:企业元数据与 issuer 元数据相互印证,确认你面对的确实是该企业。校验细节见发现文档与企业身份校验。
会话是你的身份线
正式 1.0 把会话与账号分开。Session 由你标识:
- 为每个会话生成随机会话 ID;
- 每个请求都用委托密钥新签一个会话 JWT(声明会话 ID、用户 ID、请求方法与地址),放在
Poppy-Session头中,并携带Poppy-Version; - 会话 JWT 是每请求一次的证明,不复用旧签名。
未登录的会话请求同样是合法请求;会话与账号登录是两条独立的线。
账号能力按需接入
只有当任务确实需要账号能力时才引导用户登录:
- 登录走 Direct Sign-In(授权码 + PKCE);issuer 元数据需支持
ES256与PS384、refresh_token授权与撤销端点。 - 安全保存 refresh token,按需换取 access token;刷新时必须使用取得该 refresh token 的同一 DPoP 密钥。
- 撤销语义有三种且互不替代(refresh token 撤销、会话停用、账号登出),排障见身份与授权。
验证顺序
| 阶段 | 成功依据 |
|---|---|
| 发现 | 域名与 issuer 双向校验通过 |
| 开始会话 | 自签会话 JWT 被企业接受;被拒时收到明确的 invalid_session |
| 登录 | Direct Sign-In 完成,用户批准的 scope 与令牌内容对应 |
| 执行 | 一个带 access token 的只读请求返回预期结果 |
| 撤销 | 撤销 refresh token 后无法再换取 access token;会话请求以未登录方式继续 |
先用只读任务走通全链,再扩展写操作。失败处理与重试边界见凭据、撤销与安全重试。
边界
- 本站未运行任何真实登录、拒绝或撤销流程;上述顺序是静态核对官方 1.0 后的组织建议,不是实测结论。
- 官方
kit/company的 Validator 可做发现文档静态校验;通过静态校验不等于登录、会话或撤销可用。
最后更新于