Zdieľať cez

Rozhranie API overovania

  • Článok

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

Správcovia služby Power BI môžu povoliť alebo zakázať rozhranie API prostredníctvom globálneho prepínača. Predvolené bloky nastavenia (zakáže) rozhranie API.

Rozhranie API sa vzťahuje len na vizuály AppSource, nie na súkromné vizuály. Vizuály, ktoré sú vo vývoji, je možné pred publikovaním testovať v režime ladenia.

Podporované prostredia

Podporované sú nasledujúce prostredia:

  • Web
  • Pracovná plocha
  • RS Desktop
  • Mobilné zariadenia

Nepodporované prostredia

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

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

Používanie rozhrania API na overovanie

Do súboru capabilities.json pridajte oprávnenie AADAuthentication s identifikátorom URI registrovanej aplikácie Microsoft Entra pre každý podporovaný cloud. Fabric vygeneruje token podľa publika nakonfigurovaného pre aktuálny cloud a dodá ho do vizuálu.
Vizuál potom môže využiť token na overenie pre príslušnú cieľovú skupinu predstavujúcu jeho serverovú službu:

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

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

Novo exponovaná služba AcquireAADTokenService obsahuje dve metódy:

  • acquireAADToken: Vráti údajovú časť tokenu overenia typu AcquireAADTokenResult pre vizuál alebo hodnotu null, ak sa nedá načítať.

     /**
 * 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
}

  • acquireADTokenstatus: Vráti jedno z nasledujúcich oprávnení priradených k získaniu tokenu.

    • Povolené: Oprávnenie je povolené v aktuálnom prostredí.
    • NotDeclared: Deklarácia oprávnenia chýba v časti možností vizuálu.
    • NotSupported (Nepodporované): Oprávnenie nie je podporované v aktuálnom prostredí.
    • DisabledBy Spravovanie: Správca služby Fabric poprel používanie oprávnení.

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

Akvizícia tokenu je blokovaná, ak sa uplatňuje niektorá z nasledujúcich podmienok:

  • Prepínač nájomníka je vypnutý.

  • Používateľ nie je prihlásený (v aplikácii Desktop).

  • Nezávislý dodávateľ softvéru nepredvolil predbežnú autorizáciu aplikácie Power BI.

  • Formát parametra oprávnenia AADAuthentication je neplatný.

  • Vizuál nie je verejne schválený alebo nie je vizuálom ladenia.

  • Serverová služba vizuálu nakonfigurovaná ako cieľová skupina vizuálu nemá príslušné súhlasy pre rozhranie Graph API v nájomníkovi spotrebiteľských používateľov, ktorí ho používajú. Ďalšie informácie o súhlase nájdete v téme Súhlas správcu nájomníkov.

Súvisiaci obsah

Nastavenie aplikácie id Microsoft Entra