Beveiliging op rijniveau met Power BI EmbeddedRow-level security with Power BI Embedded

Beveiliging op rijniveau (RLS) kan worden gebruikt om de gebruikerstoegang tot gegevens in dashboards, tegels, rapporten en gegevenssets te beperken.Row-level security (RLS) can be used to restrict user access to data within dashboards, tiles, reports, and datasets. Verschillende gebruikers kunnen werken met dezelfde artefacten, terwijl ze allemaal verschillende gegevens zien.Different users can work with those same artifacts all while seeing different data. Het insluiten van inhoud biedt ondersteuning voor RLS.Embedding supports RLS.

Als u inhoud wilt insluiten voor niet-Power BI-gebruikers (app is eigenaar van de gegevens), een typisch ISV-scenario, is dit artikel van belang voor u.If you're embedding for non-Power BI users (app owns data), which is typically an ISV scenario, then this article is for you! Configureer het insluittoken zodanig dat rekening wordt gehouden met de gebruiker en de rol.Configure the embed token to account for the user and role.

Als u inhoud wilt insluiten voor Power BI-gebruikers (gebruiker is eigenaar van de gegevens), werkt RLS hetzelfde als bij het rechtstreeks insluiten van inhoud in de Power BI-service.If you're embedding to Power BI users (user owns data), within your organization, RLS works the same as it does within the Power BI service directly. U hoeft verder niets te doen in uw toepassing.There's nothing more you need to do in your application. Zie Beveiliging op rijniveau (RLS) met Power BI voor meer informatie.For more information, see Row-Level security (RLS) with Power BI.

Items die betrokken zijn bij beveiliging op rijniveau.

Als u wilt kunnen profiteren van RLS, is het belangrijk dat u de drie hoofdbegrippen kent: gebruikers, rollen en regels.To take advantage of RLS, it's important you understand three main concepts; Users, Roles, and Rules. Laten we deze concepten eens nader bekijken:Let's take a closer look at these concepts:

Gebruikers: eindgebruikers die het artefact weergeven (dashboard, tegel, rapport of gegevensset).Users – End users viewing the artifact (dashboard, tile, report, or dataset). In Power BI Embedded worden gebruikers geïdentificeerd op basis van de eigenschap username (gebruikersnaam) in een insluittoken.In Power BI Embedded, users are identified by the username property in an embed token.

Rollen: gebruikers behoren tot rollen.Roles – Users belong to roles. Rollen zijn containers voor regels en kunnen namen hebben als Verkoopmanager of Verkoper. U maakt rollen in Power BI Desktop.A role is a container for rules and can be named something like Sales Manager or Sales Rep. You create roles within Power BI Desktop. Zie Beveiliging op rijniveau (RLS) met Power BI Desktop voor meer informatie.For more information, see Row-level security (RLS) with Power BI Desktop.

Regels: rollen bevatten regels, en deze regels zijn de werkelijke filters die op de gegevens worden toegepast.Rules – Roles have rules, and those rules are the actual filters that are going to be applied to the data. De regels kunnen zo eenvoudig zijn als 'Land = Nederland', maar ook veel ingewikkelder.The rules could be as simple as "Country = USA" or something much more dynamic. In de rest van dit artikel is een voorbeeld te vinden van het ontwerp en gebruik van RLS binnen een ingesloten toepassing.For the rest of this article, there's an example of authoring RLS, and then consuming that within an embedded application. Voor dit voorbeeld gebruiken we het PBIX-bestand Voorbeeld van een retailanalyse.Our example uses the Retail Analysis Sample PBIX file.

Voorbeeldrapport

Rollen toevoegen met Power BI DesktopAdding roles with Power BI Desktop

In het voorbeeld van een retailanalyse worden de verkoopcijfers voor alle winkels van een winkelketen weergegeven.Our Retail Analysis sample shows sales for all the stores in a retail chain. Zonder RLS zou elke regiomanager die zich aanmeldt en het rapport weergeeft, dezelfde gegevens zien.Without RLS, no matter which district manager signs in and views the report, they all see the same data. Het senior management heeft besloten dat elke regiomanager alleen de verkoopcijfers mag zien voor de winkels die hij of zij beheert.Senior management has determined each district manager should only see the sales for the stores they manage. Met behulp van RLS kan het senior management de gegevenstoegang filteren op regiomanager.Using RLS allows Senior management to restrict data based on a district manager.

