Delen via

Een insluittoken genereren

  • Artikel

VAN TOEPASSING OP: App is eigenaar van gegevens die gebruiker eigenaar is van gegevens

Een token genereren is een REST API waarmee u een token kunt genereren voor het insluiten van een Power BI-rapport of semantisch model in een web-app of een portal. Het kan een token genereren voor één item of voor meerdere rapporten of semantische modellen. Het token wordt gebruikt om uw aanvraag te autoriseren tegen de Power BI-service.

Het Generate token-API maakt gebruik van een identiteit (een hoofdgebruiker of service-principal) om een token voor een afzonderlijke gebruiker te genereren, op basis van de referenties van de gebruiker in de app (effectieve identiteit).

Na een geslaagde verificatie wordt toegang tot de relevante gegevens verleend.

Notitie

Een token genereren is de nieuwere API van versie 2 die werkt voor zowel rapporten als semantische modellen, en één of meerdere items. Gebruik voor dashboards en tegels de V1 Dashboards GenerateTokenInGroup en Tiles GenerateTokenInGroup.

Uw gegevens beveiligen

Als u gegevens van meerdere klanten verwerkt, zijn er twee belangrijke benaderingen voor het beveiligen van uw gegevens: isolatie op basis van werkruimten en isolatie op basis van beveiliging op rijniveau. U vindt een gedetailleerde vergelijking tussen deze profielen in service-principalprofielen en beveiliging op rijniveau.

We raden u aan om isolatie op basis van werkruimten te gebruiken met profielen, maar als u de RLS-benadering wilt gebruiken, raadpleegt u de sectie RLS aan het einde van dit artikel.

Tokenmachtigingen en -beveiliging

In de Generate-token API's worden in de sectie GenerateTokenRequest de tokenmachtigingen beschreven.

Toegangsniveau

  • Gebruik de parameter allowEdit om de gebruiker machtigingen voor weergave of bewerking te verlenen.

  • Als u wilt dat de gebruiker nieuwe rapporten maakt (SaveAs of CreateNew) in die werkruimte, voegt u de werkruimte-id toe aan het insluittoken.

De beveiliging op rijniveau

Met beveiliging op rijniveau (RLS) kan de identiteit die u gebruikt verschillen van de identiteit van de service-principal of hoofdgebruiker die u gebruikt om het token te genereren. Door verschillende identiteiten te gebruiken, kunt u ingesloten informatie weergeven op basis van de gebruiker die u wilt gebruiken. In uw toepassing kunt u bijvoorbeeld gebruikers vragen zich aan te melden en vervolgens een rapport weer te geven dat alleen verkoopgegevens bevat als de aangemelde gebruiker een verkoopmedewerker is.

Als u RLS gebruikt, kunt u soms de identiteit van de gebruiker weglaten (de parameter EffectiveIdentity ). Wanneer u de parameter EffectiveIdentity niet gebruikt, heeft het token toegang tot de hele database. Deze methode kan worden gebruikt om toegang te verlenen aan gebruikers, zoals beheerders en managers, die gemachtigd zijn om het hele semantische model weer te geven. U kunt deze methode echter niet gebruiken in elk scenario. De volgende tabel bevat de verschillende RLS-typen en toont welke verificatiemethode kan worden gebruikt zonder de identiteit van een gebruiker op te geven.

De tabel bevat ook de overwegingen en beperkingen die van toepassing zijn op elk type beveiliging op rijniveau.

