For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/core-concepts/identity-and-permissions.md.

用户身份与权限模型

提示

本文档面向在豆包中提供业务工具能力的开发者,主要说明三个核心问题:平台如何识别应用、应用如何识别当前用户,以及受保护能力在满足用户授权条件后如何使用

本文主要介绍:

  • 核心概念:AppID、OpenID、业务账号、业务会话与应用身份凭证
  • 用户身份模型:获取 login_code、换取 OpenID、绑定业务账号并建立业务会话
  • 权限使用模型:能力开通、权限声明、用户索权、系统权限与异常处理
  • 开发者检查清单:环境隔离、密钥管理、账号绑定、会话管理与最小权限
  • 相关文档:应用配置、登录指南及相关 API

核心概念

提示

一句话理解:

  • AppID 标识“这是哪个应用”
  • OpenID 标识“这是该应用下的哪个用户”
  • 业务账号 则用于判断“这个用户在业务里是谁”
  • 业务会话 判断“当前请求是否处于有效登录状态”
概念含义使用边界
AppID应用插件在平台上的应用标识,也是用户身份与权限数据的应用级命名空间。用于标识“哪个应用”发起请求,不能代替用户身份。
OpenID用户在当前 AppID 下的稳定标识。同一用户在不同 AppID 下的 OpenID 不同,不应直接用于跨应用识别用户。
业务账号开发者自身账号体系中的用户,例如会员、员工或客户账号。由开发者建立 OpenID 与业务账号的绑定关系,并自行维护账号生命周期。
业务会话开发者服务端签发并校验的登录态。由开发者决定有效期、续期、退出和风控策略;平台不会替应用维护第三方业务登录态。
应用身份凭证如 AppSecret、应用级访问凭证,用于证明服务端代表某个应用调用平台能力。只应保存在服务端。它们证明的是应用身份,不代表某个用户,也不等同于用户授权。

用户身份模型

  • 豆包应用插件获取登录凭证:调用 doubao.login(),获得一次性、短时有效的 login_code
  • 服务端换取平台用户标识:将 login_code 发送给开发者服务端;服务端调用平台接口,换取当前应用下的 OpenID
  • 关联业务账号:服务端业务规则自行查找、创建或绑定业务账号,是否需要手机号由业务场景自行决定
  • 建立业务会话:服务端向应用插件签发自己的会话凭证,后续业务接口根据该凭证识别登录状态与业务权限

代码示例:如何建立业务登录态

login() 返回一次性 login_code:前端应立即把它提交给自己的服务端,并用服务端返回的业务会话访问后续业务接口。

import { login, request } from '@doubao-dev/framework/api';

type SessionResponse = {
  sessionToken: string;
  user: {
    id: string;
    displayName: string;
  };
};

export async function signIn(): Promise<SessionResponse> {
  // code 有效期为 5 分钟,且只能兑换一次
  const { code } = await login({ timeout: 30_000 });

  const result = await request({
    url: 'https://api.example.com/session',
    method: 'POST',
    dataType: 'json',
    header: { 'content-type': 'application/json' },
    data: { loginCode: code }
  });

  if (result.statusCode !== 200 || !result.data) {
    throw new Error('建立业务会话失败');
  }

  return result.data as SessionResponse;
}

逻辑边界:平台用户身份与业务账号可以一对一,也可以按业务规则建立其他绑定关系

权限使用模型

受保护能力能否使用,通常由以下几层共同决定:

层次解决的问题开发者职责
能力开通当前应用是否具备使用某项平台能力的资格。按平台要求申请或开通相应能力。
权限声明应用是否事先声明将使用某个权限范围,以及使用目的。在应用配置中声明 scope,并提供准确、具体、与场景一致的用途说明。
用户索权当前用户是否同意该应用访问相应数据或设备能力。在真实使用场景中发起授权,处理同意、拒绝和后续变更。
系统权限手机操作系统是否允许豆包访问相应设备能力,例如定位、相机或麦克风。当能力涉及系统权限时,识别系统授权状态,并为用户提供清晰的开启指引。

备注:声明先于调用,需要先在开放平台为应用开通并声明相应权限,填写与场景一致的用途,构建工具会把平台返回的权限信息写入应用清单,不要手工修改构建产物

权限声明与用户授权的关系

  • 声明不等于授权:配置中声明 scope,只表示应用说明了使用意图;是否授权仍由用户决定。
  • 用户授权不等于系统权限:用户在应用插件内同意后,涉及设备能力时仍可能受手机系统设置限制。
  • 系统权限不等于应用插件授权:即使系统已允许豆包访问设备能力,当前应用插件仍需满足自身的声明与用户授权要求

典型状态与处理方式

状态建议处理
未声明所需 scope补充应用配置并重新发布;不要仅通过重复调用 API 规避声明要求。
尚未向用户索权在真实功能场景中说明用途并发起授权。
用户已拒绝明确告知功能影响,提供可选的重新授权入口,同时保留不依赖该权限的体验。
应用插件已授权,但系统权限关闭提示用户前往手机系统设置开启相应权限。
权限已具备,但业务操作被拒绝检查业务账号、角色、资源归属与服务端鉴权逻辑。

代码示例:查询、申请与使用权限

以下示例以定位为例,区分“从未索权”“已经拒绝”“已经授权”三种状态,并在用户明确使用相关功能时再发起请求。

import {
  authorize,
  getLocation,
  getSetting
} from '@doubao-dev/framework/api';

const LOCATION_SCOPE = 'scope.userLocation' as const;

export async function getCurrentLocationWithConsent() {
  const { authSetting } = await getSetting();
  const decision = authSetting[LOCATION_SCOPE];

  if (decision !== true) {
    // authSetting 中没有该 scope:此前尚未请求过
    try {
      await authorize({ scope: LOCATION_SCOPE });
    } catch {
      // 用户拒绝或授权过程失败,保留不依赖定位的体验
      return null;
    }
  }

  try {
    return await getLocation();
  } catch (error) {
    // 应用插件授权通过后,系统定位权限或定位服务仍可能不可用
    console.error('定位能力不可用,请检查系统设置', error);
    throw error;
  }
}

开发者检查清单

  • 确认生产、测试等不同环境使用的 AppID,避免混用身份数据与配置。

  • AppSecret 和应用级访问凭证仅保存在服务端,并具备轮换与泄露处置机制。

  • 服务端完成 login_code 兑换,不在客户端存放或使用 AppSecret。

  • 明确 OpenID 与业务账号的绑定、解绑、合并和异常恢复规则。

  • 业务会话具备合理的有效期、续期、退出、吊销和风控策略。

  • 仅声明业务实际需要的 scope,用途说明与真实功能一致。

  • 仅在需要时发起索权,并完整处理同意、拒绝、撤销与系统权限关闭等状态。

相关文档