配置 Simulator 身份验证用于本地测试

Simulator 身份验证提供程序允许你在本地测试基于角色的权限，而无需配置真正的身份提供程序。你可以在开发阶段使用它，先验证权限规则是否正确，再部署到生产环境。

选择本地身份验证提供程序

在开发期间，你可以在不配置生产级身份提供程序的情况下测试身份验证和授权。

提供程序	最适合	说明
Simulator	快速权限测试	仅限开发环境。它会把每个请求都视为已认证。默认使用 `Authenticated` 角色；可通过 `X-MS-API-ROLE` 覆盖。

身份验证流程

Simulator 提供程序会将所有请求视为已认证，从而让你专注于测试授权规则：

展示请求如何被自动视为已认证的 Simulator 身份验证流程示意图。

阶段	发生的事情
请求到达	开发者向数据墙DBW发送 HTTP 请求
角色分配	数据墙DBW 分配 `Authenticated`（默认）或使用 `X-MS-API-ROLE` 标头中的角色
权限检查	数据墙DBW根据该角色在实体上的权限评估请求
执行查询	若被允许，数据墙DBW查询数据库并返回结果

IMPORTANT

Simulator 提供程序仅用于开发。绝不要在生产环境中使用它，因为它会绕过所有真实身份验证。

先决条件

已安装数据墙DBW CLI（请参阅安装指南）
至少包含一个实体的现有 dab-config.json

快速参考

设置	值
Provider	`Simulator`
Host mode	`development`（必需）
默认角色	`Authenticated`（自动注入）
角色覆盖标头	`X-MS-API-ROLE`
是否需要令牌	No
Claims 支持	有限（仅系统角色 `Anonymous` / `Authenticated`；不支持任意自定义 claims）

步骤 1：配置 Simulator 提供程序

将身份验证提供程序设为 Simulator，并确保启用 development 模式。

CLI

Bash

bash

# 启用 development 模式
dab configure \
  --runtime.host.mode development

# 设置 Simulator 提供程序
dab configure \
  --runtime.host.authentication.provider Simulator

Command Prompt

cmd

REM 启用 development 模式
dab configure ^
  --runtime.host.mode development

REM 设置 Simulator 提供程序
dab configure ^
  --runtime.host.authentication.provider Simulator

生成的配置

json

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

NOTE

Simulator 提供程序仅在 mode 设置为 development 时可用。在 production 模式下，数据墙DBW会拒绝该提供程序并启动失败。

步骤 2：配置实体权限

为你想测试的角色定义权限。你可以测试系统角色（Anonymous、Authenticated）和自定义角色。

示例：多个角色

Bash

bash

# 允许 anonymous 读取
dab update Book \
  --permissions "Anonymous:read"

# 允许 authenticated 完整读取
dab update Book \
  --permissions "Authenticated:read"

# 允许 author 创建和更新
dab update Book \
  --permissions "author:create,read,update"

# 允许 admin 完全访问
dab update Book \
  --permissions "admin:*"

Command Prompt

cmd

REM 允许 anonymous 读取
dab update Book ^
  --permissions "Anonymous:read"

REM 允许 authenticated 完整读取
dab update Book ^
  --permissions "Authenticated:read"

REM 允许 author 创建和更新
dab update Book ^
  --permissions "author:create,read,update"

REM 允许 admin 完全访问
dab update Book ^
  --permissions "admin:*"

生成的配置

json

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Anonymous",
          "actions": ["read"]
        },
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "author",
          "actions": ["create", "read", "update"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

步骤 3：测试不同角色

启动数据墙DBW并发送请求来测试不同角色。

bash

dab start

以 authenticated 身份测试（默认）

在不提供任何特殊标头的情况下，请求会按 Authenticated 角色进行评估：

bash

curl -X GET "http://localhost:5000/api/Book"

以 anonymous 身份测试

使用 X-MS-API-ROLE 标头测试 Anonymous：

bash

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

以自定义角色测试

使用 X-MS-API-ROLE 标头测试任意自定义角色：

bash

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

NOTE

在 Simulator 模式下，自定义角色测试之所以可行，是因为数据墙DBW会根据 X-MS-API-ROLE 标头值来评估权限。系统角色（Anonymous、Authenticated）始终可用。如果某个自定义角色请求返回 403，请检查角色名是否与你在实体权限中定义的完全一致。

测试一个应被拒绝的操作

尝试执行某个该角色无权执行的操作：

bash

# 这里应失败——Anonymous 只能读取
curl -X POST "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: Anonymous" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Book", "author": "Test"}'

预期响应：403 Forbidden

测试场景

你可以使用 Simulator 测试以下常见场景：

场景	测试方式
Anonymous 访问	设置 `X-MS-API-ROLE: Anonymous`
Authenticated 访问	不带标头（默认）或设置 `X-MS-API-ROLE: Authenticated`
自定义角色访问	设置 `X-MS-API-ROLE: <role-name>`
被拒绝的动作	请求某个该角色没有权限的动作
字段限制	配置字段级权限并验证响应字段
缺失角色	设置 `X-MS-API-ROLE: nonexistent` 测试错误处理

限制

Simulator 提供程序有以下限制：

限制	解决方式
不支持自定义 claims	使用自定义 JWT 提供程序测试 claims
无法测试依赖 claims 的数据库策略	使用自定义 JWT 提供程序测试策略
不做令牌验证	生产环境请切换到 `Custom`
仅支持 development 模式	生产环境使用真实提供程序

迁移到生产环境

当你准备部署时，请将 Simulator 提供程序替换为生产级提供程序：

将 mode 从 development 改为 production
将 provider 从 Simulator 改为你选定的生产提供程序（例如 Custom）
配置所需的 JWT 设置（audience、issuer）

json

{
  "runtime": {
    "host": {
      "mode": "production",
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "api://<your-app-id>",
          "issuer": "https://identity.example.com/"
        }
      }
    }
  }
}

完整配置示例

json

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/数据墙DBW.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=localhost;Database=Library;Trusted_Connection=true;TrustServerCertificate=true;"
  },
  "runtime": {
    "host": {
      "mode": "development",
      "authentication": {
        "provider": "Simulator"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Anonymous",
          "actions": ["read"]
        },
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "author",
          "actions": ["create", "read", "update"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

配置 Simulator 身份验证用于本地测试 ​

选择本地身份验证提供程序 ​

身份验证流程 ​

先决条件 ​

快速参考 ​

步骤 1：配置 Simulator 提供程序 ​

CLI ​

Bash ​

Command Prompt ​

生成的配置 ​

步骤 2：配置实体权限 ​

示例：多个角色 ​

Bash ​

Command Prompt ​

生成的配置 ​

步骤 3：测试不同角色 ​

以 authenticated 身份测试（默认） ​

以 anonymous 身份测试 ​

以自定义角色测试 ​

测试一个应被拒绝的操作 ​

测试场景 ​

限制 ​

迁移到生产环境 ​

完整配置示例 ​

相关内容 ​

配置 Simulator 身份验证用于本地测试

选择本地身份验证提供程序

身份验证流程

先决条件

快速参考

步骤 1：配置 Simulator 提供程序

CLI

Bash

Command Prompt

生成的配置

步骤 2：配置实体权限

示例：多个角色

Bash

Command Prompt

生成的配置

步骤 3：测试不同角色

以 authenticated 身份测试（默认）

以 anonymous 身份测试

以自定义角色测试

测试一个应被拒绝的操作

测试场景

限制

迁移到生产环境

完整配置示例

相关内容