RLS is geschreven in Power BI Desktop.RLS is authored in Power BI Desktop. Na het openen van de gegevensset en het rapport kunnen we overschakelen naar de diagramweergave van het schema:When the dataset and report are opened, we can switch to diagram view to see the schema:

Diagramweergave in Power BI Desktop

We noemen enkele dingen die opvallen in dit schema:Here are a few things to notice with this schema:

  • Alle metingen, zoals Totale verkoop, worden opgeslagen in de feitentabel Verkoop.All measures, like Total Sales, are stored in the Sales fact table.

  • Er zijn vier extra gerelateerde dimensietabellen: Artikel, Tijd, Winkel en Regio.There are four additional related dimension tables: Item, Time, Store, and District.

  • Met de pijlen op de relatielijnen wordt aangegeven in welke richting filters van de ene naar de andere tabel kunnen stromen.The arrows on the relationship lines indicate which way filters can flow from one table to another. Als er bijvoorbeeld een filter op Tijd[Datum] wordt toegepast in het huidige schema, worden alleen de waarden in de tabel Verkoop gefilterd.For example, if a filter is placed on Time[Date], in the current schema it would only filter down values in the Sales table. Er worden geen andere tabellen beïnvloed door dit filter, omdat alle pijlen op de relatielijnen naar de tabel Verkoop toe wijzen, en niet ervandaan.No other tables are affected by this filter since all the arrows on the relationship lines point to the sales table and not away.

  • In de tabel Regio wordt de manager van elke regio aangegeven:The District table indicates who the manager is for each district:

    Rijen in de tabel District

Als we in dit schema een filter toepassen op de kolom Regiomanager in de tabel Regio en als dat filter overeenkomt met de gebruiker die het rapport weergeeft, worden in de tabellen Winkel en Verkoop de gegevens voor die regiomanager weergegeven.Based on this schema, if we apply a filter to the District Manager column in the District table, and if that filter matches the user viewing the report, that filter down the Store and Sales tables to show data for that district manager.

U doet dit als volgt:Here's how:

  1. Op het tabblad Modellering selecteert u Rollen beheren.On the Modeling tab, select Manage Roles.

    Tabblad Modellering in Power BI Desktop

  2. Maak een nieuwe rol met de naam Manager.Create a new role called Manager.

    Nieuwe rol maken

  3. Voer in de tabel Regio deze DAX-expressie in: [Regiomanager] = USERNAME() .In the District table, enter this DAX expression: [District Manager] = USERNAME().

    DAX-instructie voor RLS-regel

  4. Als u wilt controleren of de regels correct functioneren, selecteert u op het tabblad Modellering de optie Als rollen weergeven. Selecteer vervolgens de rol Manager die u hebt gemaakt, plus de rol Andere gebruikers.To make sure the rules are working, on the Modeling tab, select View as Roles, and then select both the Manager role you created, along with Other users. Voer Andrew Ma in als gebruiker.Enter Andrew Ma for the user.

    Dialoogvenster Als rollen weergeven

    In de rapporten worden de gegevens weergegeven alsof u bent aangemeld als Andrew Ma.The reports show data as if you're signed in as Andrew Ma.

Door het filter toe te passen zoals we hier hebben gedaan, worden alle records in de tabellen Regio, Winkel en Verkoop gefilterd.Applying the filter, the way we did here, filters down all records in the District, Store, and Sales tables. Vanwege de filterrichting van de relaties tussen Verkoop en Tijd, worden de tabellen Verkoop en Artikel, en Artikel en Tijd echter niet gefilterd.However, because of the filter direction on the relationships between Sales and Time, Sales and Item, and Item and Time tables aren't filtered down. Download voor meer informatie over kruisfiltering in twee richtingen het technische document over Kruisfiltering in twee richtingen in SQL Server Analysis Services 2016 en Power BI Desktop.To learn more about bidirectional cross-filtering, download the Bidirectional cross-filtering in SQL Server Analysis Services 2016 and Power BI Desktop whitepaper.

Gebruiker en rol toepassen op een insluittokenApplying user and role to an embed token

Nu de rollen in Power BI Desktop zijn geconfigureerd, moet u nog wat werk verrichten in de toepassing om voordeel van de rollen te hebben.Now that you have your Power BI Desktop roles configured, some more work needs to be done in your application to take advantage of the roles.

