Add-PswaAuthorizationRule
Add-PswaAuthorizationRule
Adds a Web Access authorization rule.
Syntax
Parameter Set: UserGroupNameComputerGroupName
Add-PswaAuthorizationRule -ComputerGroupName <String> -ConfigurationName <String> -UserGroupName <String[]> [-Force] [-RuleName <String> ] [ <CommonParameters>]
Parameter Set: UserGroupNameComputerName
Add-PswaAuthorizationRule -ComputerName <String> -ConfigurationName <String> -UserGroupName <String[]> [-Force] [-RuleName <String> ] [ <CommonParameters>]
Parameter Set: UserNameComputerGroupName
Add-PswaAuthorizationRule [-UserName] <String[]> -ComputerGroupName <String> -ConfigurationName <String> [-Force] [-RuleName <String> ] [ <CommonParameters>]
Parameter Set: UserNameComputerName
Add-PswaAuthorizationRule [-UserName] <String[]> [-ComputerName] <String> [-ConfigurationName] <String> [-Force] [-RuleName <String> ] [ <CommonParameters>]
Detailed Description
The Add-PswaAuthorizationRule cmdlet adds a new authorization rule to the Windows PowerShell® Web Access authorization rule set.
You must specify the users, computers, and Windows PowerShell endpoints for this rule. You can specify both users and computers either by individual user accounts and computer names, or by specifying groups.
For a computer that is joined to an Active Directory domain, the cmdlet uses the security identifier (SID) of the computer to create the rule. This allows you to use a short name, a fully qualified domain name (FQDN), or an IP address for the Computer Name field on the sign-in page.
For a computer that is not joined to an Active Directory domain, the cmdlet creates the rule using the computer name provided by the administrator. To successfully connect to this machine, the end user must provide the computer name exactly as it appears in the rule.
If there are multiple computers with the same name on the network, then short name can resolve to more than one computer. This can lead to ambiguity when establishing a connection. For example, if a rule exists for the workgroup computer named Server15 and a new computer named server15.contoso.com is joined to the network, validation using the authorization rules succeeds and Windows PowerShell Web Access attempts to establish a connection to the computer named Server15. It is not guaranteed that the connection is established with the specified workgroup computer; the attempt could be made on either the workgroup or the domain computer named Server15. To reduce ambiguity, it is recommended that you use the FQDN for the destination computer whenever possible to create an authorization rule.
The authorization rules evaluate the primary sign-in credential of the Windows PowerShell Web Access users, not the alternate credentials (the second set of credentials found in the Optional connection settings section of the sign-in page). For an example of this, see Example 6.
Parameters
-ComputerGroupName<String>
Specifies the name of a computer group in Active Directory Domain Services (AD DS) or local groups to which this rule grants access.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-ComputerName<String>
Specifies the computer name to which this rule grants access.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-ConfigurationName<String>
Specifies the name of the Windows PowerShell session configuration, also known as runspace, to which this rule grants access.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-Force
Forces the command to run without asking for user confirmation.
In addition, it also prompts for confirmation when you enter a simple or short computer name (such as a name that is not a domain name or is not fully qualified). Confirmation is requested for security reasons, so that you can use the simple name to add a computer only if the computer is in a workgroup.
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-RuleName<String>
Specifies the friendly name for this rule.
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-UserGroupName<String[]>
Specifies the name of one or more user groups in AD DS or local groups to which this rule grants access.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-UserName<String[]>
Specifies one or more users to which this rule grants access. The user name can be a local user account on the gateway computer or a user in AD DS.
The format is domain\user or computer\user.
Aliases |
none |
Required? |
true |
Position? |
1 |
Default Value |
none |
Accept Pipeline Input? |
True (ByValue, ByPropertyName) |
Accept Wildcard Characters? |
false |
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see about_CommonParameters (https://go.microsoft.com/fwlink/p/?LinkID=113216).
Inputs
The input type is the type of the objects that you can pipe to the cmdlet.
String, String[]
This cmdlet accepts a string or an array of strings as input.
Outputs
The output type is the type of the objects that the cmdlet emits.
- Microsoft.Management.PowerShellWebAccess.PswaAuthorizationRule
Examples
EXAMPLE 1: Grant access to the session configuration for users in a group
This command grants access to the session configuration PSWAEndpoint, a restricted runspace, on srv25 for users in the SMAdmins group.
Note: The computer name must be a fully qualified domain name (FQDN). Administrators define a restricted session configuration or runspace, which is a limited range of cmdlets and tasks that end users can run. Defining a restricted runspace can prevent users from accessing other computers that are not in the allowed Windows PowerShell® runspace, thus offering a more secure connection. For more information on session configurations, see about_Session_Configurations or the Windows PowerShell Web Access Help.
PS C:\> Add-PswaAuthorizationRule -ComputerName srv25.contoso.com -UserGroupName "contoso\SMAdmins" -ConfigurationName "PSWAEndpoint"
EXAMPLE 2: Grant specific users access to the default configuration
This command grants access to the default Windows PowerShell session configuration, Microsoft.PowerShell, on srv25 for users in the users named contoso\user10, contoso\user20, and contoso\user30. This cmdlet creates three rules (1 per person).
PS C:\> Add-PswaAuthorizationRule –UserName "contoso\user10, contoso\user20, contoso\user30" –ComputerName "srv25.contoso.com" -ConfigurationName "Microsoft.PowerShell"
EXAMPLE 3: Input user names by using the pipeline
This command inputs user name values by using the pipeline.
PS C:\> "contoso\user10","contoso\user20" | Add-pswaAuthorizationRule –ComputerName "srv25.contoso.com" –ConfigurationName "Microsoft.PowerShell"
EXAMPLE 4: Create named pipeline parameters
This command creates a new object with named parameters in order to pass values to a command from the pipeline by property name.
PS C:\> $o = New-Object -TypeName PSObject | Add-Member -Type NoteProperty -Name "UserName" -Value "contoso\user10" -PassThru | Add-Member -Type NoteProperty -Name "ComputerName" -Value "srv25.contoso.com" -PassThru | Add-Member -Type NoteProperty -Name "ConfigurationName" -Value "Microsoft.PowerShell" –PassThru
This command passes the constructed object to Add-PswaAuthorizationRule by using the pipeline.
PS C:\> $o | Add-PswaAuthorizationRule -UserName "contoso\user10" -ConfigurationName "Microsoft.PowerShell"
EXAMPLE 5: Create a rule to allow a local user server access
This command adds a rule to allow the local user named PswaServer\PattiLocal access to the server named srv10.contoso.com.
This example illustrates a scenario where the gateway is in a workgroup and the destination computer is in a domain. The authorization rule applies to the local users on the gateway. On the Windows PowerShell Web Access sign-in page the user must provide a second set of credentials in the Optional connection settings area to be authenticated. The gateway server uses the additional set of credentials to authenticate the user on the destination computer, a server named srv10.contoso.com.
PS C:\> Add-PswaAuthorizationRule –UserName "PswaServer\PattiLocal" –ComputerName "srv10.contoso.com" –ConfigurationName "Microsoft.PowerShell"
EXAMPLE 6: Disable all authorization rules for testing
This example allows all users access to all endpoints on all computers. This essentially turns off authorization rules.
Note: Use of the * wildcard character is not recommended for security-sensitive deployments and should only be considered for test environments or used in deployments where security can be relaxed.
PS C:\> Add-PswaAuthorizationRule –UserName "*" -ComputerName "*" -ConfigurationName "*"