Citrix Virtual Apps and Desktops SDK

New-BrokerAccessPolicyRule

Creates a new rule in the site’s access policy.

Syntax

New-BrokerAccessPolicyRule
   [-AllowedConnections <AllowedConnection>]
   [-AllowedProtocols <String[]>]
   [-AllowedUsers <AllowedUser>]
   [-AllowRestart <Boolean>]
   [-AppProtectionKeyLoggingRequired <Boolean>]
   [-AppProtectionScreenCaptureRequired <Boolean>]
   [-Description <String>]
   -DesktopGroupUid <Int32>
   [-Enabled <Boolean>]
   [-ExcludedClientIPFilterEnabled <Boolean>]
   [-ExcludedClientIPs <IPAddressRange[]>]
   [-ExcludedClientNameFilterEnabled <Boolean>]
   [-ExcludedClientNames <String[]>]
   [-ExcludedSmartAccessFilterEnabled <Boolean>]
   [-ExcludedSmartAccessTags <String[]>]
   [-ExcludedUserFilterEnabled <Boolean>]
   [-ExcludedUsers <User[]>]
   [-HdxSslEnabled <Boolean>]
   [-IncludedClientIPFilterEnabled <Boolean>]
   [-IncludedClientIPs <IPAddressRange[]>]
   [-IncludedClientNameFilterEnabled <Boolean>]
   [-IncludedClientNames <String[]>]
   [-IncludedSmartAccessFilterEnabled <Boolean>]
   [-IncludedSmartAccessFilterType <String>]
   [-IncludedSmartAccessTags <String[]>]
   [-IncludedUserFilterEnabled <Boolean>]
   [-IncludedUsers <User[]>]
   [-Name] <String>
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->
New-BrokerAccessPolicyRule
   [-AllowedConnections <AllowedConnection>]
   [-AllowedProtocols <String[]>]
   [-AllowedUsers <AllowedUser>]
   [-AllowRestart <Boolean>]
   [-AppProtectionKeyLoggingRequired <Boolean>]
   [-AppProtectionScreenCaptureRequired <Boolean>]
   [-Description <String>]
   [-Enabled <Boolean>]
   [-ExcludedClientIPFilterEnabled <Boolean>]
   [-ExcludedClientIPs <IPAddressRange[]>]
   [-ExcludedClientNameFilterEnabled <Boolean>]
   [-ExcludedClientNames <String[]>]
   [-ExcludedSmartAccessFilterEnabled <Boolean>]
   [-ExcludedSmartAccessTags <String[]>]
   [-ExcludedUserFilterEnabled <Boolean>]
   [-ExcludedUsers <User[]>]
   [-HdxSslEnabled <Boolean>]
   [-IncludedClientIPFilterEnabled <Boolean>]
   [-IncludedClientIPs <IPAddressRange[]>]
   [-IncludedClientNameFilterEnabled <Boolean>]
   [-IncludedClientNames <String[]>]
   [-IncludedDesktopGroupFilterEnabled <Boolean>]
   -IncludedDesktopGroups <DesktopGroup[]>
   [-IncludedSmartAccessFilterEnabled <Boolean>]
   [-IncludedSmartAccessFilterType <String>]
   [-IncludedSmartAccessTags <String[]>]
   [-IncludedUserFilterEnabled <Boolean>]
   [-IncludedUsers <User[]>]
   [-Name] <String>
   [-LoggingId <Guid>]
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Description

The New-BrokerAccessPolicyRule cmdlet adds a new rule to the site’s access policy.

An access policy rule defines a set of connection filters and access control rights relating to a desktop group. These allow fine-grained control of what access is granted to a desktop group based on details of, for example, a user’s endpoint device, its address, and the user’s identity.

Multiple rules in the access policy can apply to the same desktop group.

For a user to gain access to a desktop group via a rule their connection must match all its enabled include filters, and none of its enabled exclude filters. In addition, for a user to be able to launch a desktop or application resource session from the desktop group, they must have an entitlement to use the resource granted by the entitlement or assignment policies, or by direct machine assignment.

Examples

EXAMPLE 1

Creates an access policy rule allowing access to the Tech Support desktop group for all users of the SUPPORT\uk-staff group. Connections to desktop or application resources in the group can only be made using the HDX protocol.

For users to gain access to resources in the group also requires that, depending on the desktop kind of the group, appropriate assignment or entitlement policy rules, or explicit machine assignments exist.

