Sdílet prostřednictvím

Rozhraní API pro ověřování

  • Článek

Rozhraní API pro ověřování umožňuje vizuálům získat přístupové tokeny Microsoft Entra ID (dříve označované jako Azure AD) pro přihlášené uživatele, což usnadňuje ověřování pomocí jednotného přihlašování.

Správci Power BI můžou rozhraní API povolit nebo zakázat prostřednictvím globálního přepínače. Výchozí nastavení blokuje (zakáže) rozhraní API.

Toto rozhraní API platí jenom pro vizuály AppSource, nikoli pro privátní vizuály. Vizuály, které jsou ve vývoji, je možné testovat v režimu ladění před jejich publikováním.

Podporovaná prostředí

Podporují se následující prostředí:

  • Web
  • Desktop
  • RS Desktop
  • Mobilní

Nepodporovaná prostředí

Následující prostředí se zatím nepodporují:

  • Služba RS
  • Vložené analýzy
  • Teams

Jak používat rozhraní API pro ověřování

Do souboru capabilities.json přidejte oprávnění AADAuthentication s identifikátorem URI aplikace zaregistrovaným v Microsoft Entra pro každý podporovaný cloud. Prostředky infrastruktury vygenerují token podle cílové skupiny nakonfigurované pro aktuální cloud a doručí ho do vizuálu.
Vizuál pak může token využít k ověření vůči příslušné cílové skupině, která představuje svou back-endovou službu:

"privileges": [
    {
        "name": "AADAuthentication",
        "parameters": {
            "COM": "https://contoso.com",
            "CN": "https://contoso.cn"
        }
    }
]

V souboru pbiviz.json nastavte verzi rozhraní API na 5.9.1 nebo vyšší:

Nově zpřístupněná služba AcquireAADTokenService obsahuje dvě metody:

  • acquireAADToken: Vrátí datovou část ověřovacího tokenu typu AcquireAADTokenResult pro vizuál nebo hodnotu null, pokud ji nelze načíst.

     /**
 * 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: Vrátí jeden z následujících stavů oprávnění spojených se získáním tokenu.

    • Povoleno: Oprávnění je povolené v aktuálním prostředí.
    • NotDeclared: V části schopností vizuálu chybí deklarace oprávnění.
    • Nepodporováno: Oprávnění se v aktuálním prostředí nepodporuje.
    • DisabledBy Správa: Správce prostředků infrastruktury odepřel využití oprávnění.

Následující ukázkový kód ukazuje, jak získat token ID Microsoft Entra pomocí rozhraní 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

Úvahy a omezení

Získání tokenu se zablokuje, pokud platí některá z následujících podmínek:

  • Přepínač tenanta je vypnutý.

  • Uživatel není přihlášený (v Desktopu).

  • Výrobce softwaru předem neověřil aplikaci Power BI.

  • Formát parametru oprávnění AADAuthentication je neplatný.

  • Vizuál není veřejně schválený nebo není vizuál ladění.

  • Back-endová služba vizuálu nakonfigurovaná jako cílová skupina vizuálu nemá odpovídající souhlas pro rozhraní Graph API v tenantovi příjemce, který vizuál používá. Další informace o souhlasu najdete v tématu Souhlas správce tenanta.

Související obsah

Nastavení aplikace Microsoft Entra ID