Freigeben über

Authentifizierungs-API

Die Authentifizierungs-API ermöglicht visuellen Benutzern das Abrufen von Microsoft Entra ID-Zugriffstoken (früher Azure AD) für angemeldete Benutzer, wodurch die Single Sign-On-Authentifizierung erleichtert wird.

Power BI-Administratoren können die API über einen globalen Switch aktivieren oder deaktivieren. Die Standardeinstellung blockiert (deaktiviert) die API.

Die API gilt nur für visuelle AppSource-Elemente und nicht für private visuelle Elemente. Visuelle Elemente, 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
  • Mobiltelefon

Nicht unterstützte Umgebungen

Die folgenden Umgebungen werden noch nicht unterstützt:

  • RS-Dienst
  • Eingebettete Analysen
  • Mannschaften

So verwenden Sie die Authentifizierungs-API

Fügen Sie in der capabilities.json die "AADAuthentication"-Berechtigung mit einer Microsoft Entra ID registrierten Anwendungs-URI für jede unterstützte Cloud hinzu. Fabric generiert ein Token entsprechend dem Benutzerkreis, der für die aktuelle Cloud konfiguriert ist, und liefert es an die grafische Darstellung.
Das visuelle Element kann dann das Token verwenden, um sich bei der jeweiligen Zielgruppe zu authentifizieren, die seinen Back-End-Dienst darstellt:

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

Legen Sie in der dateipbiviz.json die API-Version auf 5.9.1 oder höher fest:

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

  • acquireAADToken: Gibt eine Authentifizierungstokennutzlast vom Typ AcquireAADTokenResult für die Visualisierung oder null zurück, wenn sie 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 zurück, die dem Abrufen des Tokens zugeordnet sind.

    • Zulässig: Die Berechtigung ist in der aktuellen Umgebung zulässig.
    • NotDeclared: Die Berechtigungsdeklaration fehlt im Abschnitt mit visuellen Funktionen.
    • NotSupported: Die Berechtigung wird in der aktuellen Umgebung nicht unterstützt.
    • DisabledByAdmin: Der Fabric-Administrator hat die Verwendung von Berechtigungen verweigert.

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

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

Die Tokenerfassung wird blockiert, wenn eine der folgenden Bedingungen zutrifft:

  • Der Mandantenschalter ist deaktiviert.

  • Der Benutzer ist nicht angemeldet (in Desktop).

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

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

  • Das visuelle Element ist nicht öffentlich genehmigt oder kein Debug-visuelles Element.

  • Der Back-End-Dienst des visuellen Elements, vom visuellen Element als Zielgruppe konfiguriert, verfügt nicht über die entsprechenden Zustimmungen für die Graph API im Verbrauchermandanten, der das visuelle Element verwendet. Weitere Informationen zur Zustimmung finden Sie unter Zustimmung des Mandantenadministrators.

Verwandte Inhalte

Setup der Microsoft Entra-ID-Anwendung

  • Last updated on