共用方式為

配置模擬器驗證以進行本地測試

模擬器認證提供者讓你可以在本地測試基於角色的權限，而無需設定身份提供者。 在開發過程中用它來驗證你的權限規則是否正確運作，然後再部署到生產環境。

選擇本地認證提供者

在開發過程中，你可以在不設定生產身份提供者的情況下測試認證與授權。

Provider 適用對象 註釋
模擬器 快速權限測試 僅供開發用途 每個請求都視為已驗證。 預設為角色 Authenticated，可用 X-MS-API-ROLE 覆蓋。
AppService 以主張為導向的測試 透過隨同自訂宣告發送 X-MS-CLIENT-PRINCIPAL ，在本地模擬 EasyAuth。 詳情請參見 「配置 App Service 認證」。

驗證流程

模擬器提供者將所有請求視為已認證，讓您專注於測試授權規則：

模擬器驗證流程的示意圖，展示請求如何自動被視為認證。

Phase 會發生什麼事
請求來了 開發者向 DAB 發送 HTTP 請求
角色指派 DAB 會指派Authenticated（預設角色）或從X-MS-API-ROLE 標頭裡指定角色
權限檢查 DAB 會根據該實體對該角色的權限進行評估請求
查詢執行 若允許，DAB 會查詢資料庫並回傳結果

這很重要

模擬器提供者 僅供開發使用。 千萬不要在生產環境中使用它——這會繞過所有真正的驗證。

先決條件

  • Data API 建構器 CLI 已安裝（安裝指南）
  • 現有的dab-config.json至少擁有一個實體

快速參考

Setting 價值觀
Provider Simulator
主機模式 development (必要)
預設角色 Authenticated （自動注射）
角色覆寫標頭 X-MS-API-ROLE
需要代幣 否
理賠支持 有限（僅限系統角色 Anonymous/Authenticated ;禁止任意主張）

步驟 1：設定模擬器提供者

將認證提供者設為模擬器，並確保開發模式已啟用。

CLI

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

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

所產生的設定

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

備註

模擬器提供者只有在 mode 設定為 development時才會運作。 在生產模式下，DAB 會拒絕模擬器提供者並無法啟動。

步驟 2：設定實體權限

為你想測試的角色定義權限。 你可以測試系統角色（Anonymous、） Authenticated和自訂角色。

範例：多重角色

# 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:*"

所產生的設定

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

步驟三：測試不同角色

啟動 Data 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"

備註

使用 Simulator 時，自訂角色測試可行，因為 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 為測試錯誤處理

局限性

模擬器供應商有以下限制：

限度 因應措施
無自定義聲明 使用帶有 X-MS-CLIENT-PRINCIPAL 標頭的 AppService 提供者
沒有帶有理賠的資料庫保單 使用 AppService 提供者測試策略
沒有標記驗證 切換到 Entra 或 Custom Provider 來製作
僅限開發模式 在生產環境中使用真實的供應商

小提示

如果你需要測試使用聲明的資料庫規則（例如 @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": ["*"]
        }
      ]
    }
  }
}

相關內容

  • Last updated on