Assign users and groups to an application in Azure Active Directory

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 roles, you can also assign a specific role to the user.

Prerequisites

To assign users to an app using PowerShell, you need:

  • An Azure account with an active subscription. Create an account for free.
  • One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.
  • If you have not yet installed the AzureAD module (use the command Install-Module -Name AzureAD). If prompted to install a NuGet module or the new Azure Active Directory V2 PowerShell module, type Y and press ENTER.
  • 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.
  • Optional: Completion of Configure an app.

Assign users, and groups, to an app using PowerShell

  1. Open an elevated Windows PowerShell command prompt.

  2. Run Connect-AzureAD 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 app using PowerShell

  1. Open an elevated Windows PowerShell command prompt.

  2. Run Connect-AzureAD 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 #].ObjectId
    

Next steps