Gebruikers worden geverifieerd en geautoriseerd door de toepassing, en insluittokens worden gebruikt om een gebruiker toegang te geven tot een specifiek Power BI Embedded-rapport.Users are authenticated and authorized by your application and embed tokens are used to grant a user access to a specific Power BI Embedded report. Power BI Embedded bevat geen specifieke informatie over de identiteit van de gebruiker.Power BI Embedded doesn't have any specific information on who your user is. Voor de juiste werking van RLS moet u aanvullende contextgegevens bij insluittokens doorgeven in de vorm van identiteiten.For RLS to work, you need to pass some additional context as part of your embed token in the form of identities. U kunt de identiteiten doorgeven via de API Embed Token.You can pass the identities by using the Embed Token API.

Met de API wordt een lijst identiteiten geaccepteerd met vermelding van de relevante gegevenssets.The API accepts a list of identities with indication of the relevant datasets. Voor de juiste werking van RLS moet u de onderstaande stukken doorgeven als onderdeel van de identiteit.For RLS to work, you need to pass the below pieces as part of the identity.

  • gebruikersnaam (verplicht) : een tekenreeks die kan worden gebruikt om de identiteit van de gebruiker vast te stellen bij het toepassen van RLS-regels.username (mandatory) – A string that can be used to help identify the user when applying RLS rules. Er kan slechts één gebruiker worden opgegeven.Only a single user can be listed. Uw gebruikersnaam kan worden gemaakt met ASCII-tekens.Your username can be created with ASCII characters.
  • rollen (verplicht) : een tekenreeks met de rollen die kunnen worden geselecteerd bij het toepassen van de regels voor beveiliging op rijniveau.roles (mandatory) – A string containing the roles to select when applying Row Level Security rules. Als u meerdere rollen wilt doorgeven, moeten deze worden doorgegeven als een tekenreeksmatrix.If passing more than one role, they should be passed as a string array.
  • gegevensset (verplicht) : de toepasselijke gegevensset voor het artefact dat u wilt insluiten.dataset (mandatory) – The dataset that is applicable for the artifact you're embedding.

U kunt het insluittoken maken met behulp van de methode GenerateTokenInGroup in PowerBIClient.Reports.You can create the embed token by using the GenerateTokenInGroup method on PowerBIClient.Reports.

U kunt bijvoorbeeld de PowerBI-Developer-Samples wijzigen > .NET Framework > Insluiten voor uw klanten > PowerBIEmbedded_AppOwnsData voorbeeld.For example, you could change the PowerBI-Developer-Samples > .NET Framework > Embed for your customers > PowerBIEmbedded_AppOwnsData sample.

Vóór de wijzigingBefore the change

// Generate Embed Token with effective identities.
generateTokenRequestParameters = new GenerateTokenRequest(accessLevel: "view", identities: new List<EffectiveIdentity> { rls });

// Generate Embed Token for reports without effective identities.
generateTokenRequestParameters = new GenerateTokenRequest(accessLevel: "view");

Na de wijzigingAfter the change

var generateTokenRequestParameters = new GenerateTokenRequest("View", null, identities: new List<EffectiveIdentity> { new EffectiveIdentity(username: "username", roles: new List<string> { "roleA", "roleB" }, datasets: new List<string> { "datasetId" }) });

var tokenResponse = await client.Reports.GenerateTokenInGroupAsync("groupId", "reportId", generateTokenRequestParameters);

Als u de REST API aanroept, accepteert de bijgewerkte API nu een extra JSON-matrix met de naam identities, met een gebruikersnaam, een tekenreeks met de lijst met rollen en een tekenreeks met de lijst met gegevenssets.If you're calling the REST API, the updated API now accepts an additional JSON array, named identities, containing a username, list of string roles and list of string datasets.

Gebruik de code hieronder als voorbeeld:Use the following code below as an example:

{
    "accessLevel": "View",
    "identities": [
        {
            "username": "EffectiveIdentity",
            "roles": [ "Role1", "Role2" ],
            "datasets": [ "fe0a1aeb-f6a4-4b27-a2d3-b5df3bb28bdc" ]
        }
    ]
}

Nu zijn alle benodigde onderdelen aanwezig. Als een gebruiker zich bij uw toepassing aanmeldt om dit artefact weer te geven, ziet de gebruiker alleen de gegevens die hij of zij mag zien, zoals gedefinieerd in de beveiliging op rijniveau.Now, with all the pieces together, when someone logs into your application to view this artifact, they'll only see the data that they're allowed to see, as defined by our row-level security.

Werken met liveverbindingen van Analysis ServicesWorking with Analysis Services live connections

