Manage users assignment to an application

Assign users to an application using the Microsoft Entra admin center

To assign a user to an enterprise application:

1. Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.

2. Browse to Identity > Applications > Enterprise applications > All applications.

3. Enter the name of the existing application in the search box, and then select the application from the search results.

4. Select Users and groups, and then select Add user/group.

   

5. On the Add Assignment pane, select None Selected under Users and groups.

6. Search for and select the user that you want to assign to the application. For example, contosouser1@contoso.com or contosoteam1@contoso.com.

7. Select Select.

8. Under Select a role, select the role that you want to assign to the user or group. If you haven't defined any roles yet, the default role is Default Access.

9. On the Add Assignment pane, select Assign to assign the user to the application.

Unassign users from an application

1. Follow the steps on the Assign users to an application section to navigate to the Users and groups pane.
2. Search for and select the user that you want to unassign from the application.
3. Select Remove to unassign the user from the application.

Assign users to an application using Azure AD PowerShell

1. Open an elevated Windows PowerShell command prompt.

2. Run Connect-AzureAD -AzureEnvironmentName AzureChinaCloud and sign in as at least a Cloud Application Administrator.

3. Use the following script to assign a user and role to an application:

   # Assign the values to the variables
   $username = "<Your user's UPN>"
   $app_name = "<Your App's display name>"
   $app_role_name = "<App role display name>"
   
   # Get the user to assign, and the service principal for the app to assign to
   $user = Get-AzureADUser -ObjectId "$username"
   $sp = Get-AzureADServicePrincipal -Filter "displayName eq '$app_name'"
   $appRole = $sp.AppRoles | Where-Object { $_.DisplayName -eq $app_role_name }
   
   # Assign the user to the app role
   New-AzureADUserAppRoleAssignment -ObjectId $user.ObjectId -PrincipalId $user.ObjectId -ResourceId $sp.ObjectId -Id $appRole.Id
   

For more information about how to assign a user to an application role, see the documentation for New-AzureADUserAppRoleAssignment.

Example

This example assigns the user Britta Simon to the Microsoft Workplace Analytics application using PowerShell.

1. In PowerShell, assign the corresponding values to the variables $username, $app_name and $app_role_name.

   # Assign the values to the variables
   $username = "britta.simon@contoso.com"
   $app_name = "Workplace Analytics"
   

2. In this example, we don't know what is the exact name of the application role we want to assign to Britta Simon. Run the following commands to get the user ($user) and the service principal ($sp) using the user UPN and the service principal display names.

   # Get the user to assign, and the service principal for the app to assign to
   $user = Get-AzureADUser -ObjectId "$username"
   $sp = Get-AzureADServicePrincipal -Filter "displayName eq '$app_name'"
   

3. Run the command $sp.AppRoles to display the roles available for the Workplace Analytics application. In this example, we want to assign Britta Simon the Analyst (Limited access) Role.

4. Assign the role name to the $app_role_name variable.

   # Assign the values to the variables
   $app_role_name = "Analyst (Limited access)"
   $appRole = $sp.AppRoles | Where-Object { $_.DisplayName -eq $app_role_name }
   

5. Run the following command to assign the user to the app role:

   # Assign the user to the app role
   New-AzureADUserAppRoleAssignment -ObjectId $user.ObjectId -PrincipalId $user.ObjectId -ResourceId $sp.ObjectId -Id $appRole.Id
   

Unassign users from an application using Azure AD PowerShell

1. Open an elevated Windows PowerShell command prompt.

2. Run Connect-AzureAD -AzureEnvironmentName AzureChinaCloud and sign in as at least a Cloud Application Administrator.

