GraphQL API 的自訂授權與使用者資料功能（預覽版）

授權者 User-Defined 函式（UDFs）允許你 在處理 GraphQL API 請求前執行自訂授權邏輯。 此功能使 API 擁有者能強制執行超越靜態角色指派的業務專用存取規則。 透過授權函式 UDF，您可以評估已認證請求中的資訊（例如，JSON Web Token（JWT）令牌中的聲明），並決定是否應允許該請求。 該邏輯以函式形式實作，並自動在 API 呼叫時被呼叫。

使用案例

當你需要時，可以使用授權使用者資料函式：

• 在執行 API 前套用自訂商業邏輯
• 根據使用者身份或憑證主張限制存取權限
• 驗證服務主體時，請與使用者帳號分開處理

授權功能的運作方式

當啟用自訂授權並使用使用者資料函式時：

• 函式在 GraphQL API 執行前執行。
• 它會從已驗證的請求中接收上下文。
• 自訂邏輯會檢查授權。
• 若授權成功，API 請求會繼續進行，否則將被拒絕。
• 未來的請求能更快達成此結果。

建立用戶數據函式

Fabric 使用者資料函式中的授權函式需要特定的格式。

1. 函式名稱可由使用者定義。 它沒有 GraphQL 專屬的限制，應根據使用者資料函式的限制來定義。
2. 函式參數/參數名稱應該是 request，且型別應該是字典。 當 GraphQL 服務端呼叫函式時，會傳送一個包含名為請求的字典的載荷，其中包含以下欄位：
   • tokenClaims（字典）： 包含從輸入使用者憑證中提取的權杖權利的鍵值對。
   • query（string）： 當呼叫 GraphQL API 時傳遞的查詢字串。
   • variables（字典）： 包含在呼叫 GraphQL API 時傳遞的變數的鍵值對。
   • 回傳類型（字典）： 函數會回傳 isAuthorized 和 roles。 roles 為可選，且需在啟用 RBAC 功能時發送。

Example

在 Fabric portal 建立使用者資料函式。 用這個範例授權函式更新函式程式碼。

from typing import TYPE_CHECKING
import fabric.functions as fn
import logging

user data function = fn.UserDataFunctions()

@user data function.function()
def invokeauthudf(request: dict) -> dict:
    
    token_claims: dict = request.get("tokenClaims", {})
    query: str = request.get("query", "")
    variables: dict = request.get("variables", {})
    domain = "onmicrosoft.com"
    spn = "<SPN-ID>"

    # Extract claims from token_claims dictionary
    tid_claim = token_claims.get("tid")
    upn_claim = token_claims.get("upn")
    appid_claim = token_claims.get("appid")
    logging.info(f"Query: {query}");
    logging.info(f"Claims: {token_claims}");
    logging.info(f"Tenant: {tid_claim}");
    logging.info(f"UPN: {upn_claim}");
    logging.info(f"SPN: {appid_claim}");

    # Authorization logic
    ## Optional: Do role-based access check
    roles = []

    if upn_claim is not None:
        is_authorized = domain in upn_claim
        roles = ["Default"]
    else:
        is_authorized =  spn in appid_claim
        roles = ["SPN"]

    logging.info(f"Authorized: {is_authorized}")
    logging.info(f"Roles: {roles}")
    logging.info(f"SPN: {spn}")
    logging.info(f"App ID: {appid_claim}")
    return {

            "isAuthorized": is_authorized,
            "roles": roles
    }

這個函式是做什麼的？

• 此授權使用者資料函式會在 GraphQL 請求執行前執行，從呼叫者的 JSON Web Token （JWT） 令牌讀取身份聲明（UPN、應用程式 ID），並記錄請求細節。
• 它透過檢查使用者的電子郵件（UPN）是否屬於特定網域來授權，並透過匹配已知的應用程式 ID 來授權服務主體。
• 根據結果，它會回傳 isAuthorized。

新增連接到使用者資料函式

在啟用此功能之前，你需要先為使用者資料功能類型新增一個連線。

1. 在 設定 中，選擇 管理連線與閘道器。
2. 在「連線」標籤中，選擇「新」。
3. 在 新連線 頁面，選擇 雲端，提供連線名稱，並選擇 使用者資料功能 作為連線類型。 使用 OAUth 方法並更新憑證以進行驗證。 建立這個連線時，你不需要勾選「允許此連線與本地資料閘道或 VNet 資料閘道使用」。

啟用授權功能

當該函式及該使用者資料函式的連線建立後，啟用授權功能。 你需要寫入權限才能啟用或停用這個功能。

1. 打開 GraphQL 項目的 API，選擇 設定。
2. 選擇 授權（預覽） 並啟用此功能。
3. 提供使用者資料函數項目和你想使用的認證函數。

限制與行為

下一步

• 連接到應用程式