Beveiliging op rijniveau kan worden gebruikt voor liveverbindingen van Analysis Services met on-premises servers.Row-level security can be used with Analysis Services live connections for on-premises servers. Als u dit type verbinding wilt gebruiken, moet u een aantal concepten goed kennen.There are a few specific concepts that you should understand when using this type of connection.

De effectieve identiteit die wordt opgegeven voor de eigenschap voor de gebruikersnaam, moet een Windows-gebruiker zijn met machtigingen voor de Analysis Services-server.The effective identity that is provided for the username property must be a Windows user with permissions on the Analysis Services server.

Notitie

Wanneer u de service-principal gebruikt met een Azure Analysis Services-gegevensbron, moet de service-principal zelf machtigingen hebben voor Azure Analysis Services.When using service principal with an Azure Analysis Services data source, the service principal itself must have an Azure Analysis Services instance permissions. Het gebruik van een beveiligingsgroep die de service-principal voor dit doel bevat, werkt niet.Using a security group that contains the service principal for this purpose, doesn't work.

Configuratie van on-premises gegevensgatewayOn-premises data gateway configuration

Voor liveverbindingen van Analysis Services wordt een On-premises gegevensgateway gebruikt.An On-premises data gateway is used when working with Analysis Services live connections. Bij het genereren van een insluittoken, met een opgegeven identiteit, moet het hoofdaccount zijn opgegeven als beheerder van de gateway.When generating an embed token, with an identity listed, the master account needs to be listed as an admin of the gateway. Als het hoofdaccount niet is opgegeven, wordt de beveiliging op rijniveau niet toegepast op de eigenschap van de gegevens.If the master account isn't listed, the row-level security isn't applied to the property of the data. Een niet-beheerder van de gateway kan rollen opgeven, maar moet zijn eigen gebruikersnaam als effectieve identiteit opgeven.A non-admin of the gateway can provide roles, but must specify its own username for the effective identity.

Gebruik van rollenUse of roles

Rollen kunnen worden opgegeven met de identiteit in een insluittoken.Roles can be provided with the identity in an embed token. Als er geen rol wordt opgegeven, kunnen de betreffende rollen worden omgezet op basis van de opgegeven gebruikersnaam.If no role is provided, the username that was provided can be used to resolve the associated roles.

De functie CustomData gebruikenUsing the CustomData feature

De functie CustomData werkt alleen voor modellen die zich in Azure Analysis Services bevinden. Bovendien werkt de functie uitsluitend in de Connect livemodus.The CustomData feature only works for models that lie in Azure Analysis Services, and it only works in Connect live mode. In tegenstelling tot gebruikers en rollen, kan de functie voor Custom Data niet in een .pbix-bestand worden ingesteld.Unlike users and roles, the Custom data feature can't be set inside a .pbix file. Tijdens het genereren van een token met de functie Custom Data, moet u over een gebruikersnaam beschikken.When generating a token with the Custom data feature, you need to have a username.

Notitie

De CustomData-gebruikersnaam mag niet langer zijn dan 256 tekens.The CustomData username can only be 256 characters long.

Met de functie CustomData kunt u een rijfilter toevoegen wanneer u Power BI-gegevens in uw toepassing bekijkt en u Azure Analysis Services als gegevensbron gebruikt (Power BI-gegevens bekijken die zijn gekoppeld aan Azure Analysis Services in uw toepassing).The CustomData feature allows you to add a Row filter when viewing Power BI data in your application when using Azure Analysis Services as your data source (viewing Power BI data connected to Azure Analysis Services in your application).

Met de functie CustomData kunt u vrije tekst (een tekenreeks) doorgeven met behulp van de eigenschap van de CustomData-verbindingsreeks.The CustomData feature allows passing free text (string) using the CustomData connection string property. Analysis Services gebruikt deze waarde via de functie CUSTOMDATA() .Analysis Services uses this value via the CUSTOMDATA() function.

De enige manier om in Azure Analysis Services dynamische RLS (dat dynamische waarden gebruikt voor filterbeoordeling) te gebruiken, is door toepassing van de functie CUSTOMDATA() .The only way to have dynamic RLS (which uses dynamic values for filter evaluation) in Azure Analysis Services, is using the CUSTOMDATA() function.

De functie kan binnen de DAX-query voor rollen worden gebruikt en de functie kan zonder rol in de DAX-query voor metingen worden gebruikt.You can use it inside the role DAX query, and you can use it without any role in a measure DAX query. De functie CustomData maakt deel uit van de functionaliteit voor het genereren van tokens voor de artefacten Dashboard, Rapport en Tegel.CustomData feature is part of our token generation functionality for the following artifacts: dashboard, report, and tile. Dashboards kunnen over meerdere CustomData-identiteiten (één per tegel/model) beschikken.Dashboards can have multiple CustomData identities (one per tile/model).

