Managing Power BI Workspace Permissions using PowerShell

Managing workspace permissions in Power BI is essential for controlling access, security, and collaboration. Using PowerShell, administrators can:

View current permissions
Add or remove users and groups
Assign different roles (Admin, Member, Contributor, Viewer)

This guide explains how to manage Power BI workspace permissions using the MicrosoftPowerBIMgmt module.

Step 1: Prerequisites

1. Install and Import the Power BI PowerShell Module

Ensure you have the required PowerShell module installed:

# Install Power BI module
Install-Module -Name MicrosoftPowerBIMgmt -Scope CurrentUser -Force

# Import the module
Import-Module MicrosoftPowerBIMgmt

2. Authenticate to Power BI

You must connect to Power BI before managing permissions:

# Connect interactively
Connect-PowerBIServiceAccount

For automation, use a Service Principal:

# Define credentials
$clientId = "your-client-id"
$clientSecret = "your-client-secret"
$tenantId = "your-tenant-id"

# Convert secret to secure string
$secureSecret = ConvertTo-SecureString $clientSecret -AsPlainText -Force
$credential = New-Object System.Management.Automation.PSCredential ($clientId, $secureSecret)

# Connect using Service Principal
Connect-PowerBIServiceAccount -ServicePrincipal -TenantId $tenantId -ClientId $clientId -Credential $credential

Step 2: List Power BI Workspaces and Permissions

1. List All Workspaces

Get-PowerBIWorkspace

2. Retrieve Permissions for a Specific Workspace

# Define workspace name
$workspaceName = "Sales Analytics"

# Get workspace details
$workspace = Get-PowerBIWorkspace -Name $workspaceName

# List users and their roles in the workspace
Get-PowerBIWorkspaceUser -Id $workspace.Id

Example Output

PrincipalType UserEmail                 Role
------------- ------------------------- ------------
User         user1@domain.com           Admin
User         user2@domain.com           Member
User         user3@domain.com           Viewer

Step 3: Adding Users to a Power BI Workspace

To add a user to a workspace, use Add-PowerBIWorkspaceUser.

1. Define Variables for the Workspace and User

$workspaceName = "Sales Analytics"
$userEmail = "newuser@domain.com"
$role = "Contributor"  # Options: Admin, Member, Contributor, Viewer

2. Assign User to the Workspace

# Get workspace ID
$workspace = Get-PowerBIWorkspace -Name $workspaceName

# Add user to the workspace
Add-PowerBIWorkspaceUser -Id $workspace.Id -UserPrincipalName $userEmail -AccessRight $role

User added successfully!

Step 4: Removing Users from a Workspace

To remove a user from a workspace, use Remove-PowerBIWorkspaceUser.

# Define workspace name and user email
$workspaceName = "Sales Analytics"
$userEmail = "newuser@domain.com"

# Get workspace ID
$workspace = Get-PowerBIWorkspace -Name $workspaceName

# Remove user
Remove-PowerBIWorkspaceUser -Id $workspace.Id -UserPrincipalName $userEmail

User removed successfully!

Step 5: Modifying User Roles in a Workspace

Since PowerShell doesn’t support modifying user roles directly, you need to remove the user first and then re-add them with a different role.

# Remove user
Remove-PowerBIWorkspaceUser -Id $workspace.Id -UserPrincipalName $userEmail

# Re-add user with a new role
Add-PowerBIWorkspaceUser -Id $workspace.Id -UserPrincipalName $userEmail -AccessRight "Admin"

User role updated successfully!

Step 6: Adding Security Groups to a Workspace

Instead of adding individual users, you can assign Azure AD Security Groups for easier permission management.

# Define workspace and group details
$workspaceName = "Finance Reports"
$securityGroup = "finance-team@domain.com"
$role = "Member"

# Get workspace ID
$workspace = Get-PowerBIWorkspace -Name $workspaceName

# Add security group
Add-PowerBIWorkspaceUser -Id $workspace.Id -Identifier $securityGroup -AccessRight $role -PrincipalType Group

Security Group added to workspace!

Step 7: Exporting Workspace Permissions Report

To export all workspace users and roles into a CSV file:

# Get all workspaces
$workspaces = Get-PowerBIWorkspace

# Initialize an array
$permissionsList = @()

# Loop through workspaces
foreach ($workspace in $workspaces) {
    $users = Get-PowerBIWorkspaceUser -Id $workspace.Id
    foreach ($user in $users) {
        $permissionsList += [PSCustomObject]@{
            WorkspaceName = $workspace.Name
            UserEmail     = $user.UserPrincipalName
            Role         = $user.AccessRight
        }
    }
}

# Export to CSV
$permissionsList | Export-Csv -Path "C:\PowerBI_Workspace_Permissions.csv" -NoTypeInformation

Permissions exported successfully!

Step 8: Disconnect from Power BI

Once done, disconnect from Power BI:

Disconnect-PowerBIServiceAccount