Power BI-inhoud insluiten met service-principal en een toepassingsgeheim

  • Artikel

Service-principal is een verificatiemethode die kan worden gebruikt om een Microsoft Entra-toepassing toegang te geven tot Power BI-service inhoud en API's.

Wanneer u een Microsoft Entra-app maakt, wordt er een service-principal-object gemaakt. Het service-principal-object, ook wel service-principal genoemd, stelt Microsoft Entra-id in staat om uw app te verifiëren. Nadat deze is geverifieerd, heeft de app toegang tot microsoft Entra-tenantbronnen.

Voor verificatie gebruikt de service-principal de toepassings-id van de Microsoft Entra-app en een van de volgende opties:

  • Een certificaat
  • Een toepassingsgeheim

In dit artikel worden service-principalverificatie beschreven met behulp van een toepassings-id en een toepassingsgeheim.

Notitie

U wordt aangeraden uw back-endservices te beveiligen met behulp van certificaten, in plaats van geheime sleutels.

Wijze

Als u service-principal en een toepassings-id voor ingesloten analyses wilt gebruiken, voert u de volgende stappen uit. In volgende secties worden deze stappen gedetailleerd beschreven.

  1. Maak een Microsoft Entra-app.

    1. Maak een geheim voor uw Microsoft Entra-app.
    2. Haal de toepassings-id en het toepassingsgeheim van de app op.

    Notitie

    Deze stappen worden beschreven in stap 1. Zie Een Microsoft Entra-app maken voor meer informatie over het maken van een Microsoft Entra-app.

  2. Maak een Microsoft Entra-beveiligingsgroep.

  3. Schakel de Power BI-service-beheerinstellingen in.

  4. Voeg de service-principal toe aan uw werkruimte.

  5. Uw inhoud insluiten.

Belangrijk

Voor een Microsoft Entra-toepassing hoeft u geen gedelegeerde machtigingen of toepassingsmachtigingen te configureren in Azure Portal wanneer deze is gemaakt voor een service-principal. Wanneer u een Microsoft Entra-toepassing voor een service-principal maakt voor toegang tot de Power BI REST API, wordt u aangeraden geen machtigingen toe te voegen. Ze worden nooit gebruikt en kunnen fouten veroorzaken die moeilijk kunnen worden opgelost.

Stap 1: Een Microsoft Entra-app maken

Maak een Microsoft Entra-app met behulp van een van de volgende methoden:

Een Microsoft Entra-app maken in Azure Portal

  1. Meld u aan bij de Azure-portal.

  2. Zoek en selecteer App-registraties.

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

  3. Selecteer Nieuwe registratie.

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

  4. Vul de vereiste gegevens in:

    • Naam : voer een naam in voor uw toepassing.
    • Ondersteunde accounttypen : selecteer ondersteunde accounttypen.
    • (Optioneel) Omleidings-URI : voer indien nodig een URI in.

  5. Selecteer Registreren.

  6. Nadat u uw app hebt geregistreerd, is de toepassings-id beschikbaar op het tabblad Overzicht . Kopieer en sla de toepassings-id op voor later gebruik.

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

  7. Selecteer Certificaten en geheimen.

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

  8. Selecteer Nieuw clientgeheim.

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

  9. Voer in het venster Een clientgeheim toevoegen een beschrijving in, geef op wanneer u het clientgeheim wilt laten verlopen en selecteer Toevoegen.

  10. Kopieer de clientgeheimwaarde en sla deze op.

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

    Notitie

    Nadat u dit venster hebt verlaten, is de waarde van het clientgeheim verborgen en kunt u deze niet meer weergeven of kopiëren.

Een Microsoft Entra-app maken met behulp van PowerShell

Met het volgende PowerShell-voorbeeldscript maakt u een nieuwe Microsoft Entra-app en een service-principal. Voordat u dit script uitvoert:

Nadat het script is uitgevoerd, noteert u de volgende informatie in de scriptuitvoer:

  • De client-id van de nieuwe app
  • De object-id van de nieuwe service-principal
  • De waarde van het geheim van de service-principal
# 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)

Stap 2: een Microsoft Entra-beveiligingsgroep maken

Uw service-principal heeft geen toegang tot uw Power BI-inhoud en API's. Als u de service-principal toegang wilt geven, maakt u een beveiligingsgroep in Microsoft Entra-id. Voeg vervolgens de service-principal toe die u hebt gemaakt aan die beveiligingsgroep.

Notitie

Als u service-principaltoegang wilt inschakelen voor de hele organisatie, slaat u deze stap over.

Er zijn twee manieren om een Microsoft Entra-beveiligingsgroep te maken:

Handmatig een beveiligingsgroep maken

Als u handmatig een Azure-beveiligingsgroep wilt maken, volgt u de instructies in Een basisgroep maken en voegt u leden toe.

Een beveiligingsgroep maken met behulp van PowerShell

Met het volgende voorbeeldscript wordt een nieuwe beveiligingsgroep gemaakt. Ook wordt de service-principal die u eerder hebt gemaakt, toegevoegd aan de nieuwe beveiligingsgroep.

  • Voordat u het script uitvoert, vervangt <app-client-ID> u de client-id die u eerder hebt vastgelegd voor uw nieuwe app.
  • Nadat u het script hebt uitgevoerd, noteert u de object-id van de nieuwe beveiligingsgroep, die u kunt vinden in de scriptuitvoer.
# 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)

Stap 3: de Power BI-service-beheerinstellingen inschakelen

