Add-PswaAuthorizationRule
[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]
Add-PswaAuthorizationRule
Adds a new authorization rule to the Windows PowerShell® Web Access authorization rule set.
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: UserGroupNameConnectionURI
Add-PswaAuthorizationRule -ConfigurationName <String> -ConnectionUri <Uri> -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>]
Parameter Set: UserNameConnectionURI
Add-PswaAuthorizationRule [-UserName] <String> -ConfigurationName <String> -ConnectionUri <Uri> [-Force] [-RuleName <String> ] [ <CommonParameters>]
Detailed Description
The Add-PswaAuthorizationRule cmdlet adds a new authorization rule to the Windows PowerShell® Web Access authorization rule set.
The administrator must specify the users and computers for this rule. The administrator can specify users either by individual user accounts, or by specifying user groups. The user has three options for how to specify computers:
1) Individual computer names.
2) Computer groups.
3) URI. If a URI is provided, the entire URI is used for rule evaluation.
● ○ <Transport>://<ComputerName>:<Port>/<ApplicationName>
These rules evaluate the primary sign-in credential of the Windows PowerShell Web Access users, not the alternate credentials (the second set of credentials is found in the Optional connection settings section of the sign-in page).
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 |
false |
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? |
2 |
Default Value |
false |
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 |
false |
Accept Pipeline Input? |
true (ByPropertyName) |
Accept Wildcard Characters? |
false |
-ConnectionUri<Uri>
Specifies the connection URI to which this rule grants access. The entire URI is used for rule evaluation.
● ○ <Transport>://<ComputerName>:<Port>/<ApplicationName>
.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
false |
Accept Pipeline Input? |
true (ByPropertyName) |
Accept Wildcard Characters? |
false |
-Force
Runs the cmdlet without prompting for confirmation. By default the cmdlet asks for confirmation from the user before proceeding. In addition, it also prompts for confirmation when a user enters 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 the user 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 |
false |
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 |
false |
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 |
false |
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 |
false |
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.
Inputs
The input type is the type of the objects that you can pipe to the cmdlet.
- None
Outputs
The output type is the type of the objects that the cmdlet emits.
- Microsoft.Management.PowerShellWebAccess.PswaAuthorizationRule
Examples
EXAMPLE 1
This example grants access to the session configuration PSWAEndpoint, a restricted runspace, on srv2 for users in the SMAdmins group. Note: The computer name must be a fully qualified domain name (FQDN). Administrators can restrict access to all computers by defining 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 srv2.contoso.com -UserGroupName contoso\SMAdmins -ConfigurationName PSWAEndpoint
EXAMPLE 2
This example grants users in the SMAdmins group access to the default configuration Microsoft.PowerShell
and to the specified Connection URI.
PS C:\> Add-PswaAuthorizationRule –UserNameGroup SMAdmins –ConnectionUri https://contoso:5985/testman -ConfigurationName Microsoft.PowerShell
EXAMPLE 3
This example grants access to the default Windows PowerShell session configuration, Microsoft.PowerShell
, on srv2 for users in the users named contoso\jonj99, contoso\danj99, and contoso\toddr99. This cmdlet creates three rules (1 per person).
PS C:\> Add-PswaAuthorizationRule –UserName contoso\jonj99, contoso\danj99, contoso\toddr99 –ComputerName srv2.contoso.com -ConfigurationName Microsoft.PowerShell
EXAMPLE 4
This example illustrates how to input username values via the pipeline.
PS C:\> "contoso\jonj99","contoso\danj99" | Add-pswaAuthorizationRule –ComputerName srv2.contoso.com –ConfigurationName Microsoft.PowerShell
EXAMPLE 5
This example illustrates how all parameters take values from pipeline by property name.
PS C:\> $o = New-Object -TypeName PSObject | Add-Member -Type NoteProperty -Name "UserName" -Value "contoso\jonj99" -PassThru | Add-Member -Type NoteProperty -Name "ComputerName" -Value "srv2.contoso.com" -PassThru | Add-Member -Type NoteProperty -Name "ConfigurationName" -Value "Microsoft.PowerShell" –PassThru
PS C:\> $o | Add-PswaAuthorizationRule -UserName contoso\jonj99 -ConfigurationName Microsoft.PowerShell
EXAMPLE 6
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 *