Einbetten von Power BI-Inhalten mit Dienstprinzipal und Anwendungsgeheimnis

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.

• Erfahren Sie mehr über das Abrufen von Zugriffstoken aus Microsoft Entra ID mithilfe von geheimen Schlüsseln oder Zertifikaten.
• Befolgen Sie die Anweisungen in diesem Artikel und führen Sie dann die unter Einbetten von Power BI-Inhalten mit Dienstprinzipal und Zertifikat beschriebenen Schritte aus, um Ihre Lösung mithilfe eines Zertifikats zu 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

Sie können eine Microsoft Entra-App aus dem Azure-Portal oder mithilfe von PowerShell erstellen:

Erstellen einer App im Azure-Portal

1. Melden Sie sich beim Azure-Portal an.

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

   

3. Wählen Sie Neue Registrierung aus.

   

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.

   

7. Wählen Sie Zertifikate & Geheimnisse aus.

   

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

   

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.

    

    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 App mit PowerShell

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

• Installieren Sie die neueste Version von PowerShell.
• Installieren Sie Microsoft Graph-PowerShell-SDK.

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:

• Manuell (in Azure)
• Verwenden von PowerShell

Manuelles Erstellen einer Sicherheitsgruppe

Um eine Azure-Sicherheitsgruppe manuell zu erstellen, befolgen Sie die Anweisungen unter Erstellen einer einfachen Gruppe. Fügen Sie der Gruppe zurzeit keine Mitglieder hinzu.

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.

  

• 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.

  

  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 als Mitglied oder Administrator hat. Sie stellen diesen Zugriff bereit, indem Sie den Dienstprinzipal der App oder deren Sicherheitsgruppe zu Ihrem Arbeitsbereich hinzufügen.

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

• Manuell
• Verwenden von PowerShell
• Verwenden der Gruppen – Hinzufügen einer Gruppenbenutzer-API

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.

   

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.
• Nicht alle schreibgeschützten APIs werden vom Dienstprinzipal unterstützt. Um die Dienstprinzipalunterstützung für schreibgeschützte Administrator-APIs zu aktivieren, aktivieren Sie die Power BI-Dienst Administratoreinstellungen in Ihrem Mandanten. 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

• Registrieren einer Azure AD-App zum Einbetten von Power BI-Inhalten
• Tutorial: Einbetten von Power BI-Berichten, -Dashboards oder -Kacheln in eine Anwendung für Ihre Kunden
• Anwendungs- und Dienstprinzipalobjekte in Microsoft Entra ID