Toegangstokens verkrijgen

  • 8 minuten

Wanneer u een toegangstoken verkrijgt, dat uw app altijd nodig heeft om Power BI-inhoud in te sluiten, moet u een Azure AD-token verkrijgen. Wanneer u het scenario Voor uw klanten gebruikt, gebruikt de app het token Azure AD om een insluittoken te genereren.

Voor de duidelijkheid:

  • Het toegangstoken voor het scenario Voor uw organisatie is het token Azure AD, dat claims bevat die uw app gebruikt om verleende machtigingen te identificeren.
  • Het toegangstoken voor het scenario Voor uw klanten is een insluittoken, dat feiten weergeeft over Power BI-inhoud en hoe uw app er toegang toe kan krijgen. Uw app genereert het insluittoken met behulp van een Power BI REST API-bewerking, waarvoor een Azure AD-token is vereist.

Azure AD-tokens verkrijgen

Gebruik de Microsoft Authentication Library (MSAL) om app-logica te ontwikkelen die Azure AD tokens verkrijgt van de Microsoft identity platform. MSAL ondersteunt verschillende toepassingsarchitecturen en -platforms, waaronder .NET, JavaScript, Java, Python, Android en iOS.

Tip

Wanneer u een ASP.NET Core-web-app ontwikkelt, raden we u aan de Microsoft Identity Web Authentication-bibliotheek te gebruiken. Deze bibliotheek is een set pakketten die bekend staat als Microsoft.Identity.Web. U kunt deze installeren vanuit NuGet of Visual Studio.

Er zijn verschillende technieken om een Azure AD-token te verkrijgen met behulp van MSAL. Voor sommige is gebruikersinteractie via een webbrowser vereist, terwijl voor andere geen interactie van de gebruiker nodig is. Over het algemeen is de methode die u kiest om een Azure AD-token te verkrijgen, afhankelijk van het feit of de toepassing een openbare clienttoepassing (zoals een desktop- of mobiele app) of een vertrouwelijke clienttoepassing (zoals een web-app) is. Het scenario voor insluiten heeft ook invloed op uw keuze.

Het is niet de bedoeling van deze eenheid om de technieken te beschrijven waarmee Azure AD tokens worden verkregen. Zie Tokens verkrijgen en opslaan met behulp van de Microsoft Authentication Library (MSAL) voor meer informatie.

Tip

Wanneer de voorbeeld-apps van het installatieprogramma voor insluiten overeenkomen met de vereisten van uw app, kunt u overwegen de voorbeeldcode te kopiëren om Azure AD tokens te verkrijgen.

Als u wilt dat uw app Azure AD-tokens kan verkrijgen, moet het configuratiebestand de volgende instellingen bevatten:

  • TenantId - Alleen vereist voor service-principal. Dit is uw Azure AD TenantID.
  • ClientId -Vereist. Dit is uw Azure AD app ApplicationID (ClientID).
  • ClientSecret of ClientCertificate - alleen vereist voor de service-principal.
  • PbiUsername - Alleen vereist voor hoofdgebruikersaccount.
  • PbiPassword - Alleen vereist voor hoofdgebruikersaccount.

Belangrijk

Of u nu certificaten, clientgeheimen of referenties voor hoofdgebruikersaccounts gebruikt, u moet stappen ondernemen om deze te beschermen tegen onbevoegde toegang en gebruik. U wordt aangeraden Azure Key Vault te gebruiken, waarmee cryptografische sleutels, certificaten en geheimen in de cloud worden beschermd.

Insluittokens verkrijgen

Gebruik de GenerateTokenRequestV2 bewerking van de Microsoft Power BI REST API om een insluittoken aan te vragen. Er zijn andere gerelateerde bewerkingen die insluittokens genereren voor andere Power BI-inhoudstypen. Voor alle API-bewerkingen is een Azure AD-token vereist.

Tip

