Einbetten von Power BI-Inhalten mit Dienstprinzipal und Anwendungsgeheimnis

  • Artikel

Der Dienstprinzipal ist eine Authentifizierungsmethode, die verwendet kann, um einer Microsoft Entra-Anwendung den Zugriff auf die Inhalte und die APIs im Power BI-Dienst zu ermöglichen.

Wenn Sie eine Microsoft Entra-App erstellen, wird ein Dienstprinzipalobjekt erstellt. Das Dienstprinzipalobjekt, das manchmal auch einfach als Dienstprinzipal bezeichnet wird, ermöglicht Microsoft Entra ID die Authentifizierung Ihrer App. Nach der Authentifizierung kann die App auf Microsoft Entra-Mandantenressourcen zugreifen.

Zum Authentifizieren verwendet der Dienstprinzipal die Anwendungs-ID der Microsoft Entra-App und eines der folgenden Elemente:

  • Ein Zertifikat
  • Ein Anwendungsgeheimnis

In diesem Artikel wird die Dienstprinzipal-Authentifizierung mit einer Anwendungs-ID und einem Anwendungsgeheimnis beschrieben.

Hinweis

Es wird empfohlen, dass Sie Ihre Back-End-Dienste anstatt mit geheimen Schlüsseln mit Zertifikaten sichern.

Methode

Führen Sie die folgenden Schritte aus, um den Dienstprinzipal und eine Anwendungs-ID für Embedded Analytics zu verwenden. In den folgenden Abschnitten werden diese Schritte ausführlich behandelt.

  1. Erstellen Sie eine Microsoft Entra-App.

    1. Erstellen Sie ein Geheimnis für Ihre Microsoft Entra-App.
    2. Rufen Sie die Anwendungs-ID und das Anwendungsgeheimnis der App ab.

    Hinweis

    Diese Schritte werden in Schritt 1 beschrieben. Weitere Informationen zum Erstellen einer Microsoft Entra-App finden Sie unter Erstellen einer Microsoft Entra-App.

  2. Erstellen einer Microsoft Entra Sicherheitsgruppe.

  3. Aktivieren Sie die Administratoreinstellungen für den Power BI-Dienst.

  4. Fügen Sie Ihrem Arbeitsbereich den Dienstprinzipal hinzu.

  5. Betten Sie Ihre Inhalte ein.

Wichtig

Für eine Microsoft Entra-Anwendung müssen Sie keine delegierten Berechtigungen oder Anwendungsberechtigungen im Azure-Portal konfigurieren, wenn sie für einen Dienstprinzipal erstellt wurde. Wenn Sie eine Microsoft Entra-Anwendung für einen Dienstprinzipal für den Zugriff auf die Power BI-REST-API erstellen, wird empfohlen, das Hinzufügen von Berechtigungen zu vermeiden. Sie werden nie verwendet und können schwer zu behebende Fehler verursachen.

Schritt 1: Erstellen einer Microsoft Entra-App

Erstellen Sie eine Microsoft Entra-App mit einer der folgenden Methoden:

Erstellen einer Microsoft Entra-App im Azure-Portal

  1. Melden Sie sich beim Azure-Portal an.

  2. Suchen Sie nach App-Registrierungen, und klicken Sie darauf.

    Screenshot of the Azure portal, with app registration in the search box. That box and the App registrations icon are highlighted.

  3. Wählen Sie Neue Registrierung aus.

    Screenshot of the App registrations page in the Azure portal. New registration is highlighted.

  4. Füllen Sie die erforderlichen Informationen aus:

    • Name – Geben Sie einen Namen für Ihre Anwendung ein.
    • Unterstützte Kontotypen – Wählen Sie die unterstützten Kontotypen aus.
    • (Optional) Umleitungs-URI – Geben Sie bei Bedarf einen URI ein.

  5. Wählen Sie Registrieren.

  6. Nachdem Sie Ihre App registriert haben, ist die Anwendungs-ID auf der Registerkarte Übersicht verfügbar. Kopieren und speichern Sie die Anwendungs-ID zur späteren Verwendung.

    Screenshot of the Overview page of the new app. The Application ID is indecipherable and is highlighted.

  7. Wählen Sie Zertifikate & Geheimnisse aus.

    Screenshot of the Overview page of the new app. On the navigation pane, Certificates & secrets is highlighted.

  8. Wählen Sie Neuer geheimer Clientschlüssel.

    Screenshot that shows part of the Certificates & secrets page for the app. Under Client secrets, the New client secret button is highlighted.

  9. Geben Sie im Fenster Geheimen Clientschlüssel hinzufügen eine Beschreibung ein, geben Sie an, wann der geheime Clientschlüssel ablaufen soll, und wählen Sie Hinzufügen aus.

  10. Kopieren und speichern Sie den Wert für den geheimen Clientschlüssel.

    Screenshot of the Certificates & secrets page for the app. Under Client secrets, a new secret is visible. Its indecipherable value is highlighted.

    Hinweis

    Wenn Sie dieses Fenster schließen, wird der Wert „Geheimer Clientschlüssel“ ausgeblendet, und Sie können ihn nicht erneut anzeigen oder kopieren.

