Manage admin roles with Microsoft Entra Privileged Identity Management

Use Microsoft Entra Privileged Identity Management (PIM) to manage high-privileged admin roles in the Power Platform admin center.

Prerequisites

• Remove old system administrator role assignments in your environments. You can use PowerShell scripts to inventory and remove unwanted users from the System Administrator role in one or more Power Platform environments.

Changes to feature support

Microsoft no longer automatically assigns the System Administrator role to users with global or service level admin roles such as Power Platform Administrator and Dynamics 365 Administrator.

These admins can continue to sign in, to the Power Platform admin center, with these privileges:

• Enable or disable tenant level settings
• View analytics information for environments
• View capacity consumption

These admins can't perform activities that require direct access to Dataverse data without a license. Examples of these activities include:

• Updating the security role for a user in an environment
• Installing apps for an environment

Known limitations

• When using the API, you notice that if the caller is a system administrator, the self-elevate call returns a success rather than notifying the caller that the system administrator already exists.

• The user making the call must have the tenant admin role assigned. For a full list of users who meet the tenant admin criteria, see Changes to feature support

• If you're a Dynamics 365 administrator and the environment is protected by a security group, you must be a member of the security group. This rule doesn't apply to users with the global administrator or Power Platform administrator roles.

• The elevation API can only be invoked by the user who needs to elevate their status. It doesn't support making API calls on behalf of another user for elevation purposes.

• The system administrator role assigned through self-elevation is not removed when the role assignment expires in Privileged Identity Management. You must manually remove the user from the system administrator role. See clean-up activity

• A workaround is available for customers using the Microsoft Power Platform CoE Starter Kit. See PIM Issue and Workaround #8119 for more information and details.

• Role assignments through groups aren't supported. Make sure that you assign roles directly to the user.

Self-elevate to the system administrator role

We support elevation using either PowerShell or through an intuitive experience in Power Platform admin center.

Self-elevate through PowerShell

Set up PowerShell

Install the MSAL PowerShell module. You only need to install the module once.

Install-Module -Name MSAL.PS

For more information about setting up PowerShell, see Quick Start Web API with PowerShell and Visual Studio Code.

Step 1: Run the script to elevate

In this PowerShell script, you:

• Authenticate, using the Power Platform API.
• Build an http query with your environment ID.
• Call the API endpoint to request elevation.

Add your environment ID

1. Get your Environment ID from the Environments tab of the Power Platform Admin Center.

2. Add your unique <environment id> to the script.

Run the script

Copy and paste the script into a PowerShell console.

# Set your environment ID
$environmentId = "<your environment id>"

Import-Module MSAL.PS

# Authenticate
$AuthResult = Get-MsalToken -ClientId '00001111-aaaa-2222-bbbb-3333cccc4444' -Scope 'https://api.powerplatform.com/.default' 


$Headers = @{
   Authorization  = "Bearer $($AuthResult.AccessToken)"
   'Content-Type' = "application/json"
} 

$uri = "https://api.powerplatform.com/usermanagement/environments/$environmentId/user/applyAdminRole?api-version=2022-03-01-preview";

try { 

   $postRequestResponse = Invoke-RestMethod -Method Post -Headers $Headers -Uri $uri 
   
} 
   
catch { 
   
   # Dig into the exception to get the Response details. 
   
   Write-Host "Response CorrelationId:" $_.Exception.Response.Headers["x-ms-correlation-id"] 
   
   Write-Host "StatusCode:" $_.Exception.Response.StatusCode.value__  
   
   Write-Host "StatusDescription:" $_.Exception.Response.StatusDescription 
   
   $result = $_.Exception.Response.GetResponseStream() 
   
   $reader = New-Object System.IO.StreamReader($result) 
   
   $reader.BaseStream.Position = 0 
   
   $reader.DiscardBufferedData() 
   
   $responseBody = $reader.ReadToEnd(); 
   
   Write-Host $responseBody 
   
} 
   
$output = $postRequestResponse | ConvertTo-Json -Depth 2 
   
Write-Host $output

Step 2: Confirm the result

Upon success, you see an output similar to the following output. Look for "Code": "UserExists" as evidence that you successfully elevated your role.

{
  "errors": [],
  "information": [
    {
      "Subject": "Result",
      "Description": "[\"SyncMode: Default\",\"Instance df12c345-7b56-ee10-8bc5-6045bd005555 exists\",\"Instance df85c664-7b78-ee11-8bc5-6045bd005555 in enabled state\",\"Instance Url found https://orgc1234567.crm.dynamics.com\",\"User found in AD tenant\",\"User in enabled state in AD tenant\",\"SystemUser with Id:11fa11ab-4f75-ee11-9999-6045bd12345a, objectId:aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb exists in instance\"]",
      "Code": "UserExists"
    },
    { ... }
}

Errors

You might see an error message if you don't have the right permissions.

"Unable to assign System Administrator security role as the user is not either a Global admin, Power Platform admin, or Dynamics 365 admin. Please review your role assignments in Entra ID and try again later. For help, please reach out to your administrator."

Step 3: Clean-up activity

Run Remove-RoleAssignmentFromUsers to remove users from the System Administrator security role after the assignment expires in PIM.

• -roleName: "System Administrator" or another role
• -usersFilePath: Path to CSV file with list of user principal names (one per line)
• -environmentUrl: Found at admin.powerplatform.microsoft.com
• -processAllEnvironments: (Optional) Process all your environments
• -geo: A valid GEO
• -outputLogsDirectory: Path where log files are written

Example script

Remove-RoleAssignmentFromUsers
-roleName "System Administrator" 
-usersFilePath "C:\Users\<My-Name>\Desktop\<names.csv>"
-environmentUrl "<my-name>-environment.crm.dynamics.com"
# Or, include all your environments
-processAllEnvironments $true
-geo "NA"
-outputLogsDirectory "C:\Users\<My-Name>\Desktop\<log-files>"

Self-elevate through Power Platform admin center

1. Sign in to the Power Platform admin center.

2. In the left side panel, select Environments.

3. Select the checkmark next to your environment.

4. Select Membership in the command bar to request self-elevation.

5. The System Administrators pane is displayed. Add yourself to the system administrator role by selecting Add me.