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

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

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

Data plane and control plane APIs

• 數據平面 API 是工作負載後端公開的 API。 工作負載前端可以直接呼叫它們。 For data plane APIs, the workload backend can decide on what APIs to expose.

• Control plane APIs are APIs that go through Fabric. 此程式會從呼叫 JavaScript API 的工作負載前端開始，並以網狀架構呼叫工作負載後端結束。 這類 API 的一個例子是建立項目。

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

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

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

• The scopes added for control plane APIs should preauthorize the Fabric Client for Workloads application with application ID d2450708-699c-41e3-8077-b0c8341509aa. Those scopes are included in the token that the workload backend receives when Fabric calls it.

  您必須為控制平面 API 新增至少一個範圍，流程才能運作。

• The scopes added for data plane APIs should preauthorize Microsoft Power BI with application ID 871c010f-5e61-4fb1-83ac-98610a7e9110. They're included in the token that the acquireAccessToken JavaScript API returns.

  For data plane APIs, you can use this tab to manage granular permissions for each API that your workload exposes. 在理想情況下，您應該為工作負載後端公開的每個 API 新增一組範圍，並在從用戶端呼叫這些 API 時驗證收到的令牌是否包含這些範圍。 例如：

  • 工作負載會將兩個 API 公開給用戶端，ReadData 和 WriteData。
  • 工作負載會揭示兩個數據平面範圍，data.read 和 data.write。
  • In the ReadData API, the workload validates that the data.read scope is included in the token before it continues with the flow. 同樣適用於 WriteData。

API permissions tab on the workload's application in Microsoft Entra ID

On the API permissions tab, you need to add all the scopes that your workload needs to exchange a token for. A mandatory scope to add is Fabric.Extend under the Power BI service. 若沒有此範圍，對 Fabric 的要求可能會失敗。

Working with tokens and consents

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

The following sections describe how the workload frontend should use the JavaScript API and on-behalf-of (OBO) flows to acquire tokens for the workload and external services, and to work with consents.

步驟 1：取得令牌

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

• The user sees a consent window of all the static dependencies (what's configured on the API permissions tab) that the workload configured. 如果使用者不屬於應用程式的主租使用者，且之前未授權此應用程式使用 Microsoft Graph，就會發生這種情況。

• 使用者看不到同意視窗。 This scenario happens if the user already consented at least once to Microsoft Graph for this application, or if the user is a part of the application's home tenant.

In both scenarios, the workload shouldn't care whether or not the user gave full consent for all of the dependencies (and can't know at this point). The received token has the workload backend audience and can be used to directly call the workload backend from the workload frontend.

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

工作負載可能需要存取需要驗證的服務。 For that access, it needs to perform the OBO flow, where it exchanges the token that it received from its client or from Fabric to another service. The token exchange might fail because of lack of consent or some Microsoft Entra Conditional Access policy that's configured on the resource that the workload is trying to exchange the token for.

To solve this problem, it's the workload's responsibility to propagate the error to the client when working with direct calls between the frontend and the backend. It's also the workload's responsibility to propagate the error to the client when working with calls from Fabric by using the error propagation described in Workload communication.

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

如資料面 API 發生故障，請參閱 多重驗證、條件性存取及累進同意處理。 For control plane API failures, see Workload communication.

範例案例

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

• List workspaces: GET https://api.fabric.microsoft.com/v1/workspaces

• Create a warehouse: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

• Write to a lakehouse file: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

To be able to work with those APIs, the workload backend needs to exchange tokens for the following scopes:

• 列出工作區的方法為：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
• For writing to a lakehouse file: https://storage.azure.com/user_impersonation

Note

You can find scopes needed for each Fabric API in this reference article.

The scopes mentioned earlier need to be configured on the workload application under API permissions.

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

Example 1

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

1. The workload frontend asks for a token by using the JavaScript API.

2. The workload frontend calls the workload backend API to get the workspaces of the user and attaches the token in the request.

3. The workload backend validates the token and tries to exchange it for the required scope (let's say https://analysis.windows.net/powerbi/api/Workspace.Read.All).

4. 工作負載無法交換指定資源的令牌，因為使用者未同意應用程式存取此資源（請參閱 AADSTS 錯誤碼）。

5. The workload backend propagates the error to the workload frontend by specifying that it needs consent for that resource. The workload frontend calls the acquireAccessToken JavaScript API and provides additionalScopesToConsent:

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

   Alternatively, the workload can decide to ask for consent for all of its static dependencies that are configured on its application, so it calls the JavaScript API and provides promptFullConsent:

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

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

Note

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

Example 2

Let's assume that the workload backend needs to access OneLake on the Create Item API (call from Fabric to the workload):

1. 工作負載前端會呼叫建立項目 JavaScript API。

2. 工作負載後端會從 Fabric 接收呼叫，並擷取委派的令牌並加以驗證。

3. The workload tries to exchange the token for https://storage.azure.com/user_impersonation but fails because the tenant administrator of the user-configured multifactor authentication needed to access Azure Storage (see AADSTS error codes).

4. The workload propagates the error alongside the claims returned in the error from Microsoft Entra ID to the client by using the error propagation described in Workload communication.

5. 工作負載前端會呼叫 acquireAccessToken JavaScript API，並將宣告提供為 claimsForConditionalAccessPolicy，其中 claims 是指從工作負載後端傳播過來的宣告。

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

After that, the workload can retry the operation.

Handling errors when requesting consents

有時候使用者因為各種錯誤而無法授與同意。 同意要求之後，系統會將回應傳回至重新導向 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 擷取錯誤碼並據以處理。

Note

In both scenarios (error and success), the workload must always close the window immediately, with no latency.