API проверки подлинности

API проверки подлинности позволяет визуальным элементам получать маркеры доступа Microsoft Entra ID (прежнее название — Azure AD) для пользователей, вошедшего в систему, обеспечивая проверку подлинности единого входа.

Администраторы Power BI могут включить или отключить API с помощью глобального коммутатора. Блоки параметров по умолчанию (отключают) API.

API применим только для визуальных элементов AppSource, а не для частных визуальных элементов. Визуальные элементы, которые находятся в процессе разработки, можно протестировать в режиме отладки перед их публикацией.

Поддерживаемые среды

Поддерживаются следующие среды:

• Интернет
• Настольный компьютер
• RS Desktop
• Мобильные службы

Неподдерживаемые среды

Следующие среды пока не поддерживаются:

• Служба RS
• Встроенная аналитика
• Teams

Использование API проверки подлинности

В файле capabilities.json добавьте привилегию AADAuthentication с зарегистрированным URI зарегистрированного приложения Microsoft Entra ID для каждого поддерживаемого облака. 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: привилегии не поддерживаются в текущей среде.
  • DisabledBy Администратор: администратор Fabric отказал в использовании привилегий.

В следующем примере кода показано, как получить маркер идентификатора Microsoft Entra с помощью API:

    // 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 Graph в клиенте потребителя с помощью визуального элемента. Дополнительные сведения о согласии см. в разделе "Согласие администратора клиента".

Связанный контент

Настройка приложения идентификатора Microsoft Entra