New-RdsRoleAssignment

Module:

WindowsVirtualDesktopPowershell

Creates a role assignment.

Syntax

New-RdsRoleAssignment []

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -SignInName <String>
   -AADTenantId <String>
   [-Deployment]
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -SignInName <String>
   -TenantGroupName <String>
   -AADTenantId <String>
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -SignInName <String>
   [-TenantGroupName <String>]
   -TenantName <String>
   [-AADTenantId <String>]
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -SignInName <String>
   [-TenantGroupName <String>]
   -TenantName <String>
   -HostPoolName <String>
   [-AADTenantId <String>]
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -SignInName <String>
   [-TenantGroupName <String>]
   -TenantName <String>
   -HostPoolName <String>
   -AppGroupName <String>
   [-AADTenantId <String>]
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -ApplicationId <String>
   [-Deployment]
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -ApplicationId <String>
   -TenantGroupName <String>
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -ApplicationId <String>
   [-TenantGroupName <String>]
   -TenantName <String>
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -ApplicationId <String>
   [-TenantGroupName <String>]
   -TenantName <String>
   -HostPoolName <String>
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -ApplicationId <String>
   [-TenantGroupName <String>]
   -TenantName <String>
   -HostPoolName <String>
   -AppGroupName <String>
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -GroupObjectId <String>
   -AADTenantId <String>
   [-Deployment]
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   -GroupObjectId <String>
   -TenantGroupName <String>
   -AADTenantId <String>
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   [-GroupObjectId <String>]
   [-TenantGroupName <String>]
   -TenantName <String>
   [-AADTenantId <String>]
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   [-GroupObjectId <String>]
   [-TenantGroupName <String>]
   -TenantName <String>
   -HostPoolName <String>
   [-AADTenantId <String>]
   [<CommonParameters>]

New-RdsRoleAssignment
   [-RoleDefinitionName] <String>
   [-GroupObjectId <String>]
   [-TenantGroupName <String>]
   -TenantName <String>
   -HostPoolName <String>
   -AppGroupName <String>
   [-AADTenantId <String>]
   [<CommonParameters>]

Description

The New-RdsRoleAssignment cmdlet creates a role assignment by specifying the three properties of a role assignment: the role, the principal, and the scope.

To define the role, you can use one of the following parameters:

• RDS Owner
• RDS Contributor
• RDS Reader
• RDS Operator To understand each of the built-in roles, run Get-RdsRoleDefinition.

To specify the principal, you can use one of the following parameters:

• SignInName
• ApplicationId
• GroupObjectId

To define the scope, you can use a combination of the following parameters:

• TenantGroupName
• TenantName
• HostPoolName
• AppGroupName

Examples

Example 1: Create a role assignment for a user

PS C:\> New-RdsRoleAssignment -RoleDefinitionName "RDS Owner" -SignInName "admin@contoso.com" -TenantGroupName "Default Tenant Group" -TenantName "contoso" -HostPoolName "contosoHostPool" -AppGroupName "Desktop Application Group"

RoleAssignmentId   : cccc-cccc-cccc-cccc-cccc
Scope              : /Default Tenant Group/contoso/contosoHostPool/Desktop Application Group
TenantGroupName    : Default Tenant Group
TenantName         : contoso
HostPoolName       : contosoHostPool
AppGroupName       : Desktop Application Group
DisplayName        : admin
SignInName         : admin@contoso.com
GroupObjectId      : aaaa-aaaa-aaaa-aaaa-aaaa
AADTenantId        : 0000-0000-0000-0000-0000
AppId              : yyyy-yyyy-yyyy-yyyy-yyyy
RoleDefinitionName : RDS Owner
RoleDefinitionId   : 3b14baea-8d82-4610-f5da-08d623dd1cc4
ObjectId           : bbbb-bbbb-bbbb-bbbb-bbbb
ObjectType         : User
Item               :

This commands creates a new role assignment, assigning admin@contoso.com the RDS Owner role at the "Desktop Application Group" app group scope.

Example 2: Create a role assignment for a service principal

PS C:\> New-RdsRoleAssignment -RoleDefinitionName "RDS Reader" -ApplicationId "yyyy-yyyy-yyyy-yyyy-yyyy" -TenantGroupName "contosoTenantGroup" -TenantName "contosoA" -HostPoolName "contosoAHostPool"

RoleAssignmentId   : cccc-cccc-cccc-cccc-cccc
Scope              : /contosoTenantGroup/contosoA/contosoAHostPool
TenantGroupName    : contosoTenantGroup
TenantName         : contosoA
HostPoolName       : contosoAHostPool
AppGroupName       : 
DisplayName        : 
SignInName         : 
GroupObjectId      : 0000-0000-0000-0000-0000
AADTenantId        : 0000-0000-0000-0000-0000
AppId              : yyyy-yyyy-yyyy-yyyy-yyyy
RoleDefinitionName : RDS Reader
RoleDefinitionId   : 2ea11dc0-46e3-4ee8-f5db-08d623dd1cc4
ObjectId           : bbbb-bbbb-bbbb-bbbb-bbbb
ObjectType         : ServicePrincipal
Item               :