CustomData SDK - toevoegingenCustomData SDK Additions

De eigenschap van de CustomData-tekenreeks is toegevoegd aan de effectieve identiteit in het scenario voor het genereren van tokens.The CustomData string property was added to our effective identity in the token generation scenario.

[JsonProperty(PropertyName = "customData")]
public string CustomData { get; set; }

Met behulp van de volgende aanroep kan de identiteit kan worden gemaakt met aangepaste gegevens:The identity can be created with custom data using the following call:

public EffectiveIdentity(string username, IList<string> datasets, IList<string> roles = null, string customData = null);

CustomData SDK - gebruikCustomData SDK Usage

Als u de REST API aanroept, kunt u binnen elke identiteit aangepaste gegevens toevoegen, bijvoorbeeld:If you're calling the REST API, you can add custom data inside each identity, for example:

{
    "accessLevel": "View",
    "identities": [
        {
            "username": "EffectiveIdentity",
            "roles": [ "Role1", "Role2" ],
            "customData": "MyCustomData",
            "datasets": [ "fe0a1aeb-f6a4-4b27-a2d3-b5df3bb28bdc" ]
        }
    ]
}

Dit zijn de stappen om de functie CustomData() in te stellen met uw Power BI Embedded-toepassing.Here are the steps to begin setting up the CustomData() feature with your Power BI Embedded application.

  1. Maak een Azure Analysis Services-database.Create your Azure Analysis Services database. Meld u vervolgens aan bij uw Azure Analysis Services-server via SQL Server Management Studio.Then sign in to your Azure Analysis Services server via SQL Server Management Studio.

    Een Azure Analysis Services-database maken

    Analysis Services-database

  2. Maak een rol op de Analysis Services-server.Create a Role in the Analysis Services server.

    Rol maken

  3. Stel de Algemene instellingen in.Set your General settings. Hier geeft u de Rolnaam op en stelt u de databasemachtigingen in op alleen-lezen.Here you give the Role Name and set the database permissions to Read only.

    Rol maken - Algemene instellingen instellen

  4. Geef de instellingen voor Lidmaatschap op.Set the Membership settings. Hier kunt u gebruikers toevoegen die door deze rol worden beïnvloed.Here you add te users that are affected by this role.

    Rol maken - Lidmaatschapsinstellingen opgeven

  5. Stel de DAX-query Rijfilters in met de functie CUSTOMDATA() .Set your Row filters DAX query using the CUSTOMDATA() function.

    Rol maken - Rijfilters instellen

  6. Maak een PBI-rapport en publiceer dit in een werkruimte met capaciteit.Build a PBI report and publish it to a workspace with capacity.

    PBI-rapportvoorbeeld

  7. Gebruik de Power BI-API's om de functie CustomData in uw toepassing te gebruiken.Use the Power BI APIs to use the CustomData feature in your application. Tijdens het genereren van een token met de functie Custom Data, moet u over een gebruikersnaam beschikken.When generating a token with the Custom data feature, you need to have a username. De gebruikersnaam moet gelijk zijn aan de UPN van de hoofdgebruiker.The username must be equal to the UPN of the master user. De hoofdgebruiker moet lid zijn van de rol(len) die u hebt gemaakt.The master user must be a member of the role(s) you created. Als er geen rollen zijn opgegeven, worden alle rollen waar de hoofdgebruiker lid van is, gebruikt voor de RLS-beoordeling.If no role(s) are specified, then all the roles the master user is a member of are used for RLS evaluation.

    Als u werkt met een service-principal, moet u ook de bovengenoemde stappen uitvoeren in plaats van een hoofdaccount te gebruiken.When working with a service principal, you also need to do the above steps in place of using a master account. Gebruik bij het genereren van het insluittoken de object-id van de service-principal als gebruikersnaam.When generating embed token, use the service principal object ID as the username.

    Notitie

    Wanneer u klaar bent om uw toepassing in uw productieomgeving te implementeren, moeten eindgebruikers het hoofdgebruikersaccountveld of de hoofdgebruikersoptie niet kunnen zien.When you're ready to deploy your application to production, the master user account field or option should not be visible to the end user.

    Bekijk de code om de functie CustomData toe te voegen.View the code to add the CustomData feature.

  8. U kunt het rapport nu weergeven in uw toepassing voordat u de Custom Data-waarde(n) toevoegt om alle gegevens in het rapport te bekijken.Now you can view the report in your application before applying the Custom data value(s) to see all the data your report holds.

    Vóór toepassing van CustomData

    Pas vervolgens de Custom Data-waarde(n) toe om te bekijken hoe in het rapport een andere set gegevens wordt weergegeven.Then apply the Custom data value(s) to see how the report displays a different set of data. Na toepassing van CustomDataAfter CustomData is applied

