共用方式為

設定自訂 JWT 認證（Okta、Auth0）

Data API 建構器透過自訂認證提供者支援第三方身份提供者。 當您的組織使用 Okta、Auth0 或其他符合 OAuth 2.0/OpenID Connect 標準的身份提供者時，請使用此方法。

驗證流程

有了自訂的身份提供者，您的客戶端應用程式會處理使用者認證，然後將存取權杖傳送給資料 API 建構器：

第三方身份提供者自訂 JWT 認證流程的示意圖。

Phase 會發生什麼事
使用者認證 使用者透過身份提供者（Okta、Auth0 等）登入
代幣取得 用戶端應用程式會從 IdP 收到存取權杖
API 呼叫 用戶端在標頭中將憑證傳送給 DAB Authorization
Validation DAB 驗證 JWT（發行人、受眾、簽名）
授權 DAB 會擷取角色並評估權限

先決條件

  • 一個與你的身份提供者（Okta、Auth0 等）共用的帳號。
  • 在您的身份提供者中註冊的應用程式
  • Data API 建構器 CLI 已安裝（安裝指南）
  • 現有的dab-config.json至少擁有一個實體

快速參考

Setting 價值觀
Provider Custom
驗證所需 iss， aud， exp， 有效簽章
授權所需條件 roles 包含所選角色的聲明
標記標頭 Authorization: Bearer <token>
角色聲明類型 roles （已修正，無法設定）
角色選擇標頭 X-MS-API-ROLE

步驟 1：設定您的身份提供者

具體步驟取決於你的醫療提供者。 以下是您需要的關鍵價值：

需收集的數值

價值觀 所在位置 用於
簽發者 URL 提供者文件或 OAuth 元資料端點 DAB jwt.issuer （用作 JWT 權威）
觀眾 你的應用程式的客戶端 ID 或自訂的 API 識別碼 DAB jwt.audience

備註

DAB 使用配置的 jwt.issuer 作為 JWT 授權伺服器。 簽署金鑰會透過標準 OpenID Connect 的元資料（通常是 <issuer>/.well-known/openid-configuration）自動發現。

Okta 範例

  1. 登入 Okta 管理控制台。
  2. 前往應用程式>應用程式。
  3. 建立或選擇應用程式。
  4. 請注意客戶 端 ID （作為受眾使用）。
  5. 你的發卡機構通常是 https://<your-domain>.okta.com。

Auth0 範例

  1. 登入 Auth0 儀表板。
  2. 前往 應用程式>API。
  3. 建立或選擇一個 API。
  4. 請注意識別碼（用於目標受眾）。
  5. 您的發卡人是 https://<your-tenant>.auth0.com/。

這很重要

資料 API 建構器使用固定的權利要求類型 roles 來進行基於角色的授權。 這個數值無法被設定。 如果您的身份提供者在不同的宣告中發出角色（例如 groups 或 permissions），您必須設定提供者同時發出 roles 宣告，或者使用登入後的操作將數值複製到 roles 宣告中。

步驟 2：設定資料 API 建構器

將認證提供者設定為 Custom，並配置 JWT 設定：

CLI

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

# Set the expected audience
dab configure \
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

# Set the expected issuer
dab configure \
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

所產生的設定

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "<your-api-identifier>",
          "issuer": "https://<your-issuer>/"
        }
      }
    }
  }
}

步驟 3：設定實體權限

定義身份提供者指派的角色權限：

CLI

# Allow authenticated users to read
dab update Book \
  --permissions "authenticated:read"

# Allow users with 'admin' role full access
dab update Book \
  --permissions "admin:*"

所產生的設定

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

步驟 4：在你的身份提供者中設定角色

DAB 期望在申請 roles 中擔任角色。 請設定您的身份提供者以包含此聲明。

Okta：將群組作為角色

  1. 在 Okta 管理控制台，點選 安全>API。
  2. 選擇你的授權伺服器。
  3. 請前往 「理賠」 分頁。
  4. 新增申訴：
    • 名稱： roles
    • 包含在令牌類型中：存取令牌
    • 價值類型：群組
    • 篩選器：選擇要包含的群組

Auth0：用動作新增角色

  1. 在 Auth0 儀表板中，前往 動作>資料庫。
  2. 建立一個新的動作（登入後觸發器）。
  3. 新增程式碼以包含角色：
exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};
  1. 部署該操作並將其加入到你的登入流程。

小提示

關於如何以 Okta 配置 JWT 理賠的詳細指引，請參見 《使用 Okta SDK 實作進階 JWT 理賠。

步驟五：測試配置

  1. 啟動 Data API 構建器：

    dab start

  2. 從你的身份提供者那裡取得一個代幣。 使用你服務提供者的 SDK 或像 Postman 這類工具。

  3. 請檢查 jwt.io 的代幣以驗證：

    • aud該理賠符合你設定的受眾
    • iss理賠金額與你設定的發卡機構相符
    • roles該聲明包含預期的值

  4. 呼叫 API：

    curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>"

  5. 要使用自訂角色，請包含標頭檔：X-MS-API-ROLE

    curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>" \
  -H "X-MS-API-ROLE: admin"

JWT 驗證細節

資料 API 建構器驗證 JWT 的這些面向：

檢查 Description
簽章 透過由配置的 jwt.issuer 授權機構發現的簽署金鑰（OpenID Connect 元資料 / JWKS）進行驗證
簽發者 必須完全符合 jwt.issuer 配置
觀眾 必須完全符合 jwt.audience 配置
到期 代幣必須不會過期（exp 聲稱）
以前沒有 代幣必須有效（nbf 若有，則有聲明）

故障排除

癥狀 可能原因 Solution
401 Unauthorized 發行人不匹配 請檢查 iss 宣稱是否完全匹配（尤其是尾隨斜線）
401 Unauthorized 觀眾群不匹配 檢查 aud 理賠金額是否符合你設定的金額
401 Unauthorized 代幣已過期 取得一個新的代幣
401 Unauthorized 元資料無法取得 確保 DAB 能覆蓋 <issuer>/.well-known/openid-configuration
403 Forbidden 角色非象徵性 將該角色加入你的 IdP 配置
403 Forbidden 聲稱缺失的角色 配置你的 IdP 以包含 roles 索賠
403 Forbidden 錯誤的宣稱名稱 DAB 使用理賠類型 roles （固定，不可設定）

這很重要

DAB 目前所有角色檢查都使用該申請類型 roles 。 此值是硬編碼的，無法更改為 groups、 permissions或其他理賠名稱。 設定你的身份提供者在名為 roles 的主張中發送角色。

常見發行格式

Provider 發行格式
Okta https://<domain>.okta.com 或 https://<domain>.okta.com/oauth2/default
Auth0 https://<tenant>.auth0.com/ （注意尾部斜線）
Azure AD B2C https://<tenant>.b2clogin.com/<tenant-id>/v2.0/
Keycloak https://<host>/realms/<realm>

完整組態範例

Okta 配置

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "0oa1234567890abcdef",
          "issuer": "https://dev-12345.okta.com"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Auth0 配置

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "https://my-api.example.com",
          "issuer": "https://my-tenant.auth0.com/"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

相關內容

  • Last updated on