Managing Dataverse Security Roles using PowerShell

Security roles in Microsoft Dataverse define user permissions for accessing tables, records, and operations. PowerShell allows administrators to automate security role assignments, modifications, and retrievals efficiently.

This guide provides a step-by-step approach to managing security roles in Dataverse using PowerShell.

Step 1: Prerequisites

1. Required Permissions

You must have System Administrator or Power Platform Admin access.
The Dataverse API must be enabled in your environment.

2. Install and Import Required PowerShell Modules

Ensure you have the required PowerShell modules installed.

# Install Power Platform Administration module
Install-Module -Name Microsoft.PowerPlatform.Administration -Scope CurrentUser -Force

# Install Dataverse Client module
Install-Module -Name Microsoft.PowerPlatform.Cds.Client -Scope CurrentUser -Force

# Import the modules
Import-Module Microsoft.PowerPlatform.Administration
Import-Module Microsoft.PowerPlatform.Cds.Client

Step 2: Connect to Dataverse

Option 1: Interactive Login

# Connect to Dataverse interactively
$connection = Connect-CdsService -ConnectionString "AuthType=OAuth;Url=https://yourorg.crm.dynamics.com;Prompt=Login"

A sign-in window will appear for authentication.

Option 2: Using Service Principal (App Registration)

For automation scripts, use an Azure AD App Registration.

# Define credentials
$clientId = "your-app-client-id"
$clientSecret = "your-app-client-secret"
$tenantId = "your-tenant-id"
$orgUrl = "https://yourorg.crm.dynamics.com"

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

# Connect to Dataverse
$connection = Connect-CdsService -Url $orgUrl -ClientId $clientId -ClientSecret $secureSecret -TenantId $tenantId

Step 3: Retrieve All Security Roles

List All Security Roles

# Fetch all security roles
$securityRoles = Get-CdsRecord -Connection $connection -EntityLogicalName "role"

# Display security roles
$securityRoles | Select-Object roleid, name

This retrieves all security roles with their IDs.

Step 4: Assign a Security Role to a User

1. Identify User and Role

# Define user email and role name
$userEmail = "user@example.com"
$roleName = "Basic User"

2. Retrieve User ID

# Fetch user from Dataverse
$user = Get-CdsRecord -Connection $connection -EntityLogicalName "systemuser" -Filter "internalemailaddress eq '$userEmail'"

# Extract user ID
$userId = $user.systemuserid

3. Retrieve Role ID

# Fetch security role
$role = Get-CdsRecord -Connection $connection -EntityLogicalName "role" -Filter "name eq '$roleName'"

# Extract role ID
$roleId = $role.roleid

4. Assign Role to User

# Assign security role
New-CdsAssociation -Connection $connection -EntityName "systemuserroles" -PrimaryId $userId -RelatedEntityName "role" -RelatedId $roleId

Write-Host "Security role '$roleName' assigned to user '$userEmail'"

Step 5: Remove a Security Role from a User

# Remove security role from user
Remove-CdsAssociation -Connection $connection -EntityName "systemuserroles" -PrimaryId $userId -RelatedEntityName "role" -RelatedId $roleId

Write-Host "Security role '$roleName' removed from user '$userEmail'"

Step 6: Retrieve a User’s Assigned Roles

# Get roles assigned to a user
$userRoles = Get-CdsRecord -Connection $connection -EntityLogicalName "systemuserroles" -Filter "systemuserid eq '$userId'"

# Display user roles
$userRoles | ForEach-Object {
    $role = Get-CdsRecord -Connection $connection -EntityLogicalName "role" -Filter "roleid eq '$($_.roleid)'"
    Write-Host "User has role: $($role.name)"
}

Step 7: Create a New Security Role (Duplicate an Existing Role)

1. Identify the Role to Copy

# Define source role
$sourceRoleName = "Basic User"
$sourceRole = Get-CdsRecord -Connection $connection -EntityLogicalName "role" -Filter "name eq '$sourceRoleName'"

$sourceRoleId = $sourceRole.roleid

2. Create a New Role Based on the Source Role

# Define new role name
$newRoleName = "Custom Basic User"

# Create new role
$newRole = New-CdsRecord -Connection $connection -EntityLogicalName "role" -Fields @{
    "name" = $newRoleName
    "businessunitid" = $sourceRole.businessunitid
}

Write-Host "New role '$newRoleName' created."

Step 8: Delete a Security Role

1. Identify the Role to Delete

# Define role name
$deleteRoleName = "Custom Basic User"

# Fetch role ID
$deleteRole = Get-CdsRecord -Connection $connection -EntityLogicalName "role" -Filter "name eq '$deleteRoleName'"
$deleteRoleId = $deleteRole.roleid

2. Delete the Role

# Remove security role
Remove-CdsRecord -Connection $connection -EntityLogicalName "role" -Id $deleteRoleId

Write-Host "Security role '$deleteRoleName' deleted successfully."

Step 9: Export Security Roles to a CSV File

# Define export path
$csvFilePath = "C:\Dataverse_Export\SecurityRoles.csv"

# Export roles to CSV
$securityRoles | Select-Object roleid, name | Export-Csv -Path $csvFilePath -NoTypeInformation -Encoding UTF8

Write-Host "Security roles exported to $csvFilePath"

Step 10: Disconnect from Dataverse

Disconnect-CdsService -Connection $connection
Write-Host "Disconnected from Dataverse."