RLS-type Kan ik een insluittoken genereren zonder de effectieve gebruikers-id op te geven? Overwegingen en beperkingen
Beveiliging op rijniveau in de cloud (cloud-beveiliging op rijniveau) ✔ Hoofdgebruiker
✖ Service-principal
RDL (gepagineerde rapporten) ✖ Hoofdgebruiker
✔ Service-principal		 U kunt geen hoofdgebruiker gebruiken om een insluittoken voor RDL te genereren.
On-premises liveverbinding van Analysis Services (AS) ✔ Hoofdgebruiker
✖ Service-principal		 De gebruiker die het insluittoken genereert, heeft ook een van de volgende machtigingen nodig:
  • Gatewaybeheerdersmachtigingen
  • Machtiging voor gegevensbron-imitatie (ReadOverrideEffectiveIdentity)
    		•
    Liveverbinding met Analysis Services (AS) van Azure ✔ Hoofdgebruiker
    ✖ Service-principal    		 De identiteit van de gebruiker die het insluittoken genereert, kan niet worden overschreven. Aangepaste gegevens kunnen worden gebruikt voor het implementeren van dynamische beveiliging op rijniveau of veilig filteren.

    Opmerking: Service-principal moet de object-id opgeven als de effectieve identiteit (RLS-gebruikersnaam).
    Single sign-on (SSO) ✔ Hoofdgebruiker
    ✖ Service-principal    		 Een expliciete identiteit (SSO) kan worden opgegeven met behulp van de eigenschap identity blob in een effectief identiteitsobject
    SSO en cloud-RLS ✔ Hoofdgebruiker
    ✖ Service-principal    		 U moet het volgende opgeven:
  • Expliciete identiteit (SSO) in de eigenschap identity blob in een effectief identiteitsobject
  • Effectieve identiteit (RLS) (gebruikersnaam)
    		•

    Notitie

    Service-principals moeten altijd het volgende bieden:

    • Een identiteit voor elk item met een semantisch RLS-model
    • Een effectieve RLS-identiteit met de gedefinieerde contextuele (SSO) identiteit (voor een semantisch SSO-model)

    DirectQuery voor semantische Power BI-modellen

    Een Power BI-rapport met een semantisch model met een Direct Query-verbinding insluiten met een ander semantisch Power BI-model:

    Tokens verlengen voordat ze verlopen

    Tokens worden geleverd met een tijdslimiet. Daarom hebt u na het insluiten van een Power BI-item een beperkte hoeveelheid tijd om ermee te werken. Als u uw gebruikers een continue ervaring wilt bieden, vernieuwt u het token (of vernieuwt) voordat het verloopt.

    Dashboards en tegels

    Het token Genereren werkt voor rapporten en semantische modellen. Gebruik versie 1 Dashboards GenerateTokenInGroup of Tiles GenerateTokenInGroup-API's om een insluittokentoken voor een dashboard of tegel te genereren. Deze API's genereren tokens voor slechts één item tegelijk. U kunt geen token genereren voor meerdere items.

    Voor deze API's:

    • Gebruik de parameter accessLevel om het toegangsniveau van de gebruiker te bepalen.

      • Weergave : de gebruiker machtigingen verlenen voor weergave.

      • Bewerken : de gebruiker machtigingen verlenen voor weergeven en bewerken (alleen van toepassing bij het genereren van een insluittoken voor een rapport).

      • Maken : de gebruikersmachtigingen verlenen om een nieuw rapport te maken (alleen van toepassing bij het genereren van een insluittoken voor het maken van een rapport). Voor het maken van rapporten moet u ook de parameter datasetId opgeven.

    • Gebruik de booleaanse waarde allowSaveAs om gebruikers het rapport als een nieuw rapport te laten opslaan. Deze instelling is standaard ingesteld op onwaar en is alleen van toepassing bij het genereren van een insluittoken voor een rapport.

    Overwegingen en beperkingen

    • Om veiligheidsredenen wordt de levensduur van het insluittoken ingesteld op de resterende levensduur van het Microsoft Entra-token dat wordt gebruikt om de GenerateToken API aan te roepen. Als u dus hetzelfde Microsoft Entra-token gebruikt om verschillende insluittokens te genereren, wordt de levensduur van de gegenereerde insluitingstokens korter bij elke aanroep.

    • Als het semantische model en het item dat moet worden ingesloten zich in twee verschillende werkruimten bevinden, moet de service-principal of hoofdgebruiker ten minste lid zijn van beide werkruimten.

    • Voor het insluiten van items met behulp van Data Lake Storage (DLS) is V2 van de Generate-token-APIvereist.

    • U kunt geen insluittoken maken voor Mijn werkruimte.

    Gerelateerde inhoud