Поделиться через

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

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

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

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

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

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

  • Интернет
  • Рабочий стол
  • RS Desktop
  • Мобильные устройства

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

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

  • Служба RS
  • Внедренная аналитика
  • Рабочие группы

Использование 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: привилегии не поддерживаются в текущей среде.
    • DisabledByAdmin: администратор 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.

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

  • Серверная служба визуального элемента, настроенная визуальным элементом как аудитория, не имеет соответствующих разрешений для Graph API в арендаторе-потребителе, который использует этот визуальный элемент. Дополнительные сведения о согласии см. в разделе "Согласие администратора клиента".

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

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

  • Last updated on