Assign users and groups to an application

This article shows you how to assign users and groups to an enterprise application in Azure Active Directory (Azure AD) 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.

When you assign a group to an application, only users in the group will have access. The assignment doesn't cascade to nested groups.

Group-based assignment requires Azure Active Directory Premium P1 or P2 edition. Group-based assignment is supported for Security groups only. Nested group memberships and Microsoft 365 groups aren't currently supported. For more licensing requirements for the features discussed in this article, see the Azure Active Directory pricing page.

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.

Prerequisites

To assign users to an enterprise application, you need:

  • An Azure AD account with an active subscription. If you don't already have one, you can Create an account for free.
  • One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.
  • Azure Active Directory Premium P1 or P2 for group-based assignment. For more licensing requirements for the features discussed in this article, see the Azure Active Directory pricing page.

To assign a user or group account to an enterprise application:

  1. In the Azure Active Directory Admin Center, select Enterprise applications, and then search for and select the application to which you want to assign the user or group account.

  2. In the left pane, select Users and groups, and then select Add user/group.

    Assign user account to an application in your Azure AD tenant.

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

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

  5. Select Select.

  6. On the Add Assignment pane, select Assign at the bottom of the pane.

  1. Open an elevated Windows PowerShell command prompt.

  2. Run Connect-AzureAD Application.Read.All, Directory.Read.All, Application.ReadWrite.All, Directory.ReadWrite.All and sign in with a Global Admin user account.

  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
    

To assign a group to an enterprise app, you must replace Get-AzureADUser with Get-AzureADGroup and replace New-AzureADUserAppRoleAssignment with New-AzureADGroupAppRoleAssignment.

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

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. Shows the roles available to a user using Workplace Analytics 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, and groups, from an application

  1. Open an elevated Windows PowerShell command prompt.

  2. Run Connect-AzureAD Application.Read.All Directory.Read.All Application.ReadWrite.All Directory.ReadWrite.All and sign in with a Global Admin user account. 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

Use the following script to remove all users and groups 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 and groups 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
    }
}
  1. Open an elevated Windows PowerShell command prompt.
  2. Run Connect-AzureAD Application.Read.All Directory.Read.All Application.ReadWrite.All Directory.ReadWrite.All and sign in with a Global Admin user account.
  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, and groups, from an application

  1. Open an elevated Windows PowerShell command prompt.
  2. Run Connect-AzureAD Application.Read.All Directory.Read.All Application.ReadWrite.All Directory.ReadWrite.All and sign in with a Global Admin user account. 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 and groups assigned to the application

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

$assignments | ForEach-Object {
    if ($_.PrincipalType -in ("user", "Group")) {
        Remove-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $Sp.Id -AppRoleAssignmentId $_.Id  }
}
  1. To assign users and groups to an application, sign in to Graph Explorer with one of the roles listed in the prerequisite section.

    You'll need to consent to the following permissions:

    Application.Read.All, Application.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All.

    To grant an app role assignment, you need three identifiers:

    • principalId: The ID of the user or group to which you're assigning the app role.
    • resourceId: The ID of the resource servicePrincipal that has defined the app role.
    • appRoleId: The ID of the appRole (defined on the resource service principal) to assign to a user or group.
  2. Get the enterprise application. Filter by DisplayName.

    GET servicePrincipal?$filter=DisplayName eq '{appDisplayName}'
    

    Record the following values from the response body:

    • Object ID of the enterprise application
    • appRoleId that you'll assign to the user. If the application doesn't expose any roles, the user will be assigned the default access role.
  3. Get the user by filtering by the user's principal name. Record the object ID of the user.

    GET /users/{userPrincipalName}
    
  4. Assign the user to the application.

    POST /servicePrincipals/resource-servicePrincipal-id/appRoleAssignedTo
    
    {
    "principalId": "33ad69f9-da99-4bed-acd0-3f24235cb296",
    "resourceId": "9028d19c-26a9-4809-8e3f-20ff73e2d75e",
    "appRoleId": "ef7437e6-4f94-4a0a-a110-a439eb2aa8f7"
    }
    

    In the example, both the resource-servicePrincipal-id and resourceId represent the enterprise application.

Unassign users, and groups, from an application

To unassign user and groups from the application, run the following query.

  1. Get the enterprise application. Filter by DisplayName.

    GET servicePrincipal?$filter=DisplayName eq '{appDisplayName}'
    
  2. Get the list of appRoleAssignments for the application.

       GET /servicePrincipals/{id}/appRoleAssignedTo
    
  3. Remove the appRoleAssignments by specifying the appRoleAssignment ID.

    DELETE /servicePrincipals/{resource-servicePrincipal-id}/appRoleAssignedTo/{appRoleAssignment-id}
    

Next steps