Hitelesítési API

A Hitelesítési API lehetővé teszi a vizualizációk számára a Microsoft Entra ID (korábbi nevén Azure AD) hozzáférési jogkivonatok beszerzését a bejelentkezett felhasználók számára, megkönnyítve az egyszeri bejelentkezéses hitelesítést.

A Power BI-rendszergazdák globális kapcsolóval engedélyezhetik vagy letilthatják az API-t. Az alapértelmezett beállítás blokkolja (letiltja) az API-t.

Az API csak AppSource-vizualizációkra alkalmazható, magánvizualizációkra nem. A fejlesztés alatt álló vizualizációk hibakeresési módban tesztelhetők a közzététel előtt.

Támogatott környezetek

A következő környezetek támogatottak:

• Webes
• Asztali
• RS Desktop
• Mobil

Nem támogatott környezetek

A következő környezetek még nem támogatottak:

• RS szolgáltatás
• Beágyazott elemzések
• Teams

A hitelesítési API használata

A capabilities.json fájlban adja hozzá az "AADAuthentication" jogosultságot egy Regisztrált Microsoft Entra-alkalmazás URI-jával minden támogatott felhőhöz. A Fabric létrehoz egy jogkivonatot az aktuális felhőhöz konfigurált célközönségnek megfelelően, és kézbesíti azt a vizualizációnak.
A vizualizáció ezután felhasználhatja a jogkivonatot a megfelelő célközönségen való hitelesítéshez, amely a háttérszolgáltatást képviseli:

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

A pbiviz.json fájlban állítsa az API 5.9.1-es vagy újabb verzióját:

Az újonnan közzétett AcquireAADTokenService két módszert tartalmaz:

• acquireAADToken: A vizualizációhoz vagy null értékhez tartozó AcquireAADTokenResult hitelesítési jogkivonatot ad vissza, ha nem lehet beolvasni.

   /**
   * 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: A jogkivonat beszerzéséhez társított alábbi jogosultsági állapotok egyikét adja vissza.

  • Engedélyezett: A jogosultság az aktuális környezetben engedélyezett.
  • NotDeclared: A jogosultsági deklaráció hiányzik a vizualizáció képességei szakaszban.
  • Nem támogatott: A jogosultság az aktuális környezetben nem támogatott.
  • DisabledBy Rendszergazda: A Háló rendszergazdája megtagadta a jogosultságok használatát.

Az alábbi mintakód bemutatja, hogyan szerezhet be Egy Microsoft Entra ID-jogkivonatot az API használatával:

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

Szempontok és korlátozások

A jogkivonatok beszerzése le lesz tiltva, ha az alábbi feltételek valamelyike érvényes:

• A bérlőkapcsoló ki van kapcsolva.

• A felhasználó nincs bejelentkezve (a Desktopban).

• Az ISV nem készítette elő a Power BI-alkalmazást.

• Az AADAuthentication privilege paraméter formátuma érvénytelen.

• A vizualizáció nincs nyilvánosan jóváhagyva, vagy nem hibakeresési vizualizáció.

• A vizualizáció háttérszolgáltatása, amelyet a vizualizáció konfigurál közönségként, nem rendelkezik megfelelő hozzájárulásokkal a Graph API-hoz a vizualizációt használó fogyasztói bérlőben. A hozzájárulásról további információt a bérlői rendszergazda hozzájárulásában talál.

Kapcsolódó tartalom

Microsoft Entra ID-alkalmazás beállítása