$dg = Get-BrokerDesktopGroup 'Tech Support'
New-BrokerAccessPolicyRule 'UK Tech Support' -IncludedUserFilterEnabled $true -IncludedUsers support\uk-staff -DesktopGroupUid $dg.Uid -AllowedProtocols 'HDX'
<!--NeedCopy-->

Parameters

-Name

Specifies the administrative name of the new rule. Each rule within the site’s access policy must have a unique name.

Type: String
Position: 2
Default value: None
Required: True
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: True
Length range: 1 to 64
Disallowed characters: /;:#.*?=<>\|[]()"'`\ and all ASCII control characters

-DesktopGroupUid

Specifies the desktop group to which the new rule applies.

Type: Int32
Position: Named
Default value: None
Required: True
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-IncludedDesktopGroups

This parameter is supported for backward compatibility only. If used only a single desktop group UID can be specified.

The IncludedDesktopGroups and IncludedDesktopGroupFilterEnabled parameters have been superseded by the DesktopGroupUid parameter.

Type: DesktopGroup[]
Position: Named
Default value: (empty list)
Required: True
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-AllowedConnections

Specifies whether connections must be local or via Access Gateway, and if so whether specified SmartAccess tags must be provided by Access Gateway with the connection. This property forms part of the included SmartAccess tags filter.

Valid values are Filtered, NotViaAG, ViaAG and AnyViaAG.

For a detailed description of this property see “help about_Broker_AccessPolicy”.

Type: AllowedConnection
Accepted values: Filtered, NotViaAG, ViaAG, AnyViaAG, AnyNotViaAG
Position: Named
Default value: Filtered
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-AllowedProtocols

Specifies the protocols (for example HDX, RDP) available to the user for sessions delivered from the new rule’s desktop group. If the user gains access to a desktop group by multiple rules, the allowed protocol list is the combination of the protocol lists from all those rules.

If the protocol list is empty, access to the desktop group is implicitly denied.

Type: String[]
Position: Named
Default value: HDX
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-AllowedUsers

Specifies the behavior of the included users filter of the new rule. This can restrict access to a list of named users or groups, allow access to any authenticated user, any user (whether authenticated or not), or only non-authenticated users. For a detailed description of this property see “help about_Broker_AccessPolicy”.

Valid values are Filtered, AnyAuthenticated, Any, AnonymousOnly and FilteredOrAnonymous.

Type: AllowedUser
Accepted values: Filtered, AnyAuthenticated, Any, AnonymousOnly, FilteredOrAnonymous
Position: Named
Default value: Filtered
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-AllowRestart

Specifies if the user can restart sessions delivered from the new rule’s desktop group. Session restart is handled as follows: For sessions on single-session power-managed machines, the machine is powered off, and a new session launch request made; for sessions on multi-session machines, a logoff request is issued to the session, and a new session launch request made; otherwise the property is ignored.

Type: Boolean
Position: Named
Default value: False
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-AppProtectionKeyLoggingRequired

Specifies whether key logging app protection is required.

Type: Boolean
Position: Named
Default value: False
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2106

-AppProtectionScreenCaptureRequired

Specifies whether screen capture app protection is required.

Type: Boolean
Position: Named
Default value: False
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2106

-Description

Specifies an optional description of the new rule. The text is purely informational for the administrator, it is never visible to the end user.

Type: String
Position: Named
Default value: None
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: True
Disallowed characters: All ASCII control characters

-Enabled

Specifies whether the new rule is initially enabled. A disabled rule is ignored when evaluating the site’s access policy.

Type: Boolean
Position: Named
Default value: True
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-ExcludedClientIPFilterEnabled

Specifies whether the excluded client IP address filter is initially enabled. If the filter is disabled, it is ignored when the access policy rule is evaluated.

Type: Boolean
Position: Named
Default value: False
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-ExcludedClientIPs

Specifies IP addresses of user devices explicitly denied access to the new rule’s desktop group. Addresses can be specified as simple numeric addresses or as subnet masks (for example, 10.40.37.5 or 10.40.0.0/16). This property forms part of the excluded client IP address filter.

Type: IPAddressRange[]
Position: Named
Default value: (empty list)
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-ExcludedClientNameFilterEnabled

Specifies whether the excluded client names filter is initially enabled. If the filter is disabled, it is ignored when the access policy rule is evaluated.

Type: Boolean
Position: Named
Default value: False
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-ExcludedClientNames

Specifies names of user devices explicitly denied access to the new rule’s desktop group. This property forms part of the excluded client names filter.

Type: String[]
Position: Named
Default value: (empty list)
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-ExcludedSmartAccessFilterEnabled

