Power BI’s mission is to empower every individual, team, and organization to make confident decisions with data. With the increased focus on governance, compliance, and policy, customers need increased visibility within the Power BI environment to support workflows related to these areas. Power BI administrators need to support access review audits, understand oversharing risks, and see who has access to Power BI assets.
Today, I am pleased to announce the Public Preview of a suite of new admin APIs that provide much-enhanced visibility into user access and permission levels. These new APIs allow you to programmatically retrieve user and permission information for most Power BI assets (reports, dashboards, datasets, dataflows, workspaces, and capacities), or asset permission for any user or security group. Additionally, we are enhancing the read-only scanner admin API by including user permission information in the scan results. With these versatile new tools, you will be able to easily produce access reports for various Power BI assets on demand. You can even automate and schedule reviews based this information to proactively analyze oversharing risk and sleep better at night.
How can these APIs help you succeed?
- When your infosec team asks you perform an access review audit across the entire tenant or multiple workspaces, the scanner API with user permission extension will come in handy. It gives you user access information for various Power BI assets across all your workspaces.
- When you need to spot check access rights for a particular asset, such as a report, a dashboard or dataset, to assess potential data leakage risk, you want to leverage the Who has Access to an Asset API, such as the GetReportUsersAsAdmin API.
Read the rest of this blog post for an explanation of the APIs that are available for immediate use , or jump right into the documentation (see bottom of post) for more details. Remember that you can take advantage of the “Try It” feature of the Admin API docs to experiment with these API calls directly from the docs pages. You can also craft your request using tools like Postman or our PowerShell cmdlets.
Workspace scanner API with user permission extension (Preview)
We have extended the scanner admin API to help correlate users or security groups, with their access levels for one or more workspaces. For every asset in the scan result, a list of users and their permissions is returned. Read this blog post if you need a refresher on how to perform a workspace scan.
To include user and permission information in the scan result, simply add the following parameter in the query string in the PostWorkspaceInfo API to initiate a scan (remember, the scanner API is designed as an asynchronous operation):
getArtifactUsers=true
The HTTP call looks like:
POST https://api.powerbi.com/v1.0/myorg/admin/workspaces/getInfo?getArtifactUsers=true
When the scan result is ready, i.e., when a call to the GetScanStatus API returns a “status”: “Succeeded” in its response, another call to the GetScanResult API will return a list of workspaces and their assets, each of which will include a list of users with permission information:
{
"workspaces": [
{
"id": "d507422c-8d6d-4361-ac7a-30074a8cd0a1",
"name": "John Doe's workspace",
"type": "Workspace",
"state": "Active",
"isOnDedicatedCapacity": false,
"reports": [
{
"id": "d507422c-8d6d-4361-ac7a-30074a8cd0a1",
"name": "QuickCreate",
"datasetId": "d507422c-8d6d-4361-ac7a-30074a8cd0a1",
"createdDateTime": "2021-04-28T18:57:02.677",
"modifiedDateTime": "2021-04-28T18:57:02.677",
"modifiedBy": "john@contoso.com",
"sensitivityLabel": {
"labelId": "d507422c-8d6d-4361-ac7a-30074a8cd0a1"
},
"users": [
{
"reportUserAccessRight": "Owner",
"emailAddress": "john@contoso.com",
"displayName": "John Doe",
"identifier": "john@contoso.com",
"graphId": "d507422c-8d6d-4361-ac7a-30074a8cd0a1",
"principalType": "User"
},
// other users who have access to this report
]
},
// other reports
],
// similar structure with users[] for dashboard, dataset, dataflow
"users": [
{
"groupUserAccessRight": "Admin",
"emailAddress": "john@contoso.com",
"displayName": "John Doe",
"identifier": "john@contoso.com",
"graphId": "d507422c-8d6d-4361-ac7a-30074a8cd0a1",
"principalType": "User"
},
// other users who have access to this workspace
]
},
//other workspaces
]
} Some additional notes:
- If a user is a security group, then the API will return that SG but will not expand to display members.
- External users are supported and will be displayed alongside internal users.
- Power BI assets that support sharing within the organization via a linkwill be displayed with the principalType set to None, like this:
{
"reportUserAccessRight": "ReadReshare",
"displayName": "Whole Organization",
"identifier": "d507422c-8d6d-4361-ac7a-30074a8cd0a1",
"graphId": "d507422c-8d6d-4361-ac7a-30074a8cd0a1",
"principalType": "None"
} The scanner API gives you the ability to perform access reviews across an entire Power BI tenant or multiple workspaces. Sometimes, admins also need to spot check access rights for a particular asset, user, or security group to identify and assess potential data leakage risk. Read on to find out how we’re helping you do this!
Who has access to an asset? (Preview)
To figure out who has access to a particular type of Power BI asset, you can use an individual API for the corresponding asset. These APIs require you to supply an asset identifier and will output the users and groups that have been granted access to the asset, along with what roles they are granted. For example, to spot check the access list for a report, simply make this HTTP call:
GET https://api.powerbi.com/v1.0/myorg/admin/reports/{reportId}/users You’ll get back a list of users in a similar format as the scanner API users list.
The Power BI assets below are supported: capacity, workspace, report, dashboard, app, dataset, and dataflow. You can make similar HTTP calls to retrieve user access information for these assets, by replacing the “/reports/{reportId}” part with the asset of your choice.
What assets does a user have access to?
Later this summer, we will be releasing an API enabling you to specify particular users whose access rights need to be audited. Once it is available, this blog post will be updated with full details regarding this new capability.
Next steps
That’s a wrap! We are very excited about these APIs and can’t wait to see what you can accomplish with them! Check out the below references to learn more. As always, please leave feedback and questions. We’d love to hear from you!