Бөлісу құралы:

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