RLS gebruiken vs. JavaScript-filtersUsing RLS vs. JavaScript filters

Wanneer u een beslissing neemt over filters in uw rapport, kunt u beveiliging op rijniveau (RLS) of JavaScript-filters gebruiken.When deciding on filtering your data in a report, you can use row-level security (RLS) or JavaScript filters.

Beveiliging op rijniveau is een functie die gegevens op het niveau van het gegevensmodel filtert.Row-level security is a feature that filters data at the data model level. Uw back-endgegevensbron beheert uw RLS-instellingen.Your backend data source controls your RLS settings. Op basis van uw gegevensmodel stelt de generatie van het insluittoken de gebruikersnaam en de rollen voor de sessie in.Based on your data model, the embed token generation sets the username and the roles for the session. De gegevens kunnen niet worden overschreven, verwijderd of gecontroleerd door de code aan de clientzijde. Daarom wordt deze methode als veilig beschouwd.It cannot be overridden, removed, or controlled by the client-side code and that's why it's considered secure. We raden aan om RLS te gebruiken om gegevens veilig te filteren.We recommend using RLS for filtering data securely. U kunt gegevens filteren met RLS door een van de onderstaande opties te gebruiken.You can filter data with RLS by using one of the options below.

  • Rollen configureren in een Power BI-rapport.Configuring roles in a Power BI report.
  • Rollen configureren op gegevensbronniveau (alleen met een Analysis Services-liveverbinding).Configuring roles at the data source level (Analysis Services live connection only).
  • Programmatisch via een Insluittoken met EffectiveIdentity.Programmatically with an Embed Token using EffectiveIdentity. Wanneer u een insluittoken gebruikt, wordt het werkelijke filter doorgegeven via het insluittoken voor een specifieke sessie.When using an embed token, the actual filter passes through the embed token for a specific session.

JavaScript-filters worden gebruikt om de gebruiker een beperkte, gerichte of gefilterde weergave van de gegevens te geven.JavaScript filters are used to allow the user to consume reduced, scoped, or a filtered view of the data. De gebruiker heeft echter nog steeds toegang tot de tabellen, kolommen en metingen van het modelschema en mogelijk ook tot de gegevens daarin.However, the user still has access to the model schema tables, columns, and measures and potentially can access any data there. Beperkte gegevenstoegang kan alleen worden gerealiseerd met RLS en niet via filter-API's aan de clientzijde.Restricted access to the data can only be applied with RLS and not through client-side filtering APIs.

Identiteit op basis van tokens met Azure SQL DatabaseToken-based Identity with Azure SQL Database

Met de identiteit op basis van tokens kunt u de effectieve identiteit voor een ingesloten token opgeven met Azure Active Directory-toegangstokens (AAD) voor een Azure SQL Database.The token-based identity allows you to specify the effective identity for an embed token using Azure Active Directory (AAD) access token for an Azure SQL Database.

Klanten die hun gegevens bewaren in Azure SQL Database hebben bij integratie met Power BI Embedded nu de mogelijkheid om gebruikers en hun toegang tot gegevens in Azure SQL te beheren.Customers that hold their data in Azure SQL Database can now enjoy a new capability to manage users and their access to data in Azure SQL when integrating with Power BI Embedded.

Wanneer u het insluitingstoken genereert, kunt u de effectieve identiteit van een gebruiker in Azure SQL opgeven.When you're generating the embed token, you can specify the effective identity of a user in Azure SQL. U geeft de effectieve identiteit van een gebruiker op door het AAD-toegangstoken door te geven aan de server.You can specify the effective identity of a user by passing the AAD access token to the server. Het toegangstoken wordt gebruikt om alleen de gegevens uit Azure SQL op te halen die voor die gebruiker en specifieke sessie relevant zijn.The access token is used to pull only the relevant data for that user from Azure SQL, for that specific session.

