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.

De api voor het genereren van tokens maakt gebruik van één identiteit (een hoofdgebruiker of service-principal) om een token voor een afzonderlijke gebruiker te genereren, afhankelijk van de referenties van die 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. Het heeft de voorkeur boven de verouderde API's van versie 1. Voor dashboards en tegels gebruikt u 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 api's voor het genereren van tokens worden in de sectie GenerateTokenRequest de tokenmachtigingen beschreven.

Toegangsniveau

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

  • Voeg de werkruimte-id toe aan het insluittoken, zodat de gebruiker nieuwe rapporten ( SaveAs of CreateNew) in die werkruimte kan maken.

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. In de onderstaande tabel ziet u de verschillende RLS-typen en ziet u 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 de volgende informatie opgeven:

    • Een identiteit voor elk item met een semantisch RLS-model.
    • Voor een semantisch SSO-model is een effectieve RLS-identiteit met de contextuele identiteit (SSO) gedefinieerd.

    DirectQuery voor semantische Power BI-modellen

    Ga als volgt te werk als u een Power BI-rapport wilt insluiten dat een semantisch model met een direct query-verbinding heeft met een ander semantisch Power BI-model:

    Tokens verlengen voordat ze verlopen

    Tokens worden geleverd met een tijdslimiet. Dit betekent dat u na het insluiten van een Power BI-item een beperkte hoeveelheid tijd hebt 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, is 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.

    • U kunt geen insluittoken maken voor Mijn werkruimte.

    Gerelateerde inhoud