Godkendelses-API

Autentificerings-API'et gør det muligt for visuelle enheder at opnå Microsoft Entra ID (tidligere kendt som Azure AD) adgangstoks for indloggede brugere, hvilket muliggør single sign-on autentificering.

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

API'en er kun relevant for AppSource-visuals og ikke for private visuals. Visuelle ting, der er under udvikling, kan testes i debug-tilstand, før de udgives.

Understøttede miljøer

Følgende miljøer understøttes:

• web
• Skrivebord
• RS Desktop
• Mobile

Uunderstøttede miljøer

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

• RS-tjeneste
• Integreret analyse
• Teams

Sådan bruger du Autentificerings-API'et

I capabilities.json-filen tilføjes "AADAuthentikation"-privilegiet med en Microsoft Entra ID-registreret applikations-URI for hver understøttet cloud. Fabric genererer et token i henhold til målgruppen, der er konfigureret for den aktuelle cloud, og leverer det til det visuelle.
Det visuelle kan derefter bruge tokenet til at autentificere mod den respektive målgruppe og repræsentere sin backend-tjeneste:

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

I pbiviz.json-filen skal API-versionen sættes til 5.9.1 eller højere:

Den nyligt afslørede AcquireAADTokenService indeholder to metoder:

• acquireAADToken: Returnerer en autentificeringstoken-payload af typen AcquireAADTokenResult for det visuelle 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 privilegiestatusser, der er forbundet med at erhverve tokenet.

  • Tilladt: Privilegiet er tilladt i det nuværende miljø.
  • Ikke-erklæret: Privilegieerklæringen mangler i afsnittet om visuelle kapabiliteter.
  • NotSupported: Privileget understøttes ikke i det nuværende miljø.
  • DisabledByAdmin: Fabric-administratoren nægtede brug af privilegier.

Følgende eksempelkode demonstrerer, hvordan man får fat i et Microsoft Entra ID-token ved hjælp af 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 

Overvejelser og begrænsninger

Token-erhvervelse blokeres, hvis en af følgende betingelser gælder:

• Lejerkontakten er slået fra.

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

• ISV'en forhåndsgodkendte ikke Power BI-applikationen.

• Formatet for AADAuthentication-privilegieparameteren er ugyldigt.

• Visualen er ikke offentligt godkendt eller en debug-visual.

• Den visuelle backend-service, konfigureret som målgruppen af visualen, har ikke passende samtykker til Graph API'en i forbrugerlejeren, der bruger visualen. For mere om samtykke, se lejer administrator samtykke.

Relateret indhold

Microsoft Entra ID applikationsopsætning