Het kan worden gebruikt om de weergave van elke gebruiker in Azure SQL te beheren of om mee aan te melden bij Azure SQL als specifieke klant in een multitenant-database.It can be used to manage each user's view in Azure SQL or to sign in to Azure SQL as a specific customer in a multi-tenant DB. Het kan eveneens worden gebruikt om voor die sessie beveiliging op rijniveau in Azure SQL toe te passen en alleen de relevante gegevens voor die sessie op te halen, zodat het niet meer nodig is om RLS te beheren in Power BI.It can also apply row-level security on that session in Azure SQL and retrieve only the relevant data for that session, removing the need to manage RLS in Power BI.

Dergelijke problemen met effectieve identiteit zijn rechtstreeks van toepassing op RLS-regels in de Azure SQL Server.Such effective identity issues apply to RLS rules directly on the Azure SQL Server. Power BI Embedded maakt gebruikt van het opgegeven toegangstoken wanneer het query's uitvoert op gegevens uit de Azure SQL Server.Power BI Embedded uses the provided access token when querying data from the Azure SQL Server. De UPN van de gebruiker (voor wie de toegangstoken is opgegeven) is toegankelijk als gevolg van de functie USER_NAME() SQL.The UPN of the user (for which the access token was provided) is accessible as a result of the USER_NAME() SQL function.

De identiteit op basis van tokens werk allen voor DirectQuery-modellen in een capaciteit, verbonden met een Azure SQL Database die is geconfigureerd voor AAD-verificatie (meer informatie over AAD-verificatie voor Azure SQL Database).The token-based identity only works for DirectQuery models on a capacity - connected to an Azure SQL Database, which is configured to allow AAD authentication (learn more about AAD authentication for Azure SQL Database). Als u een identiteit op basis van tokens wilt gebruiken, moet de gegevensbron van de gegevensset zo zijn geconfigureerd dat de OAuth2-referenties van de gebruikers worden gebruikt.The dataset's data source must be configured to use end users' OAuth2 credentials, to use a token-based identity.

Azure SQL-server configureren

SDK-toevoegingen voor identiteiten op basis van tokensToken-based Identity SDK additions

De eigenschap van de id-blob is toegevoegd aan de effectieve identiteit in het scenario voor het genereren van tokens.The identity blob property was added to our effective identity in the token generation scenario.

[JsonProperty(PropertyName = "identityBlob")]
public IdentityBlob IdentityBlob { get; set; }

Het type IdentityBlob is een eenvoudige JSON-structuur met een eigenschap van een tekenreekswaardeThe IdentityBlob type is a simple JSON structure holding a value string property

[JsonProperty(PropertyName = "value")]
public string value { get; set; }

De EffectiveIdentity kan worden gemaakt met de id-blob en de volgende aanroep:The EffectiveIdentity can be created with identity blob using the following call:

public EffectiveIdentity(string username, IList<string> datasets, IList<string> roles = null, string customData = null, IdentityBlob identityBlob = null);

De id-blob kan worden gemaakt met de volgende aanroep.Identity blob can be created using the following call.

public IdentityBlob(string value);

REST API-gebruik van identiteit op basis van tokensToken-based Identity REST API Usage

Als u de REST API aanroept, kunt u in elke identiteit een id-blob toevoegen.If you're calling the REST API, you can add identity blob inside each identity.

{
    "accessLevel": "View",
    "identities": [
        {
            "datasets": ["fe0a1aeb-f6a4-4b27-a2d3-b5df3bb28bdc"],
        "identityBlob": {
            "value": "eyJ0eXAiOiJKV1QiLCJh…."
         }
        }
    ]
}