This command creates a new role assignment, assigning the specified service principal the RDS Reader role at the "Contoso A Host Pool" host pool scope.

Example 3: Create a role assignment for an Azure AD group

PS C:\> New-RdsRoleAssignment -RoleDefinitionName "RDS Operator" -GroupObjectId "aaaa-aaaa-aaaa-aaaa-aaaa" -TenantGroupName "contosoTenantGroup" -TenantName "contosoA"

RoleAssignmentId   : cccc-cccc-cccc-cccc-cccc
Scope              : /contosoTenantGroup/contosoA
TenantGroupName    : contosoTenantGroup
TenantName         : contosoA
DisplayName        :
SignInName         :
GroupObjectId      : aaaa-aaaa-aaaa-aaaa-aaaa
AADTenantId        : dddd-dddd-dddd-dddd-dddd
AppId              :
RoleDefinitionName : RDS Operator
RoleDefinitionId   : 827a079d-aa89-4d0d-f5dd-08d623dd1cc4
ObjectId           : bbbb-bbbb-bbbb-bbbb-bbbb
ObjectType         : Group
Item               :

This command creates a new role assignment, assigning the specified Azure AD group the RDS Operator role at the "contosoA" tenant scope.

Example 4: Create a role assignment for a user from a different Azure AD tenant

PS C:\> New-RdsRoleAssignment -RoleDefinitionName "RDS Contributor" -SignInName "admin@contosob.com" -TenantGroupName "contosoTenantGroup" -TenantName "contosoA" -AadTenantId "xxxx-xxxx-xxxx-xxxx-xxxx"

RoleAssignmentId   : cccc-cccc-cccc-cccc-cccc
Scope              : /contosoTenantGroup/contosoA
TenantGroupName    : contosoTenantGroup
TenantName         : contosoA
HostPoolName       : 
AppGroupName       : 
DisplayName        : admin
SignInName         : admin@contosob.com
GroupObjectId      : aaaa-aaaa-aaaa-aaaa-aaaa
AADTenantId        : 0000-0000-0000-0000-0000
AppId              : yyyy-yyyy-yyyy-yyyy-yyyy
RoleDefinitionName : RDS Owner
RoleDefinitionId   : 3b14baea-8d82-4610-f5da-08d623dd1cc4
ObjectId           : bbbb-bbbb-bbbb-bbbb-bbbb
ObjectType         : User
Item               :

This command creates a new role assignment, assigning admin@contosob.com the RDS Contributor role at the "contosoA" tenant scope. The AadTenantId parameter is specified since admin@contosob.com does not exist in the Azure AD tenant associated with the Contoso A tenant.

Example 5: Create a role assignment at the tenant group scope

PS C:\> New-RdsRoleAssignment -RoleDefinitionName "RDS Owner" -SignInName "admin@contoso.com" -TenantGroupName "contosoTenantGroup" -AadTenantId "xxxx-xxxx-xxxx-xxxx-xxxx"

RoleAssignmentId   : cccc-cccc-cccc-cccc-cccc
Scope              : /contosoTenantGroup
TenantGroupName    : contosoTenantGroup
TenantName         : 
HostPoolName       : 
AppGroupName       : 
DisplayName        : admin
SignInName         : admin@contoso.com
GroupObjectId      : aaaa-aaaa-aaaa-aaaa-aaaa
AADTenantId        : 0000-0000-0000-0000-0000
AppId              : yyyy-yyyy-yyyy-yyyy-yyyy
RoleDefinitionName : RDS Owner
RoleDefinitionId   : 3b14baea-8d82-4610-f5da-08d623dd1cc4
ObjectId           : bbbb-bbbb-bbbb-bbbb-bbbb
ObjectType         : User
Item               :

This command creates a new role assignment, assigning admin@contoso.com the RDS Owner role at the "contosoTenantGroup" tenant group scope. The AadTenantId parameter is specified since tenant groups are not associated with any specific Azure AD tenant and Windows Virtual Desktop must resolve the user.

Parameters

-AADTenantId

The Azure Active Directory tenant ID of the user. This is required when assigning a user at the tenant group scope. This is also required when assigning a user at the tenant, host pool, or app group scope when they do not exist in the Azure AD tenant associated with the Windows Virtual Desktop tenant.

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

-AppGroupName

The name of the app group.

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

-ApplicationId

The application ID of the service principal.

Type:	String
Aliases:	SPN, ServicePrincipalName
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-Deployment

A scope specific to Windows Virtual Desktop.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-GroupObjectId

The object ID of the Azure AD group.

Type:	String
Aliases:	AADGroupId, UserGroupObjectId
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-HostPoolName

The name of the host pool.

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

-RoleDefinitionName

The name of the role.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-SignInName

The user principal name (UPN) of the user.

Type:	String
Aliases:	Email, UserPrincipalName
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-TenantGroupName

The name of the tenant group.

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

-TenantName

The name of the tenant.

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

Inputs

System.String

System.Management.Automation.SwitchParameter

Outputs

System.Object