Dela via

API för autentisering

  • Artikel

Autentiserings-API:et gör det möjligt för visuella objekt att hämta Microsoft Entra-ID (tidigare kallat Azure AD) åtkomsttoken för inloggade användare, vilket underlättar enkel inloggningsautentisering.

Power BI-administratörer kan aktivera eller inaktivera API:et via en global växel. Standardinställningen blockerar (inaktiverar) API:et.

API:et gäller endast för visuella AppSource-objekt och inte för privata visuella objekt. Visuella objekt som är under utveckling kan testas i felsökningsläge innan de publiceras.

Miljöer som stöds

Följande miljöer stöds:

  • Webb
  • Skrivbord
  • RS Desktop
  • Mobilt

Miljöer som inte stöds

Följande miljöer stöds inte ännu:

  • RS-tjänst
  • Inbäddad analys
  • Teams

Så här använder du API:et för autentisering

I capabilities.json-filen lägger du till behörigheten "AADAuthentication" med en Microsoft Entra ID-registrerad program-URI för varje moln som stöds. Infrastrukturresurser genererar en token enligt den målgrupp som konfigurerats för det aktuella molnet och levererar den till det visuella objektet.
Det visuella objektet kan sedan använda token för att autentisera mot respektive målgrupp, vilket representerar dess serverdelstjänst:

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

I filen pbiviz.json anger du API-versionen till 5.9.1 eller senare:

Den nyligen exponerade AcquireAADTokenService innehåller två metoder:

  • acquireAADToken: Returnerar en nyttolast för autentiseringstoken av typen AcquireAADTokenResult för det visuella objektet eller null om det inte kan hämtas.

     /**
 * 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: Returnerar någon av följande behörighetsstatusar som är associerade med att hämta token.

    • Tillåten: Behörigheten tillåts i den aktuella miljön.
    • NotDeclared: Behörighetsdeklarationen saknas i avsnittet visuella funktioner.
    • Stöds inte: Behörigheten stöds inte i den aktuella miljön.
    • DisabledByAdmin: Infrastrukturadministratören nekade behörighetsanvändning.

Följande exempelkod visar hur du hämtar en Microsoft Entra-ID-token med hjälp av API:et:

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

Beaktanden och begränsningar

Tokenförvärv blockeras om något av följande villkor gäller:

  • Klientväxeln är inaktiverad.

  • Användaren är inte inloggad (i Desktop).

  • ISV:en förauktoriserar inte Power BI-programmet i förväg.

  • Formatet för parametern AADAuthentication privilege är ogiltigt.

  • Det visuella objektet är inte offentligt godkänt eller är inte ett visuellt felsökningsobjekt.

  • Det visuella objektets serverdelstjänst, som konfigurerats som målgrupp av det visuella objektet, har inte lämpliga medgivanden för Graph-API:et i konsumentklientorganisationen med hjälp av det visuella objektet. Mer information om medgivande finns i klientadministratörens medgivande.

Relaterat innehåll

Installation av Microsoft Entra-ID-program