Edit

Share via

New-RdsRoleAssignment

Module:
Microsoft.RDInfra.RDPowershell Module

Creates a role assignment.

Syntax

EmptyParameterSet (Default) 

New-RdsRoleAssignment
    [<CommonParameters>]

SignInNameRoleAssignmentDeploymentScopeParameterSet 

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

SignInNameRoleAssignmentTenantGroupScopeParameterSet 

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

SignInNameRoleAssignmentTenantScopeParameterSet 

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

SignInNameRoleAssignmentHostPoolScopeParameterSet 

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

SignInNameRoleAssignmentAppGroupScopeParameterSet 

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

SPNRoleAssignmentDeploymentScopeParameterSet 

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

SPNRoleAssignmentTenantGroupScopeParameterSet 

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

SPNRoleAssignmentTenantScopeParameterSet 

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

SPNRoleAssignmentHostPoolScopeParameterSet 

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

SPNRoleAssignmentAppGroupScopeParameterSet 

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

GroupRoleAssignmentDeploymentScopeParameterSet 

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

GroupRoleAssignmentTenantGroupScopeParameterSet 

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

GroupRoleAssignmentTenantScopeParameterSet 

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

GroupRoleAssignmentHostPoolScopeParameterSet 

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

GroupRoleAssignmentAppGroupScopeParameterSet 

New-RdsRoleAssignment
    [-RoleDefinitionName] <String>
    -TenantName <String>
    -HostPoolName <String>
    -AppGroupName <String>
    [-GroupObjectId <String>]
    [-TenantGroupName <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.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

SignInNameRoleAssignmentDeploymentScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentTenantGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentDeploymentScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentTenantGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-AppGroupName

The name of the app group.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

SignInNameRoleAssignmentAppGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentAppGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentAppGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-ApplicationId

The application ID of the service principal.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False
Aliases:SPN, ServicePrincipalName

Parameter sets

SPNRoleAssignmentDeploymentScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentTenantGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentTenantScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentHostPoolScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentAppGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Deployment

A scope specific to Windows Virtual Desktop.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

SignInNameRoleAssignmentDeploymentScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentDeploymentScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentDeploymentScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-GroupObjectId

The object ID of the Azure AD group.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False
Aliases:AADGroupId, UserGroupObjectId

Parameter sets

GroupRoleAssignmentDeploymentScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentTenantGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-HostPoolName

The name of the host pool.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

SignInNameRoleAssignmentHostPoolScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentAppGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentHostPoolScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentAppGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentHostPoolScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentAppGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-RoleDefinitionName

The name of the role.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

SignInNameRoleAssignmentDeploymentScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentTenantGroupScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentTenantScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentHostPoolScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentAppGroupScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentDeploymentScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentTenantGroupScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentTenantScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentHostPoolScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentAppGroupScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentDeploymentScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentTenantGroupScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentTenantScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentHostPoolScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentAppGroupScopeParameterSet
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-SignInName

The user principal name (UPN) of the user.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False
Aliases:Email, UserPrincipalName

Parameter sets

SignInNameRoleAssignmentDeploymentScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentTenantGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentTenantScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentHostPoolScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentAppGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-TenantGroupName

The name of the tenant group.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

SignInNameRoleAssignmentTenantGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentTenantGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentTenantGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-TenantName

The name of the tenant.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

SignInNameRoleAssignmentTenantScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentHostPoolScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SignInNameRoleAssignmentAppGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentTenantScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentHostPoolScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
SPNRoleAssignmentAppGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentTenantScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentHostPoolScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
GroupRoleAssignmentAppGroupScopeParameterSet
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

System.String

System.Management.Automation.SwitchParameter

Outputs

System.Object