Assigning Users to Dataverse Security Roles using PowerShell

Security roles in Microsoft Dataverse define user permissions for accessing tables, records, and operations. Assigning users to security roles ensures proper access control within Power Platform and Dynamics 365.

This guide provides a step-by-step approach to assigning users to Dataverse security roles 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: Assign a Security Role to Multiple Users

# List of user emails
$userEmails = @("user1@example.com", "user2@example.com", "user3@example.com")
$roleName = "Basic User"

# Get Role ID
$role = Get-CdsRecord -Connection $connection -EntityLogicalName "role" -Filter "name eq '$roleName'"
$roleId = $role.roleid

# Loop through each user and assign the role
foreach ($email in $userEmails) {
    # Fetch user
    $user = Get-CdsRecord -Connection $connection -EntityLogicalName "systemuser" -Filter "internalemailaddress eq '$email'"
    $userId = $user.systemuserid

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

    Write-Host "Assigned role '$roleName' to user '$email'"
}

Step 6: 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 7: 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 8: Export User Roles to a CSV File

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

# Fetch all user-role associations
$userRoles = Get-CdsRecord -Connection $connection -EntityLogicalName "systemuserroles"

# Export user roles to CSV
$userRoles | ForEach-Object {
    $user = Get-CdsRecord -Connection $connection -EntityLogicalName "systemuser" -Filter "systemuserid eq '$($_.systemuserid)'"
    $role = Get-CdsRecord -Connection $connection -EntityLogicalName "role" -Filter "roleid eq '$($_.roleid)'"
    
    [PSCustomObject]@{
        UserEmail = $user.internalemailaddress
        RoleName = $role.name
    }
} | Export-Csv -Path $csvFilePath -NoTypeInformation -Encoding UTF8

Write-Host "User roles exported to $csvFilePath"

Step 9: Disconnect from Dataverse

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