通过

身份验证 API

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

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

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

支持的环境

支持以下环境：

  • Web
  • 桌面
  • RS Desktop
  • 手机

不支持的环境

尚不支持以下环境：

  • 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：返回与获取令牌关联的以下特权状态之一。

    • 允许：在当前环境中允许该权限。
    • 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 特权参数的格式无效。

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

  • 可视化的后台服务（被可视化配置为目标用户）没有在使用者租户中为 Graph API 提供相应的授权。 有关同意的详细信息，请参阅 租户管理员同意。

相关内容

Microsoft Entra ID 应用程序设置

  • Last updated on