Share via

Godkjennings-API

  • Artikkel

Godkjennings-API-en gjør det mulig for visualobjekter å få tilgangstokener for Microsoft Entra ID (tidligere kjent som Azure AD) for påloggede brukere, noe som letter enkel påloggingsgodkjenning.

Power BI-administratorer kan aktivere eller deaktivere API-en via en global bryter. Standard innstillingsblokker (deaktiverer) API-en.

API-en gjelder bare for AppSource-visualobjekter, og ikke for private visualobjekter. Visualobjekter som er under utvikling, kan testes i feilsøkingsmodus før de publiseres.

Støttede miljøer

Følgende miljøer støttes:

  • Web
  • Skrivebord
  • RS Desktop
  • Mobil

Miljøer som ikke støttes

Følgende miljøer støttes ennå ikke:

  • RS-tjeneste
  • Innebygd analyse
  • Teams

Slik bruker du API-en for godkjenning

Legg til «AADAuthentication»-rettigheten i capabilities.json-filen med en Microsoft Entra ID-registrert program-URI for hver støttede sky. Fabric genererer et token i henhold til målgruppen som er konfigurert for den gjeldende skyen, og leverer det til visualobjektet.
Visualobjektet kan deretter bruke tokenet til å godkjenne mot den respektive målgruppen, som representerer serverdeltjenesten:

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

Angi API-versjonen til 5.9.1 eller høyere i pbiviz.json-filen:

Den nylig eksponerte AcquireAADTokenService inneholder to metoder:

  • acquireAADToken: Returnerer en nyttelast for godkjenningstoken av typen AcquireAADTokenResult for visualobjektet eller null hvis det ikke kan hentes.

     /**
 * 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: Returnerer én av følgende rettighetsstatuser som er knyttet til anskaffelse av tokenet.

    • Tillatt: Rettigheten er tillatt i gjeldende miljø.
    • NotDeclared: Rettighetsdeklarasjonen mangler i inndelingen visualobjektfunksjoner.
    • Støttes ikke: Rettigheten støttes ikke i gjeldende miljø.
    • DisabledByAdmin: Fabric-administratoren nektet rettighetsbruk.

Følgende eksempelkode viser hvordan du skaffer deg et Microsoft Entra ID-token ved hjelp av API-en:

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

Hensyn og begrensninger

Tokenanskaffelser blokkeres hvis noen av følgende betingelser gjelder:

  • Leierbryteren er slått av.

  • Brukeren er ikke logget på (i Skrivebord).

  • ISV-en forhåndsautoriserer ikke Power BI-programmet.

  • Formatet for AADAuthentication-rettighetsparameteren er ugyldig.

  • Visualobjektet er ikke offentlig godkjent eller er ikke et feilsøkingsvisualobjekt.

  • Visualobjektets serverdeltjeneste, konfigurert som målgruppe av visualobjektet, har ikke nødvendige samtykker for Graph-API-en i forbrukerleieren ved hjelp av visualobjektet. Hvis du vil ha mer informasjon om samtykke, kan du se samtykke fra leieradministrator.

Relatert innhold

Installasjon av Microsoft Entra ID-program