Erwerb von Zugriffstoken

  • 8 Minuten

Das Abrufen eines Zugriffstokens, das Ihre App immer für das Einbetten von Power BI-Inhalten erfordert, bringt das Abrufen eines Azure AD-Tokens mit sich. Wenn Sie das Szenario Für Ihre Kunden nutzen, verwendet die App das Azure AD-Token, um ein Einbettungstoken zu generieren.

In aller Kürze:

  • Das Zugriffstoken für das Szenario Für Ihre Organisation ist das Azure AD-Token, das Ansprüche enthält, die Ihre App verwendet, um die erteilten Berechtigungen zu identifizieren.
  • Das Zugriffstoken für das Szenario Für Ihre Kunden ist ein Einbettungstoken, das Fakten zu den Power BI-Inhalten und zum Zugriff Ihrer App auf diese darstellt. Ihre App generiert das Einbettungstoken mithilfe eines Power BI-REST-API-Vorgangs, der ein Azure AD-Token erfordert

Erwerben von Azure AD-Token

Verwenden Sie die Microsoft Authentication Library (MSAL), um App-Logik zu entwickeln, die Azure AD-Token bei der Microsoft Identity Platform abruft. MSAL unterstützt verschiedene Anwendungsarchitekturen und -plattformen einschließlich .NET, JavaScript, Java, Python, Android und iOS.

Tipp

Beim Entwickeln einer ASP.NET Core-Web-App empfehlen wir, die Microsoft Identity-Bibliothek für Web-Authentifizierung zu verwenden. Diese Bibliothek ist eine Reihe von Paketen, die als Microsoft.Identity.Web bezeichnet werden. Sie können sie aus NuGet oder Visual Studio installieren.

Es gibt verschiedene Techniken, um ein Azure AD-Token mithilfe von MSAL abzurufen. Für einige ist eine Benutzerinteraktion über einen Webbrowser erforderlich, während andere ganz ohne Benutzerinteraktion auskommen. Im Allgemeinen hängt die Methode zum Anfordern eines Azure AD-Tokens davon ab, ob es sich bei der Anwendung um eine öffentliche Clientanwendung, (z. B. eine Desktopanwendung oder eine mobile App) oder um eine vertrauliche Clientanwendung (z. B. eine Web-App) handelt. Das Einbettungsszenario wirkt sich ebenfalls auf Ihre Wahl aus.

Es gehört nicht zu den Zielen dieser Lerneinheit, die Techniken zum Abrufen von Azure AD-Token zu beschreiben. Weitere Informationen finden Sie unter Abrufen und Zwischenspeichern von Token mithilfe der Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL).

Tipp

Wenn die Beispiel-Apps für das Einbettungs-Setuptool Ihren App-Anforderungen entsprechen, können Sie den Beispielcode kopieren, um Azure AD-Token zu erwerben.

Damit Ihre App Azure AD-Token erwerben kann, sollte ihre Konfigurationsdatei die folgenden Einstellungen enthalten:

  • TenantId: Nur für den Dienstprinzipal erforderlich. Das ist Ihre Azure AD-TenantID.
  • ClientId – Erforderlich. Dies ist die ApplicationID (ClientID) Ihrer Azure AD-App.
  • ClientSecret oder ClientCertificate: Nur für den Dienstprinzipal erforderlich.
  • PbiUsername: Nur für das Hauptbenutzerkonto erforderlich.
  • PbiPassword: Nur für das Hauptbenutzerkonto erforderlich.

Wichtig

Unabhängig davon, ob Sie Zertifikate, Clientschlüssel oder Benutzerkonto-Anmeldeinformationen verwenden, müssen Sie Schritte ergreifen, um sie vor nicht autorisiertem Zugriff und nicht autorisierter Verwendung zu schützen. Wir empfehlen die Verwendung von Azure Key Vault, das Kryptografieschlüssel, Zertifikate und Geheimnisse in der Cloud schützt.

Abrufen von Einbettungstoken

Verwenden Sie den GenerateTokenRequestV2-Vorgang der Microsoft Power BI-REST-API, um ein Einbettungstoken anzufordern. Es gibt andere verwandte Vorgänge, die Einbettungstoken für andere Power BI-Inhaltstypen generieren. Alle API-Vorgänge erfordern ein Azure AD-Token.

Tipp

Beim Entwickeln einer .NET-App wird empfohlen, das Microsoft.PowerBI.Api-Paket zu installieren. Sie können es aus NuGet oder Visual Studio installieren.