3. Use the following script to remove a user and role from an application.

   # Store the proper parameters
   $user = get-azureaduser -ObjectId <objectId>
   $spo = Get-AzureADServicePrincipal -ObjectId <objectId>
   
   #Get the ID of role assignment 
   $assignments = Get-AzureADServiceAppRoleAssignment -ObjectId $spo.ObjectId | Where {$_.PrincipalDisplayName -eq $user.DisplayName}
   
   #if you run the following, it will show you what is assigned what
   $assignments | Select *
   
   #To remove the App role assignment run the following command.
   Remove-AzureADServiceAppRoleAssignment -ObjectId $spo.ObjectId -AppRoleAssignmentId $assignments[assignment number].ObjectId
   

Remove all users who are assigned to the application using Azure AD PowerShell

Use the following script to remove all users assigned to the application.

#Retrieve the service principal object ID.
$app_name = "<Your App's display name>"
$sp = Get-AzureADServicePrincipal -Filter "displayName eq '$app_name'"
$sp.ObjectId

# Get Service Principal using objectId
$sp = Get-AzureADServicePrincipal -ObjectId "<ServicePrincipal objectID>"

# Get Azure AD App role assignments using objectId of the Service Principal
$assignments = Get-AzureADServiceAppRoleAssignment -ObjectId $sp.ObjectId -All $true

# Remove all users assigned to the application
$assignments | ForEach-Object {
    if ($_.PrincipalType -eq "User") {
        Remove-AzureADUserAppRoleAssignment -ObjectId $_.PrincipalId -AppRoleAssignmentId $_.ObjectId
    } elseif ($_.PrincipalType -eq "Group") {
        Remove-AzureADGroupAppRoleAssignment -ObjectId $_.PrincipalId -AppRoleAssignmentId $_.ObjectId
    }
}

Assign users to an application using Microsoft Graph PowerShell

1. Open an elevated Windows PowerShell command prompt.
2. Run Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "Application.ReadWrite.All", "Directory.ReadWrite.All", "AppRoleAssignment.ReadWrite.All" and sign in as at least a Cloud Application Administrator.
3. Use the following script to assign a user and role to an application:

# Assign the values to the variables

$userId = "<Your user's ID>"
$app_name = "<Your App's display name>"
$app_role_name = "<App role display name>"
$sp = Get-MgServicePrincipal -Filter "displayName eq '$app_name'"

# Get the user to assign, and the service principal for the app to assign to

$params = @{
    "PrincipalId" =$userId
    "ResourceId" =$sp.Id
    "AppRoleId" =($sp.AppRoles | Where-Object { $_.DisplayName -eq $app_role_name }).Id
    }

# Assign the user to the app role

New-MgUserAppRoleAssignment -UserId $userId -BodyParameter $params |
    Format-List Id, AppRoleId, CreationTime, PrincipalDisplayName,
    PrincipalId, PrincipalType, ResourceDisplayName, ResourceId

Unassign users from an application using Microsoft Graph PowerShell

1. Open an elevated Windows PowerShell command prompt.
2. Run Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "Application.ReadWrite.All", "Directory.ReadWrite.All", "AppRoleAssignment.ReadWrite.All" and sign in as at least a Cloud Application Administrator. Use the following script to remove a user and role from an application.

# Get the user and the service principal

$user = Get-MgUser -UserId <userid>
$spo = Get-MgServicePrincipal -ServicePrincipalId <ServicePrincipalId>

# Get the Id of the role assignment

$assignments = Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $spo.Id | Where {$_.PrincipalDisplayName -eq $user.DisplayName}

# if you run the following, it will show you the list of users assigned to the application

$assignments | Select *

# To remove the App role assignment run the following command.

Remove-MgServicePrincipalAppRoleAssignedTo -AppRoleAssignmentId  '<AppRoleAssignment-id>' -ServicePrincipalId $spo.Id

Remove all users assigned to the application using Microsoft Graph PowerShell

Use the following script to remove all users assigned to the application.

$assignments | ForEach-Object {
    if ($_.PrincipalType -in ("user", "Group")) {
        Remove-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $Sp.Id -AppRoleAssignmentId $_.Id  }
}