> 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.

# 用户身份与权限模型

:::info 提示

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

<div hidden data-lark-callout-end></div>

:::

本文主要介绍：

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

## 核心概念

:::info 提示

**一句话理解：**

- **AppID** 标识“这是哪个应用”
- **OpenID** 标识“这是该应用下的哪个用户”
- **业务账号** 则用于判断“这个用户在业务里是谁”
- **业务会话** 判断“当前请求是否处于有效登录状态”

<div hidden data-lark-callout-end></div>

:::

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

## 用户身份模型

```mermaid
flowchart LR
  A[应用插件] -- "doubao.login()" --> B[login_code]
  B -- "发送到开发者服务端" --> C[用 AppID 和 AppSecret 换取 OpenID]
  C --> D[关联业务账号]
  D --> E[签发业务会话]
```

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

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

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

```typescript
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;
}
```

**逻辑边界：**&#x5E73;台用户身份与业务账号可以一对一，也可以按业务规则建立其他绑定关系

## 权限使用模型

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

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

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

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

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

### 典型状态与处理方式

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

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

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

```typescript
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，用途说明与真实功能一致。

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

## 相关文档

- [应用配置](/apps-plugin/docs/client-framework/overview.md)
- [登录 API](/apps-plugin/docs/server-api/login.md)
