Rozhranie API overovania

Autentifikačné API umožňuje vizuálom získať prístupové tokeny Microsoft Entra ID (predtým známe ako Azure AD) pre prihlásených používateľov, čím uľahčuje jednorazové prihlásenie.

Administrátori Power BI môžu API povoliť alebo vypnúť prostredníctvom globálneho prepínača. Predvolené nastavenie blokuje (deaktivuje) API.

API je použiteľné iba pre vizuály AppSource, nie pre súkromné vizuály. Vizuály, ktoré sú vo vývoji, je možné otestovať v debug režime pred ich publikovaním.

Podporované prostredia

Podporované sú nasledujúce prostredia:

  • Web
  • Stolný počítač
  • RS Desktop
  • Mobile

Nepodporované prostredia

Nasledujúce prostredia zatiaľ nie sú podporované:

  • RS služba
  • Vložená analytika
  • Teams

Ako používať autentifikačné API

V capabilities.json súbore pridajte privilégium "AADAuthentication" s Microsoft Entra ID registrovaným URI aplikácie pre každý podporovaný cloud. Fabric generuje token podľa publika nakonfigurovaného pre aktuálny cloud a doručuje ho na vizuál.
Vizuál potom môže token využiť na autentifikáciu voči príslušnému publiku, čím reprezentuje svoju backendovú službu:

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

V pbiviz.json súbore nastavte verziu API na 5.9.1 alebo novšiu:

Novo sprístupnený AcquireAADTokenService obsahuje dve metódy:

  • acquireAADToken: Vráti authenticačný token payload typu AcquireAADTokenResult pre vizuál alebo null, ak ho nie je možné získať.

     /**
 * 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áti jeden z nasledujúcich privilégií spojených so získaním tokenu.

    • Povolené: Táto výsada je v súčasnom prostredí povolená.
    • NotDeclared: Vyhlásenie privilégií chýba v sekcii vizuálnych schopností.
    • Nepodporované: Táto výhoda nie je v súčasnom prostredí podporovaná.
    • DisabledByAdmin: Administrátor Fabric zamietol použitie oprávnení.

Nasledujúci ukážkový kód ukazuje, ako získať Microsoft Entra ID token pomocou 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

Dôležité informácie a obmedzenia

Získavanie tokenov je zablokované, ak platia niektoré z nasledujúcich podmienok:

  • Prepínač nájomcov je vypnutý.

  • Používateľ nie je prihlásený (na pracovnej ploche).

  • ISV nepredautorizovalo Power BI aplikáciu.

  • Formát parametra AADAuthentication privilege je neplatný.

  • Vizuál nie je verejne schválený ani nie je debug vizuálom.

  • Backendová služba vizuálu, konfigurovaná ako publikum vizuálom, nemá príslušné súhlasy pre Graph API v spotrebiteľskom tenante používajúcom vizuál. Viac o súhlase nájdete v článku Súhlas správcu nájomcu.

Súvisiaci obsah

Nastavenie aplikácie Microsoft Entra ID

  • Last updated on