Specifies whether the excluded SmartAccess tags filter is initially enabled. If the filter is disabled, it is ignored when the access policy rule is evaluated.

Type: Boolean
Position: Named
Default value: False
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-ExcludedSmartAccessTags

Specifies SmartAccess tags which explicitly deny access to the new rule’s desktop group if any occur in those provided with the user’s connection. This property forms part of the excluded SmartAccess tags filter.

Type: String[]
Position: Named
Default value: (empty list)
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-ExcludedUserFilterEnabled

Specifies whether the excluded users filter is initially enabled. If the filter is disabled, it is ignored when the access policy rule is evaluated.

Type: Boolean
Position: Named
Default value: False
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-ExcludedUsers

Specifies any users and groups who are explicitly denied access to the new rule’s desktop group. This property forms part of the excluded users filter.

Type: User[]
Position: Named
Default value: (empty list)
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-HdxSslEnabled

Indicates whether TLS encryption is enabled for sessions delivered from the rule’s desktop group.

Type: Boolean
Position: Named
Default value: $false
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-IncludedClientIPFilterEnabled

Specifies whether the included client IP address filter is initially enabled. If the filter is disabled, it is ignored when the access policy rule is evaluated.

Type: Boolean
Position: Named
Default value: False
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-IncludedClientIPs

Specifies IP addresses of user devices allowed access to the new rule’s desktop group. Addresses can be specified as simple numeric addresses or as subnet masks (for example, 10.40.37.5 or 10.40.0.0/16). This property forms part of the included client IP address filter.

Type: IPAddressRange[]
Position: Named
Default value: (empty list)
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-IncludedClientNameFilterEnabled

Specifies whether the included client name filter is initially enabled. If the filter is disabled, it is ignored when the access policy rule is evaluated.

Type: Boolean
Position: Named
Default value: False
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-IncludedClientNames

Specifies names of user devices allowed access to the new rule’s desktop group. This property forms part of the included client names filter.

Type: String[]
Position: Named
Default value: (empty list)
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-IncludedSmartAccessFilterEnabled

Specifies whether the included SmartAccess tags filter is initially enabled. If the filter is disabled, it is ignored when the access policy rule is evaluated.

Type: Boolean
Position: Named
Default value: False
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-IncludedSmartAccessFilterType

Specifies whether all tags present in IncludedSmartAccessTags must match tags provided by the user’s connection to grant access (MatchAll), or whether any tag matching is sufficient (MatchAny).

Type: String
Accepted values: MatchAny, MatchAll
Position: Named
Default value: MatchAny
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False
Introduced in: Citrix Virtual Apps and Desktop 7 2305

-IncludedSmartAccessTags

Specifies SmartAccess tags which grant access to the new rule’s desktop group if they occur in those provided with the user’s connection. If multiple tags are specified, access also depends on the IncludedSmartAccessFilterType setting. This property forms part of the included SmartAccess tags filter.

Type: String[]
Position: Named
Default value: (empty list)
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-IncludedUserFilterEnabled

Specifies whether the included users filter is initially enabled. If the filter is disabled, it is ignored when the access policy rule is evaluated.

Type: Boolean
Position: Named
Default value: False
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-IncludedUsers

Specifies users and groups who are granted access to the new rule’s desktop group. This property forms part of the included users filter.

Type: User[]
Position: Named
Default value: (empty list)
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-LoggingId

Specifies the identifier of the high level operation that this cmdlet call forms a part of. Desktop Studio and Desktop Director typically create High Level Operations. PowerShell scripts can also wrap a series of cmdlet calls in a High Level Operation by way of the Start-LogHighLevelOperation and Stop-LogHighLevelOperation cmdlets.

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

-IncludedDesktopGroupFilterEnabled

This parameter is supported for backward compatibility only. If used the supplied value must be $true.

The IncludedDesktopGroups and IncludedDesktopGroupFilterEnabled parameters have been superseded by the DesktopGroupUid parameter.

Type: Boolean
Position: Named
Default value: True
Required: False
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

CitrixCommonParameters

This cmdlet supports the common Citrix parameters: -AdminAddress, -AdminClientIP, -BearerToken, -TraceParent, -TraceState and -VirtualSiteId. For more information, see about_CitrixCommonParameters.

CommonParameters

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

Inputs

None

You cannot pipe input into this cmdlet.

Outputs

Citrix.Broker.Admin.SDK.AccessPolicyRule

New-BrokerAccessPolicyRule returns the newly created access policy rule.

New-BrokerAccessPolicyRule