De waarde die wordt opgegeven in de id-blob moet een geldig toegangstoken zijn voor Azure SQL Server (met een resource URL van (https://database.windows.net/)).The value provided in the identity blob should be a valid access token to Azure SQL Server (with a resource URL of (https://database.windows.net/).

Notitie

Als u een toegangstoken voor Azure SQL wilt maken, moet de toepassing de gedelegeerde machtiging Toegang tot Azure SQL DB en Data Warehouse hebben voor de Azure SQL Database-API in AAD-appregistratieconfiguratie in de Azure-portal.To be able to create an access token for Azure SQL, the application must have Access Azure SQL DB and Data Warehouse delegated permission to Azure SQL Database API on AAD app registration configuration in the Azure portal.

App-registratie

On-premises gegevensgateway met service-principalOn-premises data gateway with service principal

Klanten die beveiliging op rijniveau (RLS) met een on-premises SSAS-gegevensbron (SQL Server Analysis Services) met een live-verbinding configureren, profiteren van de nieuwe service-principal-mogelijkheid om gebruikers en hun toegang tot gegevens in SSAS te beheren wanneer zij integreren met Power BI Embedded.Customers that configure row-level security (RLS) using an SQL Server Analysis Services (SSAS) on-premises live connection data source can enjoy the new service principal capability to manage users and their access to data in SSAS when integrating with Power BI Embedded.

Met Power BI REST API'skunt u de effectieve identiteit voor on-premises live-SSAS-verbindingen voor een insluittoken opgeven met behulp van een service-principal-object.Using Power BI REST APIs, allows you to specify the effective identity for SSAS on-premises live connections for an embed token using a service principal object.

Tot nu toe moest de hoofdgebruiker die het insluittoken genereert een gatewaybeheerder zijn om de effectieve identiteit voor on-premises live-SSAS-verbindingen op te geven. Nu hoeft de gebruiker geen gatewaybeheerder meer te zijn: de gatewaybeheerder kan de gebruiker een toegewezen machtiging voor die gegevensbron geven, zodat de gebruiker de effectieve identiteit kan overschrijven wanneer het insluittoken wordt gegenereerd.Until now, to be able to specify the effective identity for SSAS on-premises live connection, the master user generating the embed token had to be a gateway admin. Now, instead of requiring the user to be gateway admin, the gateway admin can give the user dedicated permission to that data source, that allows the user to override the effective identity when generating the embed token. Dankzij deze nieuwe mogelijkheid is insluiten met een service-principal voor een live-SSAS-verbinding mogelijk.This new ability enables embedding with service principal for a live SSAS connection.

Voor het inschakelen van dit scenario gebruikt de gatewaybeheerder de Add Datasource User Rest API om de service-principal de ReadOverrideEffectiveIdentity-machtiging te verlenen voor Power BI Embedded.To enable this scenario, the gateway admin uses the Add Datasource User REST API to give the service principal the ReadOverrideEffectiveIdentity permission for Power BI Embedded.

U kunt deze machtiging niet instellen via de beheerportal.You can't set this permission using the admin portal. Deze machtiging kan alleen worden ingesteld met de API.This permission is only set with the API. In de beheerportal ziet u een indicatie voor gebruikers en SPN’s met dergelijke machtigingen.In the admin portal, you see an indication for users and SPNs with such permissions.

Overwegingen en beperkingenConsiderations and limitations

  • De toewijzing van gebruikers aan rollen in de Power BI-service heeft geen invloed op de beveiliging op rijniveau bij gebruik van een insluittoken.Assignment of users to roles within the Power BI service doesn't affect RLS when using an embed token.
  • Wanneer u een identiteit met een insluittoken opgeeft, worden RLS-instellingen in de Power BI-service niet toegepast op beheerders of leden met machtigingen voor bewerken, maar op de gegevens.While the Power BI service doesn't apply RLS setting to admins or members with edit permissions, when you supply an identity with an embed token, it applies to the data.
  • Liveverbindingen van Analysis Services worden ondersteund voor on-premises servers.Analysis Services live connections are supported for on-premises servers.
  • Live verbindingen van Azure Analysis Services bieden ondersteuning voor het filteren op rollen.Azure Analysis Services live connections support filtering by roles. U kunt dynamisch filteren met CustomData.Dynamic filtering can be done using CustomData.
  • Als RLS niet vereist is voor de onderliggende gegevensset, mag de GenerateToken-aanvraag geen effectieve identiteit bevatten.If the underlying dataset doesn't require RLS, the GenerateToken request must not contain an effective identity.
  • Als de onderliggende gegevensset een cloudmodel is (een model in de cache of DirectQuery), moet de effectieve identiteit ten minste één rol bevatten. Anders wordt roltoewijzing niet uitgevoerd.If the underlying dataset is a cloud model (cached model or DirectQuery), the effective identity must include at least one role, otherwise role assignment doesn't occur.
  • Een lijst met identiteiten kan meerdere identiteitstokens insluiten in het dashboard.A list of identities enables multiple identity tokens for dashboard embedding. Voor alle andere artefacten bevat de lijst één identiteit.For all others artifacts, the list contains a single identity.

Beperkingen van identiteit op basis van tokensToken-based Identity limitations

  • U kunt alleen beveiliging op rijniveau gebruiken als u over een capaciteit beschikt.You can use RLS only if you have a capacity.
  • RLS werkt niet met on-premises SQL Server.RLS doesn't work with SQL Server on-premises.

Hebt u nog vragen?More questions? Misschien dat de Power BI-community het antwoord weetTry asking the Power BI Community