Authentifizierungs-API

Die Authentifizierungs-API ermöglicht Visuals das Abrufen von Microsoft Entra ID-Zugriffstoken (früher Azure AD) für angemeldete Benutzer*innen und erleichtert dadurch die Authentifizierung mit einmaligem Anmelden.

Power BI-Administrator*innen können die API über einen globalen Parameter aktivieren oder deaktivieren. Die Standardeinstellung blockiert (deaktiviert) die API.

Die API gilt nur für visuelle AppSource-Visuals und nicht für private Visuals. Visuals, die sich in der Entwicklung befinden, können im Debugmodus getestet werden, bevor sie veröffentlicht werden.

Unterstützte Umgebungen

Die folgenden Umgebungen werden unterstützt:

• Web
• Desktop
• RS Desktop
• Mobile

Nicht unterstützte Umgebungen

Die folgenden Umgebungen werden noch nicht unterstützt:

• RS-Dienst
• Eingebettete Analysen
• Teams

Verwenden der Authentifizierungs-API

Fügen Sie in der Datei capabilities.json für jede unterstützte Cloud die Berechtigung „AADAuthentication“ mit Ihrem in Microsoft Entra ID registrierten Anwendungs-URI hinzu. Fabric generiert ein Token gemäß der Zielgruppe, die für die aktuelle Cloud konfiguriert ist, und liefert es an das Visual.
Das Visual kann dann das Token für die Authentifizierung bei der jeweiligen Zielgruppe verwenden, die den Back-End-Dienst darstellt:

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

Legen Sie in der Datei pbiviz.json die API-Version auf 5.9.0 oder höher fest:

Das neu verfügbar gemachte AcquireAADTokenService-Element enthält zwei Methoden:

• acquireAADToken: Gibt für das Visual eine Authentifizierungstokennutzlast vom Typ AcquireAADTokenResult zurück oder Null, wenn es nicht abgerufen werden kann.

   /**
   * 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: Gibt einen der folgenden Berechtigungsstatus für den Abrufen des Tokens zurück.

  • Allowed: Die Berechtigung ist in der aktuellen Umgebung zulässig.
  • NotDeclared: Die Berechtigungsdeklaration fehlt im Abschnitt mit den Visualfunktionen.
  • NotSupported: Die Berechtigung wird in der aktuellen Umgebung nicht unterstützt.
  • DisabledByAdmin: Der*die Fabric-Administrator*in hat die Berechtigungsnutzung verweigert.

Im folgenden Beispielcode wird veranschaulicht, wie Sie ein Microsoft Entra ID-Token mithilfe der API abrufen:

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

Überlegungen und Einschränkungen

Der Tokenabruf wird blockiert, wenn eine der folgenden Bedingungen zutrifft:

• Der Mandantenparameter ist deaktiviert.

• Der Benutzer oder die Benutzerin ist nicht angemeldet (in Desktop).

• Der ISV hat die Power BI-Anwendung nicht vorab autorisiert.

• Das Format des AADAuthentication-Berechtigungsparameters ist ungültig.

• Das Visual ist nicht öffentlich genehmigt oder ist kein Debugvisual.

• Der Back-End-Dienst des Visuals, der als Zielgruppe durch das visuelle Element konfiguriert ist, verfügt nicht über entsprechende Einwilligungen für die Graph-API im Consumermandanten, der das Visual nutzt. Weitere Informationen zur Einwilligung finden Sie unter Mandantenadministratoreinwilligung.

Zugehöriger Inhalt

Setup der Microsoft Entra ID-Anwendung