Wanneer u een .NET-app ontwikkelt, raden we u aan het pakket Microsoft.PowerBI.Api te installeren. U kunt deze installeren vanuit NuGet of Visual Studio.

Bekijk de volgende code die laat zien hoe u een insluittoken genereert. Het token bevat claims voor alle rapporten en gegevenssets van een werkruimte en stelt app-gebruikers in staat om rapporten te maken of te bewerken. Het doet met name het volgende:

  1. Maakt verbinding met Power BI.
  2. Declareert een variabele met de naam reportTokenRequests om rapporttokenaanvragen op te slaan.
  3. Inventariseert alle rapporten in de werkruimte en maakt een lijst met objecten (met behulp van EmbeddedReport een helperklasse). Elk object beschrijft de id, naam en insluit-URL van het rapport. De app vereist de rapport-id om een token te genereren. De naam is vereist om aan gebruikers in een menu te presenteren en de insluit-URL is vereist om het rapport in te sluiten. Met de code wordt een rapporttokenaanvraag toegevoegd aan de variabele, waardoor het reportTokenRequests rapport kan worden bewerkt.
  4. Declareert een variabele met de naam datasetTokenRequests voor het opslaan van gegevenssettokenaanvragen.
  5. Inventariseert alle gegevenssets in de werkruimte en maakt een lijst met objecten (met behulp van EmbeddedDataset een helperklasse). Elk object beschrijft de id, naam en insluit-URL van de gegevensset. De app vereist de id van de gegevensset om een token te genereren. De naam is mogelijk vereist om deze aan gebruikers in een menu te presenteren en de insluit-URL is vereist om de gegevensset in te sluiten. Met de code wordt een gegevenssettokenaanvraag toegevoegd aan de datasetTokenRequests variabele.
  6. Hiermee wordt een aanvraag voor een werkruimtetoken gegenereerd (vereist wanneer gebruikers rapporten maken) die wordt toegevoegd aan de workspaceRequests variabele.
  7. Gebruikt de GenerateTokenRequestV2 methode om de rapporttokenaanvragen, gegevenssettokenaanvragen en de werkruimtetokenaanvraag te bundelen.
  8. Gebruikt GenerateTokenAsync om een insluittoken te genereren.
  9. Slaat het insluittoken op in een tekenreeksvariabele.
// 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;

De app moet de embedToken variabele waarde uitvoeren naar de html-pagina voor insluiten. Logica aan de clientzijde kan vervolgens het insluittoken gebruiken om inhoud in te sluiten in een div element.

Notitie

Als u wilt weten hoe u Power BI-inhoud insluit, gebruikt u de module Power BI-inhoud insluiten .

Als u wilt dat uw app insluittokens kan verkrijgen, moet het configuratiebestand details bevatten over de insluitbare inhoud. Het kan specifieke rapport-ID's en gegevensset-ID's bevatten, of meer algemeen de GroupID's van de werkruimten die insluitbare inhoud bevatten.

Zie Insluittoken - Token genereren voor meer informatie.

Toegangstokens vernieuwen

Toegangstokens hebben een verlooptijd. Zodra ze zijn gegenereerd, hebben app-gebruikers beperkte tijd om te communiceren met Power BI-inhoud die ze gebruikt. Als u uw app-gebruikers een continue ervaring wilt bieden, moet uw app toegangstokens vernieuwen voordat ze verlopen met behulp van de Client-API van Power BI.

Notitie

Als u meer wilt weten over de client-API, bekijkt u de module Inhoud integreren met de Power BI-client-API's .

Zie Het toegangstoken vernieuwen voor meer informatie.

Andere resources verkennen

Watch de Power BI-ontwikkelaarshandleiding voor Azure AD Beveiligingsvideoserie voor meer informatie. Deze serie bestaat uit zes video's die dieper ingaan op de theorie. Ted Pattison, die lid is van het Power BI Customer Advisory Team (CAT) bij Microsoft, heeft deze videoserie geproduceerd.