Изменить

Поделиться через

New-EntraUserAppRoleAssignment

  • Reference
Module:
Microsoft.Entra

Assigns a user to an application role.

Syntax

New-EntraUserAppRoleAssignment
   -UserId <String>
   -PrincipalId <String>
   -AppRoleId <String>
   -ResourceId <String>
   [<CommonParameters>]

Description

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

In delegated scenarios with work or school accounts, the signed-in user must have a supported Microsoft Entra role or a custom role with the required permissions. Supported roles include:

  • Directory Synchronization Accounts (for Entra Connect and Cloud Sync)
  • Directory Writer
  • Hybrid Identity Administrator
  • Identity Governance Administrator
  • Privileged Role Administrator
  • User Administrator
  • Application Administrator
  • Cloud Application Administrator

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 = @{
    UserId      = $user.Id
    PrincipalId = $user.Id
    ResourceId  = $servicePrincipal.Id
    AppRoleId   = [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.

  • -UserId 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.
  • -AppRoleId 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'
$servicePrincipal = Get-EntraServicePrincipal -Filter "DisplayName eq 'Box'"
$user = Get-EntraUser -UserId 'SawyerM@contoso.com'
$params = @{
    UserId      = $user.Id
    PrincipalId = $user.Id
    ResourceId  = $servicePrincipal.Id
    AppRoleId   = $servicePrincipal.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.

  • -UserId 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.
  • -AppRoleId parameter specifies the Id of a appRole (defined on the resource service principal) to assign to the user.

Parameters

-AppRoleId

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-Object 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

-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

-UserId

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
Aliases:ObjectId
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False