用户身份与权限模型
提示
本文档面向在豆包中提供业务工具能力的开发者,主要说明三个核心问题:平台如何识别应用、应用如何识别当前用户,以及受保护能力在满足用户授权条件后如何使用
本文主要介绍:
- 核心概念:AppID、OpenID、业务账号、业务会话与应用身份凭证
- 用户身份模型:获取 login_code、换取 OpenID、绑定业务账号并建立业务会话
- 权限使用模型:能力开通、权限声明、用户索权、系统权限与异常处理
- 开发者检查清单:环境隔离、密钥管理、账号绑定、会话管理与最小权限
- 相关文档:应用配置、登录指南及相关 API
核心概念
提示
一句话理解:
- AppID 标识“这是哪个应用”
- OpenID 标识“这是该应用下的哪个用户”
- 业务账号 则用于判断“这个用户在业务里是谁”
- 业务会话 判断“当前请求是否处于有效登录状态”
用户身份模型
- 豆包应用插件获取登录凭证:调用
doubao.login(),获得一次性、短时有效的login_code - 服务端换取平台用户标识:将
login_code发送给开发者服务端;服务端调用平台接口,换取当前应用下的 OpenID - 关联业务账号:服务端业务规则自行查找、创建或绑定业务账号,是否需要手机号由业务场景自行决定
- 建立业务会话:服务端向应用插件签发自己的会话凭证,后续业务接口根据该凭证识别登录状态与业务权限
代码示例:如何建立业务登录态
login() 返回一次性 login_code:前端应立即把它提交给自己的服务端,并用服务端返回的业务会话访问后续业务接口。
逻辑边界:平台用户身份与业务账号可以一对一,也可以按业务规则建立其他绑定关系
权限使用模型
受保护能力能否使用,通常由以下几层共同决定:
备注:声明先于调用,需要先在开放平台为应用开通并声明相应权限,填写与场景一致的用途,构建工具会把平台返回的权限信息写入应用清单,不要手工修改构建产物
权限声明与用户授权的关系
- 声明不等于授权:配置中声明 scope,只表示应用说明了使用意图;是否授权仍由用户决定。
- 用户授权不等于系统权限:用户在应用插件内同意后,涉及设备能力时仍可能受手机系统设置限制。
- 系统权限不等于应用插件授权:即使系统已允许豆包访问设备能力,当前应用插件仍需满足自身的声明与用户授权要求
典型状态与处理方式
代码示例:查询、申请与使用权限
以下示例以定位为例,区分“从未索权”“已经拒绝”“已经授权”三种状态,并在用户明确使用相关功能时再发起请求。
开发者检查清单
-
确认生产、测试等不同环境使用的 AppID,避免混用身份数据与配置。
-
AppSecret 和应用级访问凭证仅保存在服务端,并具备轮换与泄露处置机制。
-
服务端完成 login_code 兑换,不在客户端存放或使用 AppSecret。
-
明确 OpenID 与业务账号的绑定、解绑、合并和异常恢复规则。
-
业务会话具备合理的有效期、续期、退出、吊销和风控策略。
-
仅声明业务实际需要的 scope,用途说明与真实功能一致。
-
仅在需要时发起索权,并完整处理同意、拒绝、撤销与系统权限关闭等状态。