Share via

Godkendelses-API

  • Artikel

Godkendelses-API'en gør det muligt for visualiseringer at hente Microsoft Entra ID (tidligere kaldet Azure AD) adgangstokens til brugere, der er logget på, hvilket letter enkeltlogongodkendelse.

Power BI-administratorer kan aktivere eller deaktivere API'en via en global switch. Standardindstillingen blokerer (deaktiverer) API'en.

API'en gælder kun for AppSource-visualiseringer og ikke for private visualiseringer. Visualiseringer, der er under udvikling, kan testes i fejlfindingstilstand, før de publiceres.

Understøttede miljøer

Følgende miljøer understøttes:

  • Internet
  • Desktop
  • RS Desktop
  • Mobil

Miljøer, der ikke understøttes

Følgende miljøer understøttes endnu ikke:

  • RS-tjeneste
  • Integreret analyse
  • Teams

Sådan bruger du godkendelses-API'en

I capabilities.json-filen skal du tilføje rettigheden "AADAuthentication" med en registreret program-URI til microsoft entra-id for hver understøttet cloud. Fabric genererer et token i henhold til den målgruppe, der er konfigureret til den aktuelle cloud, og leverer det til visualiseringen.
Visualiseringen kan derefter bruge tokenet til at godkende i forhold til den respektive målgruppe, der repræsenterer backendtjenesten:

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

I den pbiviz.json fil skal du angive API-versionen til 5.9.1 eller nyere:

Den nyligt eksponerede AcquireAADTokenService indeholder to metoder:

  • acquireAADToken: Returnerer en godkendelsestokendata af typen AcquireAADTokenResult for visualiseringen eller null, hvis den 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 en af følgende rettighedsstatusser, der er knyttet til hentning af tokenet.

    • Tilladt: Rettigheden er tilladt i det aktuelle miljø.
    • NotDeclared: Rettighedserklæringen mangler i afsnittet visualiseringsfunktioner.
    • NotSupported: Rettigheden understøttes ikke i det aktuelle miljø.
    • DisabledBy Administration: Fabric-administratoren afviste brug af rettigheder.

Følgende eksempelkode viser, hvordan du henter et Microsoft Entra ID-token ved hjælp af 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

Overvejelser og begrænsninger

Tokenkøb er blokeret, hvis en af følgende betingelser gælder:

  • Lejerkontakten er slået fra.

  • Brugeren er ikke logget på (i Desktop).

  • ISV'en har ikke forhåndsgodkendt Power BI-programmet.

  • Formatet af rettighedsparameteren AADAuthentication er ugyldigt.

  • Visualiseringen er ikke offentligt godkendt eller er ikke en fejlfindingsvisualisering.

  • Visualiseringens backendtjeneste, der er konfigureret som målgruppen af visualiseringen, har ikke de nødvendige samtykker til Graph-API'en i forbrugerlejer ved hjælp af visualiseringen. Du kan få mere at vide om samtykke i lejeradministratorens samtykke.

Relateret indhold

Installation af Microsoft Entra ID-program