New-EntraUserAppRoleAssignment

Module:

Microsoft.Graph.Entra

Assigns a user to an application role.

Syntax

New-EntraUserAppRoleAssignment
   -ObjectId <String>
   -PrincipalId <String>
   -Id <String>
   -ResourceId <String>
   [<CommonParameters>]

Description

The New-EntraUserAppRoleAssignment cmdlet assigns a user to an application role in Microsoft Entra ID.

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

• PrincipalId: The Id of the user to whom you are assigning the app role.

• ResourceId: The Id of the resource servicePrincipal that has defined the app role.

• Id: The Id of the appRole (defined on the resource service principal) to assign to the user.

Examples

Example 1: Assign a user to an application without roles

Connect-Entra -Scopes 'AppRoleAssignment.ReadWrite.All'
$appId = (Get-EntraApplication -SearchString '<App-DisplayName>').AppId
$user = Get-EntraUser -SearchString '<UserPrincipalName>'
$servicePrincipal = Get-EntraServicePrincipal -Filter "appId eq '$appId'"

$params = @{
    ObjectId    = $user.ObjectId
    PrincipalId = $user.ObjectId
    ResourceId  = $servicePrincipal.ObjectId
    Id          = [Guid]::Empty
}

New-EntraUserAppRoleAssignment @params

DeletedDateTime Id                                          AppRoleId                            CreatedDateTime     PrincipalDisplayName PrincipalId                          PrincipalType ResourceDisplayName
--------------- --                                          ---------                            ---------------     -------------------- -----------                          ------------- ------------------- -
                A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u 00aa00aa-bb11-cc22-dd33-44ee44ee44ee 18-06-2024 11:22:40 UserPrincipalName          aaaaaaaa-bbbb-cccc-1111-222222222222 User          App-DisplayName

This command assigns a user to an application that doesn't have any roles.
You can use the command Get-EntraUser to get user object Id.
You can use the command Get-EntraApplication to get application Id.
You can use the command Get-EntraServicePrincipal to get service principal object Id.

• -ObjectId parameter specifies the Id of a user to whom you are assigning the app role.
• -PrincipalId parameter specifies the Id of a user to whom you are assigning the app role.
• -ResourceId parameter specifies the Id of a resource servicePrincipal that has defined the app role.
• -Id parameter specifies the Id of a appRole (defined on the resource service principal) to assign to the user.

Example 2: Assign a user to a specific role within an application

Connect-Entra -Scopes 'AppRoleAssignment.ReadWrite.All'
$userName = 'SawyerM@contoso.com'
$appName = 'Box'
$spo = Get-EntraServicePrincipal -Filter "DisplayName eq '$appName'"
$user = Get-EntraUser -Filter "userPrincipalName eq '$userName'"

$params = @{
    ObjectId    = $user.ObjectId
    PrincipalId = $user.ObjectId
    ResourceId  = $spo.ObjectId
    Id          = $spo.AppRoles[1].Id
}

New-EntraUserAppRoleAssignment @params

DeletedDateTime Id                                          AppRoleId                            CreatedDateTime     PrincipalDisplayName PrincipalId                          PrincipalType ResourceDisplayName
--------------- --                                          ---------                            ---------------     -------------------- -----------                          ------------- -------------------
                A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u 00aa00aa-bb11-cc22-dd33-44ee44ee44ee 06/18/2024 09:47:00 Sawyer Miller        1aaaaaa1-2bb2-3cc3-4dd4-5eeeeeeeeee5 User          Box

This example demonstrates how to assign a user to an application role in Microsoft Entra ID.
You can use the command Get-EntraUser to get user object Id.
You can use the command Get-EntraServicePrincipal to get service principal object Id.

• -ObjectId parameter specifies the Id of a user to whom you are assigning the app role.
• -PrincipalId parameter specifies the Id of a user to whom you are assigning the app role.
• -ResourceId parameter specifies the Id of a resource servicePrincipal that has defined the app role.
• -Id parameter specifies the Id of a appRole (defined on the resource service principal) to assign to the user.

Parameters

-Id

The ID of the app role to assign.

If application doesn't have any roles while creating new app role assignment then provide an empty guid, or the Id of the role to assign to the user.

You can retrieve the application's roles by examining the application object's AppRoles property:

Get-EntraApplication -SearchString 'Your-Application-DisplayName' | select Approles | Format-List

This cmdlet returns the list of roles that are defined in an application:

AppRoles: {GUID1, GUID2}

Type:	System.String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ObjectId

Specifies the ID of the user (as a UserPrincipalName or ObjectId) in Microsoft Entra ID to which the new app role is to be assigned.

Type:	System.String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-PrincipalId

The object ID of the principal to which the new app role is assigned.

When assigning a new role to a user, provide the object ID of the user.

Type:	System.String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ResourceId

The object ID of the Service Principal for the application to which the user role is assigned.

Type:	System.String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

Related Links

• Get-EntraUserAppRoleAssignment
• Remove-EntraUserAppRoleAssignment