Share via

身份验证 API

  • 项目

身份验证 API 使视觉对象能够获取登录用户的 Microsoft Entra ID（前 Azure AD）访问令牌，从而促进单一登录身份验证。

Power BI 管理员可以通过全局开关启用或禁用 API。 默认设置会阻止（禁用）API。

API 仅适用于 AppSource 视觉对象，不适用于专用视觉对象。 在发布之前，可以在调试模式下测试正在开发的视觉对象。

支持的环境

支持以下环境：

  • Web
  • 桌面
  • RS Desktop
  • 移动型

不受支持的环境

尚不支持以下环境：

  • RS Service
  • 嵌入式分析
  • 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

注意事项和限制

如果满足以下任一条件，则会阻止令牌获取：

  • 租户开关已关闭。

  • 用户未登录（在 Desktop 中）。

  • ISV 未预授权 Power BI 应用程序。

  • AADAuthentication 特权参数的格式无效。

  • 视觉对象未公开批准或不是调试视觉对象。

  • 视觉对象的后端服务（由视觉对象配置为受众）没有使用视觉对象在使用者租户中对图形 API 的相应同意。 有关同意的详细信息，请参阅租户管理员同意。

相关内容

Microsoft Entra ID 应用程序设置