Voor toegang tot de Power BI-inhoud en API's moet een Power BI-beheerder de volgende instellingen inschakelen voor een Microsoft Entra-app:

  • Inhoud in apps insluiten
  • Toestaan dat service-principals gebruikmaken van API's van Power BI

Ga in de Power BI Beheer-portal naar Tenantinstellingen en schuif omlaag naar Instellingen voor ontwikkelaars.

  • Schakel Inhoud insluiten in apps in voor de hele organisatie of voor de specifieke beveiligingsgroep die u hebt gemaakt in Microsoft Entra-id.

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

  • Schakel Service-principals in om API van Power BI te gebruiken voor de hele organisatie of voor de specifieke beveiligingsgroep die u in Microsoft Entra-id hebt gemaakt.

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

    Belangrijk

    Service-principals hebben toegang tot alle tenantinstellingen waarvoor ze zijn ingeschakeld. Afhankelijk van uw beheerdersinstellingen omvat dit specifieke beveiligingsgroepen of de hele organisatie.

    Als u de toegang van de service-principal tot specifieke tenantinstellingen wilt beperken, staat u alleen toegang toe tot specifieke beveiligingsgroepen. U kunt ook een toegewezen beveiligingsgroep maken voor service-principals en deze uitsluiten van de gewenste tenantinstellingen.

Stap 4: De service-principal toevoegen aan uw werkruimte

Uw Microsoft Entra-app heeft alleen toegang tot uw Power BI-rapporten, -dashboards en -semantische modellen wanneer deze toegang heeft tot uw Power BI-werkruimte. U geeft deze toegang door de service-principal of beveiligingsgroep van de app als lid of beheerder toe te voegen aan uw werkruimte.

Er zijn drie manieren om een service-principal of de bijbehorende beveiligingsgroep toe te voegen aan uw werkruimte:

Handmatig een service-principal of beveiligingsgroep toevoegen

  1. Schuif in de Power BI-service naar de werkruimte waarvoor u toegang wilt inschakelen. Selecteer werkruimtetoegang in het menu Meer.

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

  2. Voeg in het deelvenster Access onder Beheerders, leden of inzenders toevoegen een van de volgende handelingen toe:

    • Uw service-principal. De naam van uw service-principal is de weergavenaam van uw Microsoft Entra-app, zoals deze wordt weergegeven op het tabblad Overzicht van uw Microsoft Entra-app.
    • De beveiligingsgroep die uw service-principal bevat.

  3. Selecteer Lid of Beheer in de vervolgkeuzelijst.

  4. Selecteer Toevoegen.

Een service-principal of beveiligingsgroep toevoegen met behulp van PowerShell

De volgende secties bevatten voorbeelden van PowerShell-scripts voor het toevoegen van een service-principal en een beveiligingsgroep aan een Power BI-werkruimte als lid.

Een service-principal toevoegen als werkruimtelid met behulp van PowerShell

Met het volgende script wordt een service-principal toegevoegd als lid van de werkruimte. Voordat u het script uitvoert:

  • Vervang door <service-principal-object-ID> de object-id die u eerder hebt vastgelegd voor uw nieuwe service-principal.
  • Vervang <workspace-name> door de naam van de werkruimte waartoe u de service-principal toegang wilt geven.
# 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)

Een beveiligingsgroep toevoegen als werkruimtelid met behulp van PowerShell

Met het volgende script wordt een beveiligingsgroep toegevoegd als lid van de werkruimte. Voordat u het script uitvoert:

  • Vervang door <security-group-object-ID> de object-id die u eerder hebt vastgelegd voor uw nieuwe beveiligingsgroep.
  • Vervang <workspace-name> door de naam van de werkruimte waartoe u de beveiligingsgroep toegang wilt geven.
# 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)

Stap 5: Uw inhoud insluiten

U kunt uw inhoud insluiten in een voorbeeldtoepassing of in uw eigen toepassing.

Nadat uw inhoud is ingesloten, bent u klaar om naar productie te gaan.

Notitie

Als u uw inhoud wilt beveiligen met behulp van een certificaat, volgt u de stappen die worden beschreven in Power BI-inhoud insluiten met een service-principal en een certificaat.

Overwegingen en beperkingen

  • Mijn werkruimte wordt niet ondersteund bij het gebruik van een service-principal.
  • Er is een capaciteit vereist bij het verplaatsen naar productie.
  • U kunt zich niet aanmelden bij de Power BI-portal met behulp van een service-principal.
  • Power BI-beheerdersrechten zijn vereist om de service-principal in te schakelen in instellingen voor ontwikkelaars in de Power BI-Beheer-portal.
  • Insluiten voor uw organisatietoepassingen kan geen service-principal gebruiken.
  • Beheer van gegevensstromen wordt niet ondersteund.
  • Service-principal ondersteunt alleen enkele alleen-lezen beheer-API's. Als u service-principal-ondersteuning wilt inschakelen voor alleen-lezen beheerders-API's, moet u de Power BI-service-beheerdersinstellingen inschakelen in uw tenant. Zie Verificatie van de service-principal inschakelen voor alleen-lezen beheer-API's voor meer informatie.
  • Wanneer u een service-principal gebruikt met een Azure Analysis Services-gegevensbron , moet de service-principal zelf machtigingen hebben voor het Azure Analysis Services-exemplaar. Het gebruik van een beveiligingsgroep die de service-principal voor dit doel bevat, werkt niet.

Gerelateerde inhoud