Betrachten Sie den folgenden Code, der zeigt, wie Einbettungstoken generiert werden. Das Token enthält Ansprüche für alle Berichte und Datasets aus einem Arbeitsbereich und ermöglicht App-Benutzern das Erstellen oder Bearbeiten von Berichten. Folgendes wird durchgeführt:

  1. Herstellen einer Verbindung mit Power BI
  2. Deklarieren einer Variable mit dem Namen reportTokenRequests zum Speichern von Berichtstokenanforderungen
  3. Aufzählen aller Berichte im Arbeitsbereich und Erstellen einer Liste von EmbeddedReport-Objekten (unter Verwendung einer Hilfsklasse). Jedes Objekt beschreibt die ID, den Namen und die Einbettungs-URL des Berichts. Die App erfordert die ID des Berichts zum Generieren eines Tokens. Der Name wird benötigt, um den Benutzer*innen in einem Menü angezeigt zu werden, und die Einbettungs-URL wird benötigt, um den Bericht einzubetten. Der Code fügt der Variable reportTokenRequests eine Berichtstokenanforderung hinzu, was die Berichtsbearbeitung ermöglicht.
  4. Deklarieren einer Variable mit dem Namen datasetTokenRequests zum Speichern von Datasettokenanforderungen
  5. Aufzählen aller Datasets im Arbeitsbereich und Erstellen einer Liste von EmbeddedDataset-Objekten (unter Verwendung einer Hilfsklasse). Jedes Objekt beschreibt die ID, den Namen und die Einbettungs-URL des Datasets. Die App erfordert die ID des Datasets zum Generieren eines Tokens. Der Name wird benötigt, um den Benutzer*innen in einem Menü angezeigt zu werden, und die Einbettungs-URL wird benötigt, um das Dataset einzubetten. Der Code fügt der Variable datasetTokenRequests eine Datasettokenanforderung hinzu.
  6. Generieren einer Arbeitsbereich-Tokenanforderung (erforderlich, wenn Benutzer Berichte erstellen), die der workspaceRequests-Variable hinzugefügt wird.
  7. Verwenden der Methode GenerateTokenRequestV2, um die Berichtstokenanforderungen, Datasettokenanforderungen und die Arbeitsbereich-Tokenanforderung zusammenzubündeln.
  8. Verwenden von GenerateTokenAsync zum Generieren eines Einbettungstokens
  9. Speichern des Einbettungstokens in einer Zeichenfolgenvariable
// Connect to Power BI
var client = GetPowerBiClient();

// Get reports in the workspace
var reports = (await client.Reports.GetReportsInGroupAsync(_workspaceId)).Value;

var reportList = new List<EmbeddedReport>();
var reportTokenRequests = new List<GenerateTokenRequestV2Report>();

foreach (var report in reports)
{
    reportList.Add(new EmbeddedReport
    {
        Id = report.Id.ToString(),
        Name = report.Name,
        EmbedUrl = report.EmbedUrl
    });

    reportTokenRequests.Add(new GenerateTokenRequestV2Report(report.Id, allowEdit: true));
}

// Get datasets in the workspace
var datasets = (await client.Datasets.GetDatasetsInGroupAsync(_workspaceId)).Value;

var datasetList = new List<EmbeddedDataset>();
var datasetTokenRequests = new List<GenerateTokenRequestV2Dataset>();

foreach (var dataset in datasets)
{
    datasetList.Add(new EmbeddedDataset
    {
        Id = dataset.Id.ToString(),
        Name = dataset.Name,
        EmbedUrl = dataset.QnaEmbedURL
    });

    datasetTokenRequests.Add(new GenerateTokenRequestV2Dataset(dataset.Id));
}

// Generate token request for the workspace
var workspaceRequests = new GenerateTokenRequestV2TargetWorkspace[] {
    new GenerateTokenRequestV2TargetWorkspace(_workspaceId)
};

// Bundle token requests for reports, datasets, and the workspace
var tokenRequest = new GenerateTokenRequestV2(
    reports: reportTokenRequests,
    datasets: datasetTokenRequests,
    targetWorkspaces: workspaceRequests
);

// Generate the embed token
string embedToken = (await client.EmbedToken.GenerateTokenAsync(tokenRequest)).Token;

Die App sollte den embedToken-Variablenwert an die einbettende HTML-Seite ausgeben. Anschließend kann das Einbettungstoken von clientseitiger Logik verwendet werden, um Inhalte in ein div-Element einzubetten.

Hinweis

Wenn Sie erfahren möchten, wie Power BI-Inhalte eingebettet werden, arbeiten Sie das Modul Einbetten von Power BI-Inhalten durch.

Damit Ihre App Einbettungstoken erwerben kann, sollte ihre Config-Datei Details zu den einbettungsfähigen Inhalten enthalten. Sie kann bestimmte ReportIDs und DatasetIDs oder allgemeiner die GroupIDs der Arbeitsbereiche enthalten, in denen einbettungsfähige Inhalte vorhanden sind.

Weitere Informationen finden Sie unter Einbettungstoken – Token generieren.

Zugriffstoken für die Aktualisierung

Zugriffstoken weisen eine Ablaufzeit auf. Nach der Generierung verbleibt App-Benutzern eine begrenzte Zeit für die Interaktion mit Power BI-Inhalten, die sie verwenden. Damit Ihren App-Benutzern eine kontinuierliche Benutzererfahrung zur Verfügung steht, sollte Ihre App Zugriffstoken mithilfe der Power BI-Client-API aktualisieren, bevor sie ablaufen.

Hinweis

Wenn Sie mehr über die Power BI-Client-APIs erfahren möchten, arbeiten Sie das Modul Integrieren von Inhalten mit den Power BI-Client-APIs durch.

Weitere Informationen finden Sie unter Zugriffstoken aktualisieren.

Erkunden weiterer Ressourcen

Weitere Informationen finden Sie in der Videoreihe Power BI Developers Guide to Azure AD Security (Power BI-Entwicklerleitfaden zur Azure AD Sicherheit). Diese Reihe umfasst sechs Videos, in denen die Theorie ausführlich behandelt wird. Ted Pattison, der Mitglied im Power BI Customer Advisory Team (CAT) bei Microsoft ist, hat diese Videoreihe produziert.