本地身份模拟

Simulator 提供程序让开发者在本地跳过所有真实身份验证，专注于测试权限配置。所有请求自动视为已认证，并可以通过请求头模拟任意角色。

DANGER

Simulator 仅用于开发环境。绝不要在生产环境中使用——它会绕过所有身份验证，且强制要求 host.mode: development，生产模式下启动会直接失败。

配置

dab configure --runtime.host.mode development
dab configure --runtime.host.authentication.provider Simulator

生成的配置：

{
  "runtime": {
    "host": {
      "mode": "development",
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

NOTE

Simulator 仅在 mode: development 下可用。如果误设为 production 模式，引擎启动时会拒绝并报错。

行为原理

Simulator 模式下引擎对每个请求的处理逻辑：

请求到达
  ├── 不验证任何 Token（即使携带也忽略）
  ├── 读取 X-MS-API-ROLE 请求头
  │     ├── 头存在 → 使用指定的角色
  │     └── 头不存在 → 默认使用 Authenticated 角色
  └── 按该角色在实体上的 permissions 评估权限

测试不同角色

默认角色（Authenticated）

不传任何头，请求按 Authenticated 评估：

curl http://localhost:5000/api/Book

匿名角色

通过 X-MS-API-ROLE: Anonymous 模拟匿名用户：

curl http://localhost:5000/api/Book \
  -H "X-MS-API-ROLE: Anonymous"

自定义角色

模拟任意自定义角色（如 editor、admin）：

# 模拟 editor 角色
curl http://localhost:5000/api/Book \
  -H "X-MS-API-ROLE: editor"

# 模拟 admin 角色
curl http://localhost:5000/api/Book \
  -H "X-MS-API-ROLE: admin"

角色名大小写敏感，必须与实体 permissions 中配置的角色名完全一致。如果指定了一个未在 permissions 中配置的角色，请求会按 403 处理。

验证权限拒绝

测试某个角色不该有的操作：

# anonymous 角色尝试创建（应返回 403）
curl -X POST http://localhost:5000/api/Book \
  -H "X-MS-API-ROLE: Anonymous" \
  -H "Content-Type: application/json" \
  -d '{"id": 999, "title": "测试"}'

测试场景清单

场景	操作
匿名用户能否读取	X-MS-API-ROLE: Anonymous + GET
认证用户能否创建	不带头（默认 Authenticated）+ POST
特定角色能否更新	指定角色 + PATCH
字段排除是否生效	检查响应中是否不包含 fields.exclude 的列
未授权操作是否正确拒绝	尝试越权操作，期望 403
未配置角色是否被拒绝	X-MS-API-ROLE: nonexistent，期望 403

完整示例配置

{
  "runtime": {
    "host": {
      "mode": "development",
      "authentication": {
        "provider": "Simulator"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        { "role": "Anonymous",     "actions": ["read"] },
        { "role": "Authenticated", "actions": ["read", "create"] },
        { "role": "editor",        "actions": ["read", "create", "update"] },
        { "role": "admin",         "actions": ["*"] }
      ]
    }
  }
}

限制

限制	影响	替代方案
不能模拟真实 claims	无法测试依赖 @claims.userId 的数据库策略	切换到 Custom 模式用真实 JWT 测试
不做令牌验证	无法测试令牌过期、签名错误等场景	用 Custom 模式配合测试令牌
仅 development 模式	不能在生产环境留用	部署前必须改回正式 Provider
不支持 claims 自定义	X-MS-API-ROLE 只能指定角色，不能注入任意声明	—

迁移到生产环境

权限测试完成后，切换到生产认证方式：

# 1. 切换模式
dab configure --runtime.host.mode production

# 2. 切换到正式 Provider
dab configure --runtime.host.authentication.provider Custom

# 3. 配置 JWT 参数
dab configure --runtime.host.authentication.jwt.issuer "https://idp.example.com/"
dab configure --runtime.host.authentication.jwt.audience "api://dab-api"

推荐工作流：先用 Simulator 验证所有权限规则设计和字段过滤逻辑正常，确认无误后再接入真实身份提供程序。

下一步

• JWT 身份验证 — 切换到生产环境认证。
• 授权概述 — 配置角色和操作权限。