分享方式：

驗證 API

  • 文章

驗證 API 可讓視覺效果取得登入使用者的 Microsoft Entra ID (先前稱為 Azure AD) 存取權杖，從而促進單一登錄驗證。

Power BI 系統管理員可以透過全域交換器啟用或停用 API。 預設設定區塊 (停用) API。

API 僅適用於 AppSource 視覺效果，不適用於私人視覺效果。 在發行之前，開發中的視覺效果可以在偵錯模式中進行測試。

支援的環境

支援下列環境：

  • Web
  • 桌面
  • RS 桌面
  • 行動

不支援的環境

尚不支援下列環境：

  • RS 服務
  • 內嵌式分析
  • Teams

如何使用驗證 API

在 capabilities.json 檔案中，為每個支援的雲端新增具有 Microsoft Entra ID 註冊應用程式 URI 的 "AADAuthentication" 權限。 Fabric 會根據為目前雲端設定的對象產生權杖，並將其傳遞給視覺效果。
然後，視覺效果可以使用權杖來針對個別對象進行驗證，以代表其後端服務：

"privileges": [
    {
        "name": "AADAuthentication",
        "parameters": {
            "COM": "https://contoso.com",
            "CN": "https://contoso.cn"
        }
    }
]

在 pbiviz.json 檔案中 ，將 API 版本設定為 5.9.1 或更高版本：

新公開的 AcquireAADTokenService 包含兩種方法：

  • acquireAADToken：如果無法擷取，則會傳回視覺效果的類型 AcquireAADTokenResult 驗證權杖承載或 null。

     /**
 * Enum representing the various clouds supported by the Authentication API.
 */
export const enum CloudName {
    COM = "COM",         // Commercial Cloud
    CN = "CN",           // China Cloud
    GCC = "GCC",         // US Government Community Cloud
    GCCHIGH = "GCCHIGH", // US Government Community Cloud High
    DOD = "DOD",         // US Department of Defense Cloud
}

/**
 * Interface representing information about the user associated with the token.
 */
export interface AcquireAADTokenUserInfo {
    userId?: string;   // Unique identifier for the user
    tenantId?: string; // Unique identifier for the tenant
}

/**
 * Interface representing information about the fabric environment.
 */
export interface AcquireAADTokenFabricInfo {
    cloudName?: CloudName; // Name of the cloud environment
}

/**
 * Interface representing the result of acquiring a Microsoft Entra ID token.
 */
export interface AcquireAADTokenResult {
    accessToken?: string;       // Access token issued by Microsoft Entra ID
    expiresOn?: number;         // Expiration time of the access token
    userInfo?: AcquireAADTokenUserInfo;     // Information about the user associated with the token
    fabricInfo?: AcquireAADTokenFabricInfo; // Information about the fabric environment
}

  • acquireAADTokenstatus：傳回與取得權杖相關聯的下列其中一個權限狀態。

    • Allowed：目前環境中允許權限。
    • NotDeclared：視覺功能區段中遺漏權限宣告。
    • NotSupported：目前環境中不支援權限。
    • DisabledByAdmin：Fabric 系統管理員拒絕權限使用。

下列範例程式碼示範如何使用 API 取得 Microsoft Entra ID 權杖：

    // Step 1: Check the status of AAD token acquisition 
    const acquireTokenStatus = await this.acquireAADTokenService.acquireAADTokenstatus(); 

    // Step 2: Verify if acquiring the token is allowed 
    if (acquireTokenStatus === PrivilegeStatus.Allowed) { 

       // Step 3: Acquire the Microsoft Entra ID token
       const acquireAADTokenResult: AcquireAADTokenResult = await this.acquireAADTokenService.acquireAADToken(); 

       // Step 4: Confirm successful acquisition of the access token
       if (acquireAADTokenResult.accessToken) { 

            // Step 5: Call your backend API with the obtained token 
        } 
    } 

    // Step 6: Handle unsuccessful AAD token acquisition

考量與限制

如果適用下列任一情況，就會封鎖權杖取得：

  • 租用戶切換已關閉。

  • 使用者未登入 (在桌面中)。

  • ISV 未預先授權 Power BI 應用程式。

  • AADAuthentication 權限參數的格式無效。

  • 視覺效果未公開核准或不是偵錯視覺效果。

  • 視覺效果的後端服務，由視覺效果設定為對象，在使用視覺效果的取用者租用戶中，沒有圖形 API 的適當同意。 如需同意的詳細資訊，請參閱租用戶系統管理員同意。

相關內容

Microsoft Entra ID 應用程式設定