为本地测试配置模拟器身份验证

模拟器身份验证提供程序允许在本地测试基于角色的权限，而无需配置标识提供者。 在开发过程中使用它来验证权限规则在部署到生产环境之前是否正常工作。

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

在开发过程中，无需配置生产标识提供者即可测试身份验证和授权。

Provider	最适用于	注释
模拟器	快速权限测试	仅限开发。 将每个请求视为经过身份验证。 默认为 Authenticated 角色，覆盖为 X-MS-API-ROLE。
AppService	断言驱动测试	在本地模拟 EasyAuth，方法是使用 X-MS-CLIENT-PRINCIPAL 发送自定义声明。 有关详细信息，请参阅 “配置应用服务身份验证”。

身份验证流

模拟器提供程序将所有请求视为经过身份验证，让你专注于测试授权规则：

阶段	发生的情况
请求到达	开发人员将 HTTP 请求发送到 DAB
角色分配	DAB 会分配Authenticated（默认情况）或从X-MS-API-ROLE标头获取角色。
检查权限	DAB 根据实体在该角色上的权限评估请求。
查询执行	如果允许，DAB 会查询数据库并返回结果

重要

模拟器提供程序 仅用于开发。 切勿在生产环境中使用它， 它绕过所有真正的身份验证。

先决条件

• 已安装的数据 API 生成器 CLI （安装指南）
• 具有至少一个实体的现有 dab-config.json 实体

快速参考

设置	价值
Provider	Simulator
主机模式	development（必需）
默认角色	Authenticated （自动注入）
角色替代标头	X-MS-API-ROLE
需要令牌	否
索赔支持	受限（仅限系统角色 Anonymous/Authenticated ;无任意声明）

步骤 1：配置模拟器提供程序

将身份验证提供程序设置为模拟器并确保启用开发模式。

CLI

Bash

# Enable development mode
dab configure \
  --runtime.host.mode development

# Set the Simulator provider
dab configure \
  --runtime.host.authentication.provider Simulator

命令提示符

REM Enable development mode
dab configure ^
  --runtime.host.mode development

REM Set the Simulator provider
dab configure ^
  --runtime.host.authentication.provider Simulator

生成的配置

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

注释

模拟器提供程序仅在 mode 设置为 development 时工作。 在生产模式下，DAB 拒绝模拟器提供程序，无法启动。

步骤 2：配置实体权限

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

示例：多个角色

Bash

# Allow anonymous read access
dab update Book \
  --permissions "Anonymous:read"

# Allow authenticated users full read access
dab update Book \
  --permissions "Authenticated:read"

# Allow authors to create and update
dab update Book \
  --permissions "author:create,read,update"

# Allow admins full access
dab update Book \
  --permissions "admin:*"

命令提示符

REM Allow anonymous read access
dab update Book ^
  --permissions "Anonymous:read"

REM Allow authenticated users full read access
dab update Book ^
  --permissions "Authenticated:read"

REM Allow authors to create and update
dab update Book ^
  --permissions "author:create,read,update"

REM Allow admins full access
dab update Book ^
  --permissions "admin:*"

生成的配置

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

步骤 3：测试不同的角色

启动数据 API 生成器并发送用于测试每个角色的请求。

dab start

作为已验证用户进行测试（默认）

如果没有任何特殊标头，请求将被视为 Authenticated 角色处理：

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

以匿名身份测试

使用 X-MS-API-ROLE 标头来测试为 Anonymous:

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

作为自定义角色进行测试

请使用 X-MS-API-ROLE 头文件来测试任何自定义角色：

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

注释

使用模拟器时，自定义角色测试能够运行，因为 DAB 基于 X-MS-API-ROLE 标头值来评估权限。 系统角色 （Anonymous， Authenticated） 始终可用。 如果自定义角色请求返回 403，请验证角色名称是否与实体权限完全匹配。

测试被拒绝的操作

尝试执行角色没有权限的操作：

# This should fail—Anonymous can only read
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

测试方案

使用模拟器测试以下常见方案：

Scenario	如何测试
匿名访问	设置 X-MS-API-ROLE: Anonymous
经过身份验证的访问	省略标头（默认值）或设置 X-MS-API-ROLE: Authenticated
自定义角色访问	设置 X-MS-API-ROLE: <role-name>
拒绝的操作	请求执行角色无权进行的操作
字段限制	配置字段级权限并验证响应字段
缺少角色	设置为 X-MS-API-ROLE: nonexistent 测试错误处理

局限性

模拟器提供程序具有以下限制：

限度	解决方法
无自定义声明	将 AppService 提供程序与标头配合使用X-MS-CLIENT-PRINCIPAL
没有包含声明的数据库策略	使用 AppService 提供者测试对策
无令牌验证	在生产环境中切换到 Entra 或自定义提供程序
仅限开发模式	在生产环境中使用真实供应商

小窍门

如果需要测试使用声明的数据库策略（例如 @claims.userId），请改用 AppService 提供程序 。 它允许通过 X-MS-CLIENT-PRINCIPAL 标头提供自定义声明。

过渡到生产

准备好部署时，请将模拟器提供程序替换为生产提供程序：

1. 将mode从development更改为production
2. 将 provider 从 Simulator 更改为您选择的提供商（EntraID/AzureAD、AppService 或 Custom）
3. 配置所需的 JWT 设置（受众、颁发者）

{
  "runtime": {
    "host": {
      "mode": "production",
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://<your-app-id>",
          "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0"
        }
      }
    }
  }
}

完整配置示例

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.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": ["*"]
        }
      ]
    }
  }
}

相关内容

• 授权和角色
• 配置应用服务身份验证
• 配置 Microsoft Entra ID 身份验证
• 运行时配置参考