Manage users assignment to an application

Article
11/22/2024

This article shows you how to assign users to an enterprise application in Microsoft Entra ID using PowerShell. When you assign a user to an application, the application appears in the user's My Apps portal for easy access. If the application exposes app roles, you can also assign a specific app role to the user.

For greater control, certain types of enterprise applications can be configured to require user assignment. For more information on requiring user assignment for an app, see Manage access to an application.

Note

Applications that requires users to be assigned to the application must have their permissions consented by an administrator, even if the user consent policies for your directory would otherwise allow a user to consent on behalf of themselves.

Prerequisites

To assign users to an enterprise application, you need:

A Microsoft Entra account with an active subscription. If you don't already have one, you can Create an account.
One of the following roles: Cloud Application Administrator, Application Administrator, or owner of the service principal.
Microsoft Entra ID P1 or P2 for group-based assignment. For more licensing requirements for the features discussed in this article, see the Microsoft Entra pricing page.

Tip

Steps in this article might vary slightly based on the portal you start from.

Assign users to an application using the Microsoft Entra admin center

To assign a user to an enterprise application:

Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
Browse to Identity > Applications > Enterprise applications > All applications.
Enter the name of the existing application in the search box, and then select the application from the search results.
Select Users and groups, and then select Add user/group.
On the Add Assignment pane, select None Selected under Users and groups.
Search for and select the user that you want to assign to the application. For example, contosouser1@contoso.com or contosoteam1@contoso.com.
Select Select.
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.
On the Add Assignment pane, select Assign to assign the user to the application.

Unassign users from an application

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

Assign users to an application using Azure AD PowerShell

Open an elevated Windows PowerShell command prompt.
Run Connect-AzureAD -AzureEnvironmentName AzureChinaCloud and sign in as at least a Cloud Application Administrator.

Use the following script to assign a user 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

Example

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

In PowerShell, assign the corresponding values to the variables $username, $app_name and $app_role_name.
```
$username = "britta.simon@contoso.com"
$app_name = "Workplace Analytics"
```
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.
```
$user = Get-AzureADUser -ObjectId "$username"
$sp = Get-AzureADServicePrincipal -Filter "displayName eq '$app_name'"
```
Run the following command to find the app roles exposed by the service principal
```
$appRoles = $sp.AppRoles
# Display the app roles
$appRoles | ForEach-Object {
    Write-Output "AppRole: $($_.DisplayName) - ID: $($_.Id)"
```
Note

The default AppRole ID is 00000000-0000-0000-0000-000000000000. This role is assigned when no specific AppRole is defined for a service principal.
Assign the AppRole name to the $app_role_name variable. In this example, we want to assign Britta Simon the Analyst (Limited access) Role.
```
$app_role_name = "Analyst (Limited access)"
$appRole = $sp.AppRoles | Where-Object { $_.DisplayName -eq $app_role_name }
```

Run the following command to 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

Open an elevated Windows PowerShell command prompt.
Run Connect-AzureAD -AzureEnvironmentName AzureChinaCloud and sign in as at least a Cloud Application Administrator.

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

Open an elevated Windows PowerShell command prompt.

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

Open an elevated Windows PowerShell command prompt.
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 assign a user 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, the service principal and appRole.
$params = @{
"PrincipalId" =$userId
"ResourceId" =$sp.Id
"AppRoleId" =($sp.AppRoles | Where-Object { $_.DisplayName -eq $app_role_name }).Id
}
#Assign the user to the AppRole
New-MgUserAppRoleAssignment -UserId $userId -BodyParameter $params |
    Format-List Id, AppRoleId, CreationTime, PrincipalDisplayName,
    PrincipalId, PrincipalType, ResourceDisplayName, ResourceId

Example

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

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

# Assign the values to the variables  
$userId = "<Britta Simon's user ID>"  
$app_name = "Workplace Analytics"

In this example, we don't know the exact name of the application role we want to assign to Britta Simon. Run the following command to get the service principal ($sp) using the service principal display name.
```
# Get the service principal for the app  
$sp = Get-MgServicePrincipal -Filter "displayName eq '$app_name'"  
```
Run the following command to find the app roles exposed by the service principal.
```
# Get the app roles exposed by the service principal  
$appRoles = $sp.AppRoles  
# Display the app roles  
$appRoles | ForEach-Object {  
    Write-Output "AppRole: $($_.DisplayName) - ID: $($_.Id)"  
}  
```
Note

The default AppRole ID is 00000000-0000-0000-0000-000000000000. This role is assigned when no specific AppRole is defined for a service principal.

Assign the role name to the $app_role_name variable. In this example, we want to assign Britta Simon the Analyst (Limited access) Role.

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

Prepare the parameters and run the following command to assign the user to the app role.

# Prepare parameters for the role assignment  
$params = @{  
    "PrincipalId" = $userId  
    "ResourceId" = $sp.Id  
    "AppRoleId" = $appRoleId  
}  

# 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

Open an elevated Windows PowerShell command prompt.
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.

Get the user and the service principal

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

Get the ID of the role assignment

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

Run the following command to show the list of users assigned to the application
```
$assignments | Select *
```

Run the following command to remove the AppRole assignment.

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

Remove all users assigned to the application using Microsoft Graph PowerShell

Run the following command to remove all users assigned to the application.

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

Manage users assignment to an application

Prerequisites

Assign users to an application using the Microsoft Entra admin center

Unassign users from an application

Assign users to an application using Azure AD PowerShell

Example

Unassign users from an application using Azure AD PowerShell

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

Assign users to an application using Microsoft Graph PowerShell

Example

Unassign users from an application using Microsoft Graph PowerShell

Remove all users assigned to the application using Microsoft Graph PowerShell

Next steps

Additional resources