Erstellen einer Microsoft Entra-App mithilfe von PowerShell

Das folgende Beispielskript PowerShell erstellt eine neue Microsoft Entra-App und einen Dienstprinzipal. Bevor Sie dieses Skript ausführen:

Notieren Sie sich nach der Ausführung des Skripts die folgenden Informationen in der Skriptausgabe:

  • Die Client-ID der neuen App
  • Die Objekt-ID des neuen Dienstprinzipals
  • Der Wert des Dienstprinzipal-Geheimnisses
# Sign in as a user who's allowed to create an app.
Connect-MgGraph -Scopes "Application.ReadWrite.All" 

# Create a new Azure AD web application.
$web = @{
    RedirectUris = "https://localhost:44322"
    HomePageUrl = "https://localhost:44322"
}
$params = @{
    DisplayName = "myAzureADApp"
    Web = $($web)
}
$app = New-MgApplication @params
Write-Host "Client ID of new app: " $($app.AppId)

# Create a service principal.
$ServicePrincipalID=@{
  "AppId" = $($app.AppId)
  }
$sp = New-MgServicePrincipal -BodyParameter $($ServicePrincipalId)
Write-Host "Object ID of new service principal: " $($sp.Id)

# Create a key for the service principal.
$credential = Add-MgServicePrincipalPassword -ServicePrincipalId $($sp.Id)
Write-Host "Credential of new service principal: " $($credential.SecretText)

Schritt 2: Erstellen einer Microsoft Entra-Sicherheitsgruppe

Ihr Dienstprinzipal hat keinen Zugriff auf Ihre Inhalte und APIs in Power BI. Erstellen Sie eine Sicherheitsgruppe in Microsoft Entra ID, um dem Dienstprinzipal Zugriff zu gewähren. Fügen Sie dann der Sicherheitsgruppe den von Ihnen erstellten Dienstprinzipal hinzu.

Hinweis

Wenn Sie den Dienstprinzipalzugriff für die gesamte Organisation aktivieren möchten, überspringen Sie diesen Schritt.

Eine Microsoft Entra-Sicherheitsgruppe kann auf zwei Arten erstellt werden:

Manuelles Erstellen einer Sicherheitsgruppe

Befolgen Sie die Anweisungen unter Erstellen einer Basisgruppe und Hinzufügen von Mitgliedern, um eine Azure-Sicherheitsgruppe manuell zu erstellen.

Erstellen einer Sicherheitsgruppe mit PowerShell

Das folgende Beispielskript erstellt eine neue Sicherheitsgruppe. Außerdem wird der neuen Sicherheitsgruppe der zuvor erstellte Dienstprinzipal hinzugefügt.

  • Ersetzen Sie vor dem Ausführen des Skripts <app-client-ID> durch die Client-ID, die Sie zuvor für Ihre neue App aufgezeichnet haben.
  • Notieren Sie sich nach dem Ausführen des Skripts die Objekt-ID der neuen Sicherheitsgruppe, die Sie in der Skriptausgabe finden.
# Sign in as an admin.
Connect-MgGraph -Scopes "Application.ReadWrite.All"

# Get the service principal that you created earlier.
$servicePrincipal = Get-MgServicePrincipal -Filter "AppId eq '<app-client-ID>'"

