Microsoft Fabric 中的工作負載驗證指導方針概觀

發行項
12/15/2024

本文提供在建置Microsoft網狀架構工作負載時如何使用驗證的指導方針。包含有關處理代幣和授權同意的資訊。

開始之前，請確定您已熟悉驗證概觀和驗證設定的概念。

數據平面和控制平面 API

數據平面 API 是工作負載後端公開的 API。工作負載前端可以直接呼叫它們。針對數據平面 API，工作負載後端可以決定要公開的 API。
控制平面 API 是透過 Fabric 的 API。此程式會從呼叫 JavaScript API 的工作負載前端開始，並以網狀架構呼叫工作負載後端結束。這類 API 的一個例子是建立項目。

針對控制平面 API，工作負載必須遵循工作負載後端中定義的合約，並實作這些 API。

在 Microsoft Entra ID 中公開工作負載應用程式的 API 標籤

在 公開 API 索引標籤上，您需要新增控制平面 API 的權限範圍，以及資料平面 API 的權限範圍：

針對控制平面 API 新增的範圍應預先授權具有應用程式識別碼的 Fabric Client for Workloads 應用程式 d2450708-699c-41e3-8077-b0c8341509aa。當 Fabric 呼叫時，工作負載後端收到的令牌中會包含這些範圍。

您必須為控制平面 API 新增至少一個範圍，流程才能運作。
針對數據平面 API 新增的範圍，應該使用應用程式識別碼 871c010f-5e61-4fb1-83ac-98610a7e9110預先授權 Microsoft Power BI。這些內容包含在 acquireAccessToken JavaScript API 回傳的令牌中。

針對數據平面 API，您可以使用此索引標籤來管理工作負載所公開之每個 API 的細微許可權。在理想情況下，您應該為工作負載後端公開的每個 API 新增一組範圍，並在從用戶端呼叫這些 API 時驗證收到的令牌是否包含這些範圍。例如：
- 工作負載會將兩個 API 公開給用戶端，ReadData 和 WriteData。
- 工作負載會揭示兩個數據平面範圍，data.read 和 data.write。
- 在 ReadData API 中，工作負載會先驗證令牌中包含 data.read 範圍，再繼續進行流程。同樣適用於 WriteData。

Microsoft Entra ID 中工作負載的應用程式之 [API 權限] 索引標籤

在 [API 許可權] 索引標籤上，您需要新增工作負載需要交換令牌的所有範圍。必須新增的範圍是 Power BI 服務下的 Fabric.Extend。若沒有此範圍，對 Fabric 的要求可能會失敗。

使用令牌和同意

當您使用數據平面 API 時，工作負載前端必須取得令牌，才能呼叫工作負載後端。

下列各節說明工作負載前端如何使用 JavaScript API 和代理程式（OBO）流程取得工作負載和外部服務的令牌，以及使用同意。

步驟 1：取得令牌

工作負載一開始會使用 JavaScript API 來要求令牌，而不需要提供任何參數。此呼叫可能會導致兩個案例：

使用者會看到工作負載所設定之所有靜態相依性的同意視窗（API 許可權 索引標籤上設定的內容）。如果使用者不屬於應用程式的主租使用者，且之前未授權此應用程式使用 Microsoft Graph，就會發生這種情況。
使用者看不到同意視窗。如果使用者已至少同意一次 Microsoft Graph 此應用程式，或使用者屬於應用程式的主承租戶，就會發生這種情況。

在這兩種案例中，工作負載都不應該在意使用者是否已完全同意所有相依性（此時無法得知）。收到的令牌具有工作負載後端的使用範圍，可用來直接從工作負載前端呼叫工作負載後端。

步驟 2：嘗試存取外部服務

工作負載可能需要存取需要驗證的服務。為了存取此權限，它必須執行 OBO 流程，其中它會將從用戶端接收到的令牌或從 Fabric 傳送到另一個服務。令牌交換可能會失敗，原因是缺少同意，或是在工作負載嘗試交換令牌的資源上設定了某些 Microsoft Entra 條件式存取原則。

若要解決此問題，工作負載有責任在處理前端與後端之間的直接呼叫時，將錯誤傳播至用戶端。在處理來自 Fabric 的呼叫時，工作負載的責任是使用工作負載通訊中所述的錯誤傳播，將錯誤傳播至用戶端。

在工作負載傳播錯誤之後，它可以呼叫 acquireAccessToken JavaScript API 來解決同意或條件式存取原則問題，然後重試作業。

