Usare la sicurezza a livello di riga con il contenuto incorporato di Power BIUse row-level security with Power BI embedded content

La sicurezza a livello di riga può essere usata per limitare l'accesso degli utenti ai dati in dashboard, riquadri, report e set di dati.Row level security (RLS) can be used to restrict user access to data within dashboards, tiles, reports, and datasets. Più utenti diversi possono usare gli stessi elementi visualizzando al tempo stesso dati diversi.Multiple, different users can work with those same artifacts all while seeing different data. L'incorporamento supporta la sicurezza a livello di riga.Embedding supports RLS.

Se si incorporano dati per utenti non Power BI (i dati sono di proprietà dell'app), ovvero un tipico scenario ISV, leggere questo articolo.If you're embedding for non-Power BI users (app owns data), which is typically an ISV scenario, then this article is for you! Sarà necessario configurare il token di incorporamento per l'utente e il ruolo.You will need to configure the embed token to account for the user and role. Ecco come eseguire questa operazione.Read on to learn how to do this.

Se la condivisione viene effettuata con utenti di Power BI (i dati sono di proprietà dell'utente) all'interno dell'organizzazione, la sicurezza a livello di riga funziona esattamente come nel servizio Power BI.If you are embedding to Power BI users (user owns data), within your organization, RLS works the same as it does within the Power BI service directly. Non è necessario eseguire altre operazioni nell'applicazione.There is nothing more you need to do in your application. Per altre informazioni, vedere Sicurezza a livello di riga con Power BI.For more information see, Row-Level security (RLS) with Power BI.

Elementi coinvolti con la sicurezza a livello di riga.

Per sfruttare al meglio la sicurezza a livello di riga, è importante comprendere tre concetti fondamentali, ovvero utenti, ruoli e regole,To take advantage of RLS, it’s important you understand three main concepts; Users, Roles, and Rules. che verranno ora analizzati più in dettaglio:Let’s take a closer look at each:

Utenti: gli utenti finali visualizzano l'elemento (dashboard, riquadro, report o set di dati).Users – End-users viewing the artifact (dashboard, tile, report, or dataset). In Power BI Embedded gli utenti vengono identificati tramite la proprietà username in un token di incorporamento.In Power BI Embedded, users are identified by the username property in an embed token.

Ruoli: gli utenti appartengono a ruoli.Roles – Users belong to roles. Un ruolo è un contenitore di regole e può essergli assegnato un nome simile a Responsabile vendite o Rappresentante vendite. I ruoli vengono creati 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. Per altre informazioni, vedere Sicurezza a livello di riga con Power BI Desktop.For more information, see Row-level security (RLS) with Power BI Desktop.

Regole: i ruoli contengono regole e tali regole costituiscono i filtri effettivi che verranno applicati ai dati.Rules – Roles have rules, and those rules are the actual filters that are going to be applied to the data. Possono essere semplici, ad esempio "Paese = USA", oppure molto più dinamici.This could be as simple as “Country = USA” or something much more dynamic. La parte rimanente di questo articolo fornisce un esempio di creazione di sicurezza a livello di riga e il relativo utilizzo in un'applicazione incorporata.For the rest of this article, we’ll provide an example of authoring RLS, and then consuming that within an embedded application. In questo esempio viene usato il file PBIX Retail Analysis Sample.Our example uses the Retail Analysis Sample PBIX file.

Esempio di report

Aggiunta di ruoli con Power BI DesktopAdding roles with Power BI Desktop

L'esempio di analisi delle vendite al dettaglio mostra le vendite per tutti i negozi di una catena specifica.Our Retail Analysis sample shows sales for all the stores in a retail chain. Senza sicurezza a livello di riga, tutti i responsabili di area che accedono al report visualizzano gli stessi dati.Without RLS, no matter which district manager signs in and views the report, they’ll see the same data. I dirigenti hanno stabilito che ogni responsabile di area debba visualizzare solo le vendite dei negozi che gestisce e, per ottenere questo risultato, è possibile usare la sicurezza a livello di riga.Senior management has determined each district manager should only see the sales for the stores they manage, and to do this, we can use RLS.

La sicurezza a livello di riga viene creata in Power BI Desktop.RLS is authored in Power BI Desktop. All'apertura del set di dati e del report, è possibile passare alla visualizzazione diagramma per visualizzare lo schema:When the dataset and report are opened, we can switch to diagram view to see the schema:

Visualizzazione diagramma in Power BI Desktop

Alcuni aspetti da notare in questo schema:Here are a few things to notice with this schema:

  • Tutte le misure, ad esempio Total Sales, sono archiviate nella tabella dei fatti Sales.All measures, like Total Sales, are stored in the Sales fact table.
  • Sono presenti altre quattro tabelle delle dimensioni correlate: Item, Time, Store e District.There are four additional related dimension tables: Item, Time, Store, and District.
  • Le frecce sulle linee delle relazioni indicano la direzione in cui i filtri possono essere applicati da una tabella all'altra.The arrows on the relationship lines indicate which way filters can flow from one table to another. Ad esempio, se un filtro è posizionato su Time[Date], nello schema corrente verrebbero filtrati solo i valori presenti nella tabella Sales.For example, if a filter is placed on Time[Date], in the current schema it would only filter down values in the Sales table. Questo filtro non influirebbe su altre tabelle, perché tutte le frecce sulle linee relative alle relazioni fanno riferimento alla tabella Sales, non ad altre tabelle.No other tables would be affected by this filter since all the arrows on the relationship lines point to the sales table and not away.
  • La tabella District indica il responsabile per ogni area:The District table indicates who the manager is for each district:

    Righe all'interno della tabella District

In base a questo schema, se si applica un filtro alla colonna District Manager nella tabella District e se tale filtro corrisponde all'utente che visualizza il report, verranno filtrate anche le tabelle Store e Sales per visualizzare solo i dati relativi al responsabile di area specifico.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 will also filter down the Store and Sales tables to only show data for that district manager.

Ecco come:Here's how:

  1. Nella scheda Creazione di modelli selezionare Gestisci ruoli.On the Modeling tab, select Manage Roles.

    Scheda Creazione di modelli in Power BI Desktop

  2. Creare un nuovo ruolo denominato Manager.Create a new role called Manager.

    Crea nuovo ruolo

  3. Nella tabella District immettere l'espressione DAX seguente: [District Manager] = USERNAME().In the District table, enter the following DAX expression: [District Manager] = USERNAME().

    Istruzione DAX per la regola di sicurezza a livello di riga

  4. Per verificare che le regole funzionino correttamente, nella scheda Creazione di modelli selezionare Visualizza come ruoli e quindi il ruolo Manager appena creato, insieme ad Altro utente.To make sure the rules are working, on the Modeling tab, select View as Roles, and then select both the Manager role you just created, along with Other user. Per l'utente, immettere Andrew Ma.Enter Andrew Ma for the user.

    Finestra di dialogo Visualizza come ruoli

    A questo punto, nei report verranno visualizzati i dati come se l'accesso fosse stato eseguito come Andrew Ma.The reports will now show data as if you were signed in as Andrew Ma.

Applicando il filtro, come in questa procedura, vengono filtrati tutti i record nelle tabelle District, Store e Sales.Applying the filter, the way we did here, will filter down all records in the District, Store, and Sales tables. Tuttavia, a causa della direzione del filtro sulle relazioni tra le tabelle Sales e Time e Sales e Item, le tabelle Item e Time non verranno filtrate.However, because of the filter direction on the relationships between Sales and Time, Sales and Item, and Item and Time tables will not be filtered down. Per altre informazioni sui filtri incrociati bidirezionali, scaricare il white paper Bidirectional cross-filtering in SQL Server Analysis Services 2016 and Power BI Desktop (Filtri incrociati bidirezionali in SQL Server Analysis Services 2016 e 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.

Applicazione di utente e ruolo a un token di incorporamentoApplying user and role to an embed token

A questo punto, dopo aver configurato i ruoli di Power BI Desktop, per usare i ruoli è necessario eseguire alcune operazioni nell'applicazione.Now that you have your Power BI Desktop roles configured, there is some work needed in your application to take advantage of the roles.

Gli utenti vengono autenticati e autorizzati dall'applicazione e i token di incorporamento vengono usati per concedere l'accesso utente a un report specifico di Power BI Embedded.Users are authenticated and authorized by your application and embed tokens are used to grant that user access to a specific Power BI Embedded report. Power BI Embedded non ha informazioni specifiche sull'identità dell'utente.Power BI Embedded doesn’t have any specific information on who your user is. Per il corretto funzionamento della sicurezza a livello di riga, sarà necessario passare altre informazioni del contesto come parte del token di incorporamento sotto forma di identità.For RLS to work, you’ll need to pass some additional context as part of your embed token in the form of identities. Per questa operazione, si userà l'API GenerateToken.This is done by way GenerateToken API.

L'API GenerateToken accetta un elenco di identità con l'indicazione dei set di dati pertinenti.The GenerateToken API accepts a list of identities with indication of the relevant datasets. Per il corretto funzionamento della sicurezza a livello di riga, sarà necessario passare quanto segue come parte dell'identità.For RLS to work, you will need to pass the following as part of the identity.

  • username (obbligatoria): questa stringa può semplificare l'identificazione dell'utente quando si applicano le regole di sicurezza a livello di riga.username (mandatory) – This is a string that can be used to help identify the user when applying RLS rules. È possibile specificare solo un utente.Only a single user can be listed.
  • roles (obbligatoria): stringa contenente i ruoli da selezionare quando si applicano le regole di sicurezza a livello di riga.roles (mandatory) – A string containing the roles to select when applying Row Level Security rules. Se si passa più di un ruolo, sarà necessario passarli come matrice di stringhe.If passing more than one role, they should be passed as a string array.
  • dataset (obbligatoria): set di dati applicabile per l'elemento che verrà incorporato.dataset (mandatory) – The dataset that is applicable for the artifact you are embedding.

Per creare il token di incorporamento, usare il metodo GenerateTokenInGroup su PowerBIClient.Reports.You can create the embed token by using the GenerateTokenInGroup method on PowerBIClient.Reports.

È ad esempio possibile modificare l'esempio PowerBIEmbedded_AppOwnsData.For example, you could change the PowerBIEmbedded_AppOwnsData sample. Aggiornando le righe 76 e 77 del file Home\HomeController.cs da:Home\HomeController.cs line 76 and 77 could be updated from:

// Generate Embed Token.
var generateTokenRequestParameters = new GenerateTokenRequest(accessLevel: "view");

var tokenResponse = await client.Reports.GenerateTokenInGroupAsync(GroupId, report.Id, generateTokenRequestParameters);

ato

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);

Se si chiama l'API REST, l'API aggiornata ora accetta una matrice JSON aggiuntiva, denominata identities, contenente un nome utente, un elenco dei ruoli stringa e un elenco di set di dati stringa, ad esempio:If you are calling the REST API, the updated API now accepts an additional JSON array, named identities, containing a user name, list of string roles and list of string datasets, e.g.:

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

Ora, dopo aver eseguito tutti i passaggi, quando un utente effettua l'accesso all'applicazione per visualizzare questo elemento, potrà visualizzare solo i dati che è autorizzato a vedere, come definito dalla sicurezza a livello di riga.Now, with all the pieces together, when someone logs into your application to view this artifact, they’ll only be able to see the data that they are allowed to see, as defined by our row-level security.

Uso di connessioni dinamiche ad Analysis ServicesWorking with Analysis Services live connections

La sicurezza a livello di riga può essere usata solo con le connessioni in tempo reale di Analysis Services per i server locali.Row-level security can be used with Analysis Services live connections for on-premises servers. Esistono alcuni concetti specifici che è bene conoscere quando si usa questo tipo di connessione.There are a few specific concepts that you should understand when using this type of connection.

L'identità effettiva specificata per la proprietà username deve essere un utente di Windows con autorizzazioni per il server Analysis Services.The effective identity that is provided for the username property must be a Windows user with permissions on the Analysis Services server.

Configurazione del gateway dati localeOn-premises data gateway configuration

Un gateway dati locale è necessario quando si usano connessioni dinamiche di Analysis Services.An on-premises data gateway is used when working with Analysis Services live connections. Quando si genera un token di incorporamento, con un'identità elencata, l'account principale deve essere elencato come amministratore del gateway.When generating an embed token, with an identity listed, the master account needs to be listed as an admin of the gateway. Se l'account principale non è elencato, la sicurezza a livello di riga non verrà applicata correttamente ai dati.If the master account is not listed, the row-level security will not be applied property to the data. Chi non è amministratore del gateway può fornire i ruoli, ma deve specificare il proprio nome utente per l'identità effettiva.A non-admin of the gateway can provide roles, but must specify its own username for the effective identity.

Uso dei ruoliUse of roles

I ruoli possono essere forniti con l'identità in un token di incorporamento.Roles can be provded with the identity in an embed token. Se non vengono forniti ruoli, il nome utente fornito verrà usato per risolvere i ruoli associati.If no role is provided, the username that was provided will be used to resolve the associated roles.

Considerazioni e limitazioniConsiderations and limitations

  • L'assegnazione di utenti ai ruoli, all'interno del servizio Power BI, non influisce sulla sicurezza a livello di riga quando si usa un token di incorporamento.Assignment of users to roles within the Power BI service does not affect RLS when using an embed token.
  • Il servizio Power BI non applicherà l'impostazione di sicurezza a livello di riga agli amministratori o ai membri con autorizzazioni di modifica, ma quando si fornisce un'identità con un token di incorporamento, l'impostazione verrà applicata ai dati.While the Power BI service will not apply RLS setting to admins or members with edit permissions, when you supply an identity with an embed token, it will be applied to the data.
  • Sono supportate le connessioni dinamiche ad Analysis Services per i server locali.Analysis Services live connections are supported for on-premises servers.
  • Le connessioni dinamiche di Azure Analysis Services supportano i filtri in base al ruolo ma non i filtri dinamici in base al nome utente.Azure Analysis Services live connections support filtering by roles, but not dynamic by username.
  • Se il set di dati sottostante non richiede la sicurezza a livello di riga, la richiesta GenerateToken non deve contenere un'identità effettiva.If the underlying dataset doesn’t require RLS, the GenerateToken request must not contain an effective identity.
  • Se il set di dati sottostante è un modello cloud (modello memorizzato nella cache o DirectQuery), l'identità effettiva deve includere almeno un ruolo. In caso contrario, non verrà eseguita l'assegnazione di ruolo.If the underlying dataset is a cloud model (cached model or DirectQuery), the effective identity must include at least one role, otherwise role assignment will not occur.
  • Un elenco di identità consente più token di identità per l'incorporamento del dashboard.A list of identities enables multiple identity tokens for dashboard embedding. Per tutti gli altri elementi l'elenco contiene una singola identità.For all others artifacts, the list contains a single identity.

Altre domande?More questions? Provare a rivolgersi alla community di Power BITry asking the Power BI Community