# Create an Azure AD security group.
$group = New-MgGroup -DisplayName "securitygroup1" -SecurityEnabled -MailEnabled:$False -MailNickName "notSet"
Write-Host "Object ID of new security group: " $($group.Id)

# Add the service principal to the group.
New-MgGroupMember -GroupId $($group.Id) -DirectoryObjectId $($servicePrincipal.Id)

Schritt 3: Aktivieren der Administratoreinstellungen für den Power BI-Dienst

Damit eine Microsoft Entra-App auf die Power BI-Inhalte und -APIs zugreifen kann, muss ein Power BI-Administrator die folgenden Einstellungen aktivieren:

  • Inhalt in Apps einbetten
  • Dienstprinzipalen die Verwendung von Power BI-APIs gestatten

Navigieren Sie im Power BI-Admin-Portal zu Mandanteneinstellungen und scrollen Sie nach unten zu Entwicklereinstellungen.

  • Aktivieren Sie Inhalte in Apps einbetten entweder für die gesamte Organisation oder für die bestimmte Sicherheitsgruppe, die Sie in Microsoft Entra ID erstellt haben.

    Screenshot of the Developer settings in the Tenant settings section of the Admin portal. The option for embedding content in apps is turned on.

  • Aktivieren Sie Dienstprinzipalen die Verwendung von Power BI-APIs gestatten entweder für die gesamte Organisation oder für die spezifische Sicherheitsgruppe, die Sie in Microsoft Entra ID erstellt haben.

    Screenshot of the Developer settings section. The option for allowing service principals to use Power BI APIs is turned on for one security group.

    Wichtig

    Dienstprinzipale haben Zugriff auf alle Mandanteneinstellungen, für die sie aktiviert wurden. Abhängig von Ihren Administratoreinstellungen umfasst dies bestimmte Sicherheitsgruppen oder die gesamte Organisation.

    Sie können den Dienstprinzipalzugriff auf bestimmte Mandanteneinstellungen einschränken, indem Sie den Zugriff nur für bestimmte Sicherheitsgruppen zulassen. Alternativ können Sie eine dedizierte Sicherheitsgruppe für Dienstprinzipale erstellen und sie von den gewünschten Mandanteneinstellungen ausschließen.

Schritt 4: Hinzufügen des Dienstprinzipals zu Ihrem Arbeitsbereich

Ihre Microsoft Entra-App kann nur dann auf Ihre Power BI-Berichte, Dashboards und semantischen Modelle zugreifen, wenn sie Zugriff auf Ihren Power BI-Arbeitsbereich hat. Sie gewähren diesen Zugriff, indem Sie dem Arbeitsbereich als Mitglied oder Administrator den Dienstprinzipal oder die Sicherheitsgruppe der App hinzufügen.

Es gibt drei Möglichkeiten zum Hinzufügen eines Dienstprinzipals oder dessen Sicherheitsgruppe zu Ihrem Arbeitsbereich:

Manuelles Hinzufügen eines Dienstprinzipals oder einer Sicherheitsgruppe

  1. Scrollen Sie im Power BI-Dienst zu dem Arbeitsbereich, für den Sie den Zugriff aktivieren möchten. Wählen Sie im Menü Mehr die Option Arbeitsbereichszugriff aus.

    Screenshot that shows the expanded More menu for a workspace. On that menu, Workspace access is highlighted.

  2. Fügen Sie im Bereich Zugriff unter Administratoren, Mitglieder oder Mitwirkende hinzufügen eine der folgenden Elemente hinzu:

    • Ihren Dienstprinzipal: Der Name Ihres Dienstprinzipals ist der Anzeigename Ihrer Microsoft Entra-App, der auf der Registerkarte „Übersicht“ der Microsoft Entra-App angezeigt wird.
    • die Sicherheitsgruppe, die Ihren Dienstprinzipal enthält:

  3. Wählen Sie im Dropdown-Menü Mitglied oder Administrator aus.

  4. Wählen Sie Hinzufügen.

Hinzufügen eines Dienstprinzipals oder einer Sicherheitsgruppe mithilfe von PowerShell

Die folgenden Abschnitte enthalten PowerShell-Beispielskripts zum Hinzufügen eines Dienstprinzipals und einer Sicherheitsgruppe zu einem Power BI-Arbeitsbereich als Mitglied.