如資料面 API 發生故障，請參閱多重驗證、條件性存取及累進同意處理。有關控制平面 API 失敗，請參閱工作負載通訊。

範例案例

讓我們看看需要存取三個網狀架構 API 的工作負載：

列出工作區：GET https://api.fabric.microsoft.com/v1/workspaces
建立倉儲： POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses
寫入湖庫檔案：PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

若要能夠使用這些 API，工作負載後端必須交換下列範圍的令牌：

列出工作區的方法為：https://analysis.windows.net/powerbi/api/Workspace.Read.All 或 https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
若要建立倉儲：https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All 或 https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
若要寫入 Lakehouse 檔案：https://storage.azure.com/user_impersonation

注意

您可以在本參考文章中找到每個網狀架構 API 所需的範圍。

先前所述的範圍必須在 API 許可權下的工作負載應用程式上設定。

讓我們看看工作負載可能遇到的案例範例。

範例 1

假設工作負載後端有一個數據平面 API，可取得使用者的工作區，並將其傳回用戶端：

工作負載前端會使用JavaScript API要求令牌。
工作負載前端會呼叫工作負載後端 API，以取得使用者的工作區，並在要求中附加令牌。
工作負載後端會驗證令牌，並嘗試將它交換為所需的範圍（例如 https://analysis.windows.net/powerbi/api/Workspace.Read.All）。
工作負載無法交換指定資源的令牌，因為使用者未同意應用程式存取此資源（請參閱 AADSTS 錯誤碼）。
工作負載後端會指定某些資源需要同意，藉此將錯誤傳播至工作負載前端。工作負載前端會呼叫 acquireAccessToken JavaScript API，並提供 additionalScopesToConsent：

workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})

或者，工作負載也可以決定要求同意於其應用程式上設定的所有靜態相依性，因此會呼叫 JavaScript API 並提供 promptFullConsent：

workloadClient.auth.acquireAccessToken({promptFullConsent: true}).

不論使用者是否同意某些相依性，此呼叫都會提示同意視窗。之後，工作負載前端可以重試作業。

注意

如果令牌交換在同意錯誤時仍然失敗，表示使用者未授與同意。工作負載需要處理這類情境；例如，通知使用者此 API 需要同意，否則將無法運作。

範例 2

假設工作負載後端必須在建立項目 API 上存取 OneLake（從 Fabric 呼叫到工作負載）：

工作負載前端會呼叫建立項目 JavaScript API。
工作負載後端會從 Fabric 接收呼叫，並擷取委派的令牌並加以驗證。
工作負載嘗試交換 https://storage.azure.com/user_impersonation 令牌但是失敗，因為存取 Azure 儲存體所需的多重驗證由使用者設定，而租戶系統管理員未正確配置。（請參閱 AADSTS 錯誤碼）。
工作負載使用在工作負載通訊中所描述的錯誤傳播機制，將 Microsoft Entra ID 傳回時所包含的宣告中的錯誤傳遞至客戶端。
工作負載前端會呼叫 acquireAccessToken JavaScript API，並將宣告提供為 claimsForConditionalAccessPolicy，其中 claims 是指從工作負載後端傳播過來的宣告。

workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})

之後，工作負載可以重試此作業。

處理要求同意時的錯誤

有時候使用者因為各種錯誤而無法授與同意。同意要求之後，系統會將回應傳回至重新導向 URI。在我們的範例中，此程式碼負責處理回應。（您可以在index.ts檔案中找到它。

const redirectUriPath = '/close'; 
const url = new URL(window.location.href); 
if (url.pathname?.startsWith(redirectUriPath)) { 
    // Handle errors, Please refer to https://learn.microsoft.com/entra/identity-platform/reference-error-codes 
    if (url?.hash?.includes("error")) { 
        // Handle missing service principal error 
        if (url.hash.includes("AADSTS650052")) { 
            printFormattedAADErrorMessage(url?.hash); 
        // handle user declined the consent error 
        } else  if (url.hash.includes("AADSTS65004")) { 
            printFormattedAADErrorMessage(url?.hash); 
        } 
    } 
    // Always close the window  
    window.close(); 
}

工作負載前端可以從 URL 擷取錯誤碼並據以處理。

注意

在這兩種情況下（無論錯誤或成功），系統工作負載都必須立即關閉視窗，且沒有任何延遲。

共用方式為