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 *

Get-PswaAuthorizationRule

Remove-PswaAuthorizationRule

Test-PswaAuthorizationRule

Install-PswaWebApplication

Add-Member

New-Object