Hinzufügen eines Dienstprinzipals als Mitglied eines Arbeitsbereichs mithilfe von PowerShell

Das folgende Skript fügt einen Dienstprinzipal als Mitglied eines Arbeitsbereichs hinzu. Bevor Sie das Skript ausführen:

  • Ersetzen Sie <service-principal-object-ID> durch die Objekt-ID, die Sie zuvor für Ihren neuen Dienstprinzipal aufgezeichnet haben.
  • Ersetzen Sie <workspace-name> durch den Namen des Arbeitsbereichs, auf den Sie dem Dienstprinzipal Zugriff gewähren möchten.
# Sign in to Power BI.
Login-PowerBI

# Set up the service principal ID.
$SPObjectID = "<service-principal-object-ID>"

# Get the workspace.
$pbiWorkspace = Get-PowerBIWorkspace -Filter "name eq '<workspace-name>'"

# Add the service principal to the workspace.
Add-PowerBIWorkspaceUser -Id $($pbiWorkspace.Id) -AccessRight Member -PrincipalType App -Identifier $($SPObjectID)

Hinzufügen einer Sicherheitsgruppe als Mitglied eines Arbeitsbereichs mit PowerShell

Das folgende Skript fügt eine Sicherheitsgruppe als Mitglied eines Arbeitsbereichs hinzu. Bevor Sie das Skript ausführen:

  • Ersetzen Sie <security-group-object-ID> durch die Objekt-ID, die Sie zuvor für Ihre neue Sicherheitsgruppe aufgezeichnet haben.
  • Ersetzen Sie <workspace-name> durch den Namen des Arbeitsbereichs, auf den Sie der Sicherheitsgruppe Zugriff gewähren möchten.
# Sign in to Power BI.
Login-PowerBI

# Set up the security group object ID.
$SGObjectID = "<security-group-object-ID>"

# Get the workspace.
$pbiWorkspace = Get-PowerBIWorkspace -Filter "name eq '<workspace-name>'"

# Add the security group to the workspace.
Add-PowerBIWorkspaceUser -Id $($pbiWorkspace.Id) -AccessRight Member -PrincipalType Group -Identifier $($SGObjectID)

Schritt 5: Einbetten der Inhalte

Sie können Ihre Inhalte in Ihre eigene Anwendung oder in eine Beispielanwendung einbetten.

Nach dem Einbetten Ihrer Inhalte können Sie zur Produktion wechseln.

Hinweis

Führen Sie die unter Einbetten von Power BI-Inhalten mit Dienstprinzipal und Zertifikat beschriebenen Schritte aus, um Ihre Inhalte mit einem Zertifikat zu sichern.

Überlegungen und Einschränkungen

  • Mein Arbeitsbereich wird nicht unterstützt, wenn ein Dienstprinzipal verwendet wird.
  • Eine Kapazität ist erforderlich, um in die Produktionsphase wechseln zu können.
  • Sie können sich nicht mit dem Dienstprinzipal beim Power BI-Portal anmelden.
  • Power BI-Administratorberechtigungen sind erforderlich, um Dienstprinzipale in den Entwicklereinstellungen im Power BI-Verwaltungsportal aktivieren zu können.
  • Für Ihre Organisation eingebettete Anwendungen können keine Dienstprinzipale verwenden.
  • Die Verwaltung von Datenflüssen wird nicht unterstützt.
  • Der Dienstprinzipal unterstützt nur einige schreibgeschützte Administrator-APIs. Um die Dienstprinzipalunterstützung für schreibgeschützte Admin-APIs zu aktivieren, müssen Sie die Administratoreinstellungen des Power BI-Diensts in Ihrem Mandanten aktivieren. Weitere Informationen finden Sie unter Aktivieren der Dienstprinzipalauthentifizierung für schreibgeschützte Administrator-APIs.
  • Wenn Sie einen Dienstprinzipal mit einer Azure Analysis Services-Datenquelle verwenden, muss der Dienstprinzipal selbst über Azure Analysis Services-Instanzberechtigungen verfügen. Die Verwendung einer Sicherheitsgruppe, die das Dienstprinzipal enthält, funktioniert nicht.

Zugehöriger Inhalt