Updated: November 9, 2012 Applies To: Windows Server 2012 Windows PowerShell® Web Access is a new feature in Windows Server® 2012 that acts as a Windows PowerShell gateway, providing a web-based Windows PowerShell console that is targeted at a remote computer. It enables IT Pros to run Windows PowerShell commands and scripts from a Windows PowerShell console in a web browser, with no Windows PowerShell, remote management software, or browser plug-in installation necessary on the client device. All that is required to run the web-based Windows PowerShell console is a properly-configured Windows PowerShell Web Access gateway, and a client device browser that supports JavaScript® and accepts cookies. Examples of client devices include laptops, non-work personal computers, borrowed computers, tablet computers, web kiosks, computers that are not running a Windows-based operating system, and cell phone browsers. IT Pros can perform critical management tasks on remote Windows-based servers from devices that have access to an Internet connection and a web browser. After successful gateway setup and configuration, users can access a Windows PowerShell console by using a web browser. When users open the secured Windows PowerShell Web Access website, they can run a web-based Windows PowerShell console after successful authentication. Windows PowerShell Web Access setup and configuration is a three-step process: Step 1: Installing Windows PowerShell Web Access Step 2: Configuring the gateway Step 3: Configuring authorization rules and site security Before you install and configure Windows PowerShell Web Access, we recommend that you read both this topic and Use the Web-based Windows PowerShell Console, which describes how users sign in to the web-based console, and some of the limitations and differences in the console. End users of the web-based console should read Use the Web-based Windows PowerShell Console, but do not need to read this topic. This topic does not provide in-depth Web Server (IIS) operations guidance; only those steps required to configure the Windows PowerShell Web Access gateway are described in this topic. For more information about configuring and securing websites in IIS, see the IIS documentation resources in the See Also section. The following diagram shows how Windows PowerShell Web Access works. In this topic: Requirements for running Windows PowerShell Web Access Browser and client device support Step 1: Installing Windows PowerShell Web Access Step 2: Configuring the gateway Step 3: Configuring authorization rules and site security Session management Use the Web-based Windows PowerShell Console Troubleshooting access problems Uninstalling Windows PowerShell Web Access [-] Requirements for running Windows PowerShell Web Access Windows PowerShell Web Access requires Web Server (IIS), .NET Framework 4.5, and Windows PowerShell 3.0 to be running on the server on which you want to run the gateway. You can install Windows PowerShell Web Access on a server that is running Windows Server 2012 by using either the Add Roles and Features Wizard in Server Manager, or Windows PowerShell deployment cmdlets for Server Manager. When you install Windows PowerShell Web Access by using Server Manager or its deployment cmdlets, required roles and features are automatically added as part of the installation process. Windows PowerShell Web Access allows remote users to access computers in your organization by using Windows PowerShell in a web browser. Although Windows PowerShell Web Access is a convenient and powerful management tool, the web-based access poses security risks, and should be configured as securely as possible. We recommend that administrators who configure the Windows PowerShell Web Access gateway use available security layers, both the cmdlet-based authorization rules included with Windows PowerShell Web Access, and security layers that are available in Web Server (IIS) and third-party applications. This documentation includes both unsecure examples that are only recommended for test environments, as well as examples that are recommended for secure deployments. [-] Browser and client device support Windows PowerShell Web Access supports the following Internet browsers. Although mobile browsers are not officially supported, many may be able to run the web-based Windows PowerShell console. Other browsers that accept cookies, run JavaScript, and run HTTPS websites are expected to work, but are not officially tested. [-] Supported desktop computer browsers Windows® Internet Explorer® for Microsoft Windows® 8.0, 9.0, and 10.0 Mozilla Firefox® 10.0.2 Google Chrome™ 17.0.963.56m for Windows Apple Safari® 5.1.2 for Windows Apple Safari 5.1.2 for Mac OS® [-] Minimally-tested mobile devices or browsers Windows Phone 7 and 7.5 Google Android WebKit 3.1 Browser Android 2.2.1 (Kernel 2.6) Apple Safari for iPhone operating system 5.0.1 Apple Safari for iPad 2 operating system 5.0.1 [-] Browser requirements To use the Windows PowerShell Web Access web-based console, browsers must do the following. Allow cookies from the Windows PowerShell Web Access gateway website. Be able to open and read HTTPS pages. Open and run websites that use JavaScript. [-] Step 1: Installing Windows PowerShell Web Access You can install the Windows PowerShell Web Access gateway on a server that is running Windows Server 2012 by using one of the following methods. [-] To install Windows PowerShell Web Access by using the Add Roles and Features Wizard 1. If Server Manager is already open, go on to the next step. If Server Manager is not already open, open it by doing one of the following. On the Windows desktop, start Server Manager by clicking Server Manager in the Windows taskbar. On the Windows Start screen, click Server Manager. 2. On the Manage menu, click Add Roles and Features. 3. On the Select installation type page, select Role-based or feature-based installation. Click Next. 4. On the Select destination server page, select a server from the server pool, or select an offline VHD. To select an offline VHD as your destination server, first select the server on which to mount the VHD, and then select the VHD file. For information about how to add servers to your server pool, see the Server Manager Help. After you have selected the destination server, click Next. 5. On the Select features page of the wizard, expand Windows PowerShell, and then select Windows PowerShell Web Access. 6. Note that you are prompted to add required features, such as .NET Framework 4.5, and role services of Web Server (IIS). Add required features and continue. Note .7. On the Confirm installation selections page, if the feature files for Windows PowerShell Web Access are not stored on the destination server that you selected in step 4, click Specify an alternate source path, and provide the path to the feature files. Otherwise, click Install. 8. After you click Install, the Installation progress page displays installation progress, results, and messages such as warnings, failures, or post-installation configuration steps that are required for Windows PowerShell Web Access. After Windows PowerShell Web Access is installed, you are prompted to review the readme file, which contains basic, required setup instructions for the gateway. These Step 2: Configuring the gateway are also included in this document. The path to the readme file is C:\Windows\Web\PowerShellWebAccess\wwwroot\README.txt. [-] To install Windows PowerShell Web Access by using Windows PowerShell cmdlets 1. Do one of the following to open a Windows PowerShell session with elevated user rights. On the Windows desktop, right-click Windows PowerShell on the taskbar, and then click Run as Administrator. On the Windows Start screen, right-click Windows PowerShell, and then click Run as Administrator. Note 2. Type the following, and then press Enter, where computer_name represents a remote computer on which you want to install Windows PowerShell Web Access, if applicable. The Restart parameter automatically restarts destination servers if required. Install-WindowsFeature –Name WindowsPowerShellWebAccess -ComputerName <computer_name> -IncludeManagementTools -Restart Note To install roles and features on an offline VHD, you must add both the ComputerName parameter and the VHD parameter. The ComputerName parameter contains the name of the server on which to mount the VHD, and the VHD parameter contains the path to the VHD file on the specified server. Install-WindowsFeature –Name WindowsPowerShellWebAccess –VHD <path> -ComputerName <computer_name> -IncludeManagementTools -Restart 3. When installation is complete, verify that Windows PowerShell Web Access was installed on destination servers by running the Get-WindowsFeature cmdlet on a destination server, in a Windows PowerShell console that has been opened with elevated user rights. You can also verify that Windows PowerShell Web Access was installed in the Server Manager console, by selecting a destination server on the All Servers page, and then viewing the Roles and Features tile for the selected server. You can also view the readme file for Windows PowerShell Web Access. 4. After Windows PowerShell Web Access is installed, you are prompted to review the readme file, which contains basic, required setup instructions for the gateway. These setup instructions are also in the following section, Step 2: Configuring the gateway. The path to the readme file is C:\Windows\Web\PowerShellWebAccess\wwwroot\README.txt. [-] Step 2: Configuring the gateway The Install-PswaWebApplication cmdlet is a quick way to get Windows PowerShell Web Access configured. Although you can add the UseTestCertificate parameter to the Install-PswaWebApplication cmdlet to install a self-signed SSL certificate for test purposes, this is not secure; for a secure production environment, always use a valid SSL certificate that has been signed by a certification authority (CA). Administrators can replace the test certificate with a signed certificate of their choice by using the IIS Manager console. You can complete Windows PowerShell Web Access web application configuration either by running the Install-PswaWebApplication cmdlet or by performing GUI-based configuration steps in IIS Manager. By default, the cmdlet installs the web application, pswa (and an application pool for it, pswa_pool), in the Default Web Site container, as shown in IIS Manager; if desired, you can instruct the cmdlet to change the default site container of the web application. IIS Manager offers configuration options that are available for web applications, such as changing the port number or the Secure Sockets Layer (SSL) certificate. Security Note [-] Configuring the gateway by using Install-PswaWebApplication Follow these instructions to configure the Windows PowerShell Web Access gateway by using the Install-PswaWebApplication cmdlet. [-] To configure the Windows PowerShell Web Access gateway with a test certificate by using Install-PswaWebApplication 1. Do one of the following to open a Windows PowerShell session. On the Windows desktop, right-click Windows PowerShell on the taskbar. On the Windows Start screen, click Windows PowerShell. 2. Type the following, and then press Enter. Install-PswaWebApplication -UseTestCertificate Security Note The following settings are configured by running the cmdlet. You can change these manually in the IIS Manager console, if desired. Path: /pswa ApplicationPool: pswa_pool EnabledProtocols: http PhysicalPath: %windir%/Web/PowerShellWebAccess/wwwroot Example: Install-PswaWebApplication –webApplicationName myWebApp –useTestCertificateIn this example, the resulting website for Windows PowerShell Web Access is https://< server_name>/myWebApp. Note [-] To configure the Windows PowerShell Web Access gateway with a genuine certificate by using Install-PswaWebApplication 1. Do one of the following to open a Windows PowerShell session. On the Windows desktop, right-click Windows PowerShell on the taskbar. On the Windows Start screen, click Windows PowerShell. 2. Type the following, and then press Enter. Install-PswaWebApplication The following gateway settings are configured by running the cmdlet. You can change these manually in the IIS Manager console, if desired. You can also specify values for the WebsiteName and WebApplicationName parameters of the Install-PswaWebApplication cmdlet. Path: /pswa ApplicationPool: pswa_pool EnabledProtocols: http PhysicalPath: %windir%/Web/PowerShellWebAccess/wwwroot 3. Open the IIS Manager console by doing one of the following. On the Windows desktop, start Server Manager by clicking Server Manager in the Windows taskbar. On the Tools menu in Server Manager, click Internet Information Services (IIS) Manager. On the Windows Start screen, click Server Manager. 4. In the IIS Manager tree pane, expand the node for the server on which Windows PowerShell Web Access is installed until the Sites folder is visible. Expand the Sites folder. 5. Select the website in which you have installed the Windows PowerShell Web Access web application. In the Actions pane, click Bindings. 6. In the Site Binding dialog box, click Add. 7. In the Add Site Binding dialog box, in the Type field, select https. 8. In the SSL certificate field, select your signed certificate from the drop-down menu. Click OK. See To configure an SSL certificate in IIS Manager in this topic for more information about how to obtain a certificate. The Windows PowerShell Web Access web application is now configured to use your signed SSL certificate. You can access Windows PowerShell Web Access by opening https://<server_name>/pswa in a browser window. Note [-] Configuring the gateway by using IIS Manager Instructions in this section are for installing the Windows PowerShell Web Access web application in a subdirectory—and not in the root directory—of your website. This procedure is the GUI-based equivalent of the actions performed by the Install-PswaWebApplication cmdlet. This section also includes instructions for how to use IIS Manager to configure the Windows PowerShell Web Access gateway as a root website. [-] To use IIS Manager to configure the gateway in an existing website 1. Open the IIS Manager console by doing one of the following. On the Windows desktop, start Server Manager by clicking Server Manager in the Windows taskbar. On the Tools menu in Server Manager, click Internet Information Services (IIS) Manager. On the Windows Start screen, type any part of the name Internet Information Services (IIS) Manager. Click the shortcut when it is displayed in the Apps results. 2. Create a new application pool for Windows PowerShell Web Access. Expand the node of the gateway server in the IIS Manager tree pane, select Application Pools, and click Add Application Pool in the Actions pane. 3. Add a new application pool with the name pswa_pool, or provide another name. Click OK. 4. In the IIS Manager tree pane, expand the node for the server on which Windows PowerShell Web Access is installed until the Sites folder is visible. Select the Sites folder. 5. Right-click the website (for example, Default Web Site) to which you would like to add the Windows PowerShell Web Access website, and then click Add Application. 6. In the Alias field, type pswa, or provide another alias. The alias becomes the virtual directory name. For example, pswa in the following URL represents the alias specified in this step: https://<server_name>/pswa.'>https://<server_name>/pswa. 7. In the Application pool field, select the application pool that you created in step 3. 8. In the Physical path field, browse for the location of the application. You can use the default location, %windir%/Web/PowerShellWebAccess/wwwroot. Click OK. 9. Follow the steps in the procedure To configure an SSL certificate in IIS Manager in this topic. 10. Optional security step: With the website selected in the tree pane, double-click SSL Settings in the content pane. Select Require SSL, and then in the Actions pane, click Apply. Optionally, in the SSL Settings pane, you can require that users connecting to the Windows PowerShell Web Access website have client certificates. Client certificates help to verify the identity of a client device user. For more information about how requiring client certificates can increase the security of Windows PowerShell Web Access, see Security in this topic. 11. Open a browser session on a client device. For more information about supported browsers and devices, see Browser and client device support in this document. 12. Open the new Windows PowerShell Web Access website, https://< gateway_server_name>/pswa. The browser should display the Windows PowerShell Web Access console sign-in page. Note 13. In a Windows PowerShell session that has been opened with elevated user rights (Run as Administrator), run the following script, in which application_pool_name represents the name of the application pool that you created in step 3, to give the application pool access rights to the authorization file. $applicationPoolName = "<application_pool_name>" $authorizationFile = "C:\windows\web\powershellwebaccess\data\AuthorizationRules.xml" c:\windows\system32\icacls.exe $authorizationFile /grant ('"' + "IIS AppPool\$applicationPoolName" + '":R') > $null To view existing access rights on the authorization file, run the following command: c:\windows\system32\icacls.exe $authorizationFile [-] To use IIS Manager to configure the Windows PowerShell Web Access gateway as a root website with a test certificate 1. Open the IIS Manager console by doing one of the following. On the Windows desktop, start Server Manager by clicking Server Manager in the Windows taskbar. On the Tools menu in Server Manager, click Internet Information Services (IIS) Manager. On the Windows Start screen, type any part of the name Internet Information Services (IIS) Manager. Click the shortcut when it is displayed in the Apps results. 2. In the IIS Manager tree pane, expand the node for the server on which Windows PowerShell Web Access is installed until the Sites folder is visible. Select the Sites folder. 3. In the Actions pane, click Add Website. 4. Type a name for the website, such as Windows PowerShell Web Access. 5. An application pool is automatically created for the new website. To use a different application pool, click Select to select an application pool to associate with the new website. Select the alternate application pool in the Select Application Pool dialog box, and then click OK. 6. In the Physical path text box, navigate to %windir%/Web/PowerShellWebAccess/wwwroot. 7. In the Type field of the Binding area, select https. 8. Assign a port number to the website that is not already in use by another site or application. To locate open ports, you can run the netstat command in a Command Prompt window. The default port number is 443. Change the default port if another website is already using 443, or if you have other security reasons for changing the port number. If another website that is running on your gateway server is using your selected port, a warning is displayed when you click OK in the Add Website dialog box. You must use an unused port to run Windows PowerShell Web Access. 9. Optionally, if needed for your organization, specify a host name that makes sense to your organization and users, such as Microsoft România | Dispozitive ?i servicii. Click OK. 10. For a more secure production environment, we strongly recommend providing a valid certificate that has been signed by a CA. You must provide an SSL certificate, because users can only connect to Windows PowerShell Web Access through an HTTPS website. See To configure an SSL certificate in IIS Manager in this topic for more information about how to obtain a certificate. 11. Click OK to close the Add Website dialog box. 12. In a Windows PowerShell session that has been opened with elevated user rights (Run as Administrator), run the following script, in which application_pool_name represents the name of the application pool that you created in step 4, to give the application pool access rights to the authorization file. $applicationPoolName = "<application_pool_name>" $authorizationFile = "C:\windows\web\powershellwebaccess\data\AuthorizationRules.xml" c:\windows\system32\icacls.exe $authorizationFile /grant ('"' + "IIS AppPool\$applicationPoolName" + '":R') > $null To view existing access rights on the authorization file, run the following command: c:\windows\system32\icacls.exe $authorizationFile 13. With the new website selected in the IIS Manager tree pane, click Start in the Actions pane to start the website. 14. Open a browser session on a client device. For more information about supported browsers and devices, see Browser and client device support in this document. 15. Open the new Windows PowerShell Web Access website. Because the root website points to the Windows PowerShell Web Access folder, the browser should display the Windows PowerShell Web Access sign-in page when you open https://< gateway_server_name>. You should not need to add /pswa to the URL. Note [-] To configure an SSL certificate in IIS Manager 1. In the IIS Manager tree pane, select the server on which Windows PowerShell Web Access is installed. 2. In the content pane, double click Server Certificates. 3. In the Actions pane, do one of the following. For more information about configuring server certificates in IIS, see Configuring Server Certificates in IIS 7. Click Import to import an existing, valid certificate from a location on your network. Click Create Certificate Request to request a certificate from a CA such as VeriSign™, Thawte, or GeoTrust®. The certificate's common name must match the host header in the request. For example, if the client browser requests Microsoft România | Dispozitive ?i servicii, then the common name must also be Microsoft România | Dispozitive ?i servicii. This is the most secure and recommended option for providing the Windows PowerShell Web Access gateway with a certificate. Click Create a Self-Signed Certificate to create a certificate that you can use immediately, and have signed later by a CA if desired. Specify a friendly name for the self-signed certificate, such as Windows PowerShell Web Access. This option is not considered secure, and is recommended only for a private test environment. 4. After creating or obtaining a certificate, select the website to which the certificate is applied (for example, Default Web Site) in the IIS Manager tree pane, and then click Bindings in the Actions pane. 5. In the Add Site Binding dialog box, add an https binding for the site, if one is not already displayed. If you are not using a self-signed certificate, specify the host name from step 3 of this procedure. If you are using a self-signed certificate, this step is not required. 6. Select the certificate that you obtained or created in step 3 of this procedure, and then click OK. [-] Step 3: Configuring authorization rules and site security After Windows PowerShell Web Access is installed and the gateway is configured, users can open the sign-in page in a browser, but they cannot sign in until the Windows PowerShell Web Access administrator grants users access explicitly. Windows PowerShell Web Access access control is managed by using the set of Windows PowerShell cmdlets described in the following table. There is no comparable GUI for adding or managing authorization rules. For more detailed information about Windows PowerShell Web Access cmdlets, see the cmdlet Help topics linked to in the following table, or see the parent topic, Windows PowerShell Web Access Cmdlets. Administrators can define 0-n authentication rules for Windows PowerShell Web Access. The default security is restrictive rather than permissive; zero authentication rules means no users have access to anything. Windows PowerShell Web Access authentication rules are whitelist rules. Each rule is a definition of an allowed connection between users, target computers, and particular Windows PowerShell session configurations (also referred to as endpoints or runspaces) on specified target computers. Security Note [table=width: 650, class: grid, align: center] [tr] [td]Name[/td] [td]Description[/td] [td]Parameters[/td] [/tr] [tr] [td]Add-PswaAuthorizationRule[/td] [td]Adds a new authorization rule to the Windows PowerShell Web Access authorization rule set.[/td] [td] ComputerGroupName ComputerName ConfigurationName RuleName UserGroupName UserName [/td] [/tr] [tr] [td]Remove-PswaAuthorizationRule[/td] [td]Removes a specified authorization rule from Windows PowerShell Web Access.[/td] [td] Id RuleName [/td] [/tr] [tr] [td]Get-PswaAuthorizationRule[/td] [td]Returns a set of Windows PowerShell Web Access authorization rules. When it is used without parameters, the cmdlet returns all rules.[/td] [td] Id RuleName [/td] [/tr] [tr] [td]Test-PswaAuthorizationRule[/td] [td]Evaluates authorization rules to determine if a specific user, computer, or session configuration access request is authorized. By default, if no parameters are added, the cmdlet evaluates all authorization rules. By adding parameters, administrators can specify an authorization rule or a subset of rules to test.[/td] [td] ComputerName ConfigurationName RuleName UserName [/td] [/tr] [/table] The preceding cmdlets create a set of access rules which are used to authorize a user on the Windows PowerShell Web Access gateway. The rules are different from the access control lists (ACLs) on the destination computer, and provide an additional layer of security for web access. More details about security are described in the following section. If users cannot pass any of the preceding security layers, they receive a generic “access denied” message in their browser windows. Although security details are logged on the gateway server, end users are not shown information about how many security layers they passed, or at which layer the sign-in or authentication failure occurred. For more information about configuring authorization rules, see Configuring authorization rules in this topic. [-] Security The Windows PowerShell Web Access security model has four layers between an end user of the web-based console, and a target computer. Windows PowerShell Web Access administrators can add security layers through additional configuration in the IIS Manager console. For more information about securing websites in the IIS Manager console, see Configure Web Server Security (IIS 7). For more information about IIS best practices and preventing denial-of-service attacks, see Best Practices for Preventing DoS/Denial of Service Attacks. An administrator can also buy and install additional, retail authentication software. The following table describes the four layers of security between end users and target computers. [table=width: 700, class: grid, align: center] [tr] [td]Order[/td] [td]Layer[/td] [td]Description[/td] [/tr] [tr] [td]1[/td] [td]Web Server (IIS) security features, such as client certificate authentication[/td] [td]indows PowerShell Web Access users must always provide a user name and password to authenticate their accounts on the gateway. However, Windows PowerShell Web Access administrators can also turn optional client certificate authentication on or off (see step 10 of To use IIS Manager to configure the gateway in an existing website in this document). The optional client certificate feature requires end users to have a valid client certificate, in addition to their user names and passwords, and is part of Web Server (IIS) configuration. When the client certificate layer is enabled, the Windows PowerShell Web Access sign-in page prompts users to provide valid certificates before their sign-in credentials are evaluated. Client certificate authentication automatically checks for the client certificate. If a valid certificate is not found, Windows PowerShell Web Access informs users, so they can provide the certificate. If a valid client certificate is found, Windows PowerShell Web Access opens the sign-in page for users to provide their user names and passwords. This is one example of additional security settings that are offered by Web Server (IIS). For more information about other IIS security features, see Configure Web Server Security (IIS 7).[/td] [/tr] [tr] [td]2[/td] [td]Windows PowerShell Web Access forms-based gateway authentication[/td] [td]The Windows PowerShell Web Access sign-in page requires a set of credentials (user name and password) and offers users the option of providing different credentials for the target computer. If the user does not provide alternate credentials, the primary user name and password that are used to connect to the gateway are also used to connect to the target computer. The required credentials are authenticated on the Windows PowerShell Web Access gateway. These credentials must be valid user accounts on either the local Windows PowerShell Web Access gateway server, or in Active Directory®. After a user is authenticated at the gateway, Windows PowerShell Web Access checks authorization rules to verify if the user has access to the requested target computer. After successful authorization, the user’s credentials are passed along to the target computer.[/td] [/tr] [tr] [td]3[/td] [td]Windows PowerShell Web Access authorization rules[/td] [td]After a user is authenticated at the gateway, Windows PowerShell Web Access checks authorization rules to verify if the user has access to the requested target computer. After successful authorization, the user’s credentials are passed along to the target computer. These rules are evaluated only after a user has been authenticated by the gateway, and before a user can be authenticated on a target computer.[/td] [/tr] [tr] [td]4[/td] [td]Target authentication and authorization rules[/td] [td]The final layer of security for Windows PowerShell Web Access is the target computer’s own security configuration. Users must have the appropriate access rights configured on the target computer, and also in the Windows PowerShell Web Access authorization rules, to run a Windows PowerShell web-based console that affects a target computer through Windows PowerShell Web Access. This layer offers the same security mechanisms that would evaluate connection attempts if users tried to create a remote Windows PowerShell session to a target computer from within Windows PowerShell by running the Enter-PSSession or New-PSSession cmdlets. By default, Windows PowerShell Web Access uses the primary user name and password for authentication on both the gateway and the target computer. The web-based sign-in page, in a section titled Optional connection settings, offers users the option of providing different credentials for the target computer, if they are required. If the user does not provide alternate credentials, the primary user name and password that are used to connect to the gateway are also used to connect to the target computer. Authorization rules can be used to allow users access to a particular session configuration. You can create restricted runspaces or session configurations for Windows PowerShell Web Access, and allow specific users to connect only to specific session configurations when they sign in to Windows PowerShell Web Access. You can use access control lists (ACLs) to determine which users have access to specific endpoints, and further restrict access to the endpoint for a specific set of users by using authorization rules described in this section. For more information about restricted runspaces, see Constrained Runspaces on MSDN.[/td] [/tr] [/table] [-] Configuring authorization rules Administrators likely want the same authorization rule for Windows PowerShell Web Access users that is already defined in their environment for Windows PowerShell remote management. The first procedure in this section describes how to add a secure authorization rule that grants access to one user, signing in to manage one computer, and within a single session configuration. The second procedure describes how to remove an authorization rule that is no longer needed. If you plan to use custom session configurations to allow specific users to work only within restricted runspaces in Windows PowerShell Web Access, create your custom session configurations before you add authorization rules that refer to them. You cannot use the Windows PowerShell Web Access cmdlets to create custom session configurations. For more information about creating custom session configurations, see about_Session_Configuration_Files on MSDN. Windows PowerShell Web Access cmdlets support one wildcard character, an asterisk ( * ). Wildcard characters within strings are not supported; use a single asterisk per property (users, computers, or session configurations). [-] To add a restrictive authorization rule 1. Do one of the following to open a Windows PowerShell session with elevated user rights. On the Windows desktop, right-click Windows PowerShell on the taskbar, and then click Run as Administrator. On the Windows Start screen, right-click Windows PowerShell, and then click Run as Administrator. 2. Optional step for restricting user access by using session configurations: Verify that session configurations that you want to use in your rules already exist. If they have not yet been created, use instructions for creating session configurations in about_Session_Configuration_Files on MSDN. 3. Type the following, and then press Enter. Add-PswaAuthorizationRule –UserName <domain\user | computer\user> -ComputerName <computer_name> -ConfigurationName <session_configuration_name> This authorization rule allows a specific user access to one computer on the network to which they typically have access, with access to a specific session configuration that is scoped to the user’s typical scripting and cmdlet needs. In the following example, a user named JSmith in the Contoso domain is granted access to manage the computer Contoso_214, and use a session configuration named NewAdminsOnly. 4. Add-PswaAuthorizationRule –UserName Contoso\JSmith -ComputerName Contoso_214 -ConfigurationName NewAdminsOnly Verify that the rule has been created by running the Get-PswaAuthorizationRule cmdlet. Note [-] To remove an authorization rule 1. If a Windows PowerShell session is not already open, see step 1 of To add a nonrestrictive authorization rule in this section. 2. Type the following, and then press Enter, where rule ID represents the unique ID number of the rule that you want to remove. Remove-PswaAuthorizationRule -ID <rule ID> Alternatively, if you do not know the ID number, but know the friendly name of the rule you want to remove, you can get the name of the rule, and pipe it to the Remove-PswaAuthorizationRule cmdlet to remove the rule, as shown in the following example: Get-PswaAuthorizationRule -RuleName <rule name> | Remove-PswaAuthorizationRule. Note [-] Other authorization rule scenario examples Every Windows PowerShell session uses a session configuration; if one is not specified for a session, Windows PowerShell uses the default, built-in Windows PowerShell session configuration, called Microsoft.PowerShell. The default session configuration includes all cmdlets that are available on a computer. Administrators can restrict access to all computers by defining a session configuration with a restricted runspace (a limited range of cmdlets and tasks that their end users could perform). A user who is granted access to one computer with either full language access or only the Windows PowerShell remote management cmdlets can connect to other computers that are connected to the first computer. Defining a restricted runspace can prevent users from accessing other computers from their allowed Windows PowerShell runspace, and improves the security of your Windows PowerShell Web Access environment. The session configuration can be distributed (by using Group Policy) to all computers that administrators want to make accessible through Windows PowerShell Web Access. For more information about session configurations, see about_Session_Configurations. The following are some examples of this scenario. An administrator creates an endpoint, called PswaEndpoint, with a restricted runspace. Then, the administrator creates a rule, *,*,PswaEndpoint, and distributes the endpoint to other computers. The rule allows all users to access all computers with the endpoint PswaEndpoint. If this is the only authorization rule defined in the rule set, computers without that endpoint would not be accessible. The administrator created an endpoint with a restricted runspace called PswaEndpoint,and wants to restrict access to specific users. The administrator creates a group of users called Level1Support, and defines the following rule: Level1Support,*,PswaEndpoint. The rule grants any users in the group Level1Support access to all computers with the PswaEndpoint configuration. Similarly, access can be restricted to a specific set of computers. Some administrators provide certain users more access than others. For example, an administrator creates two user groups, Admins and BasicSupport. The administrator also creates an endpoint with a restricted runspace called PswaEndpoint, and defines the following two rules: Admins,*,* and BasicSupport,*,PswaEndpoint. The first rule provides all users in the Admin group access to all computers, and the second rule provides all users in the BasicSupport group access only to those computers with PswaEndpoint. An administrator has set up a private test environment, and wants to allow all authorized network users access to all computers on the network to which they typically have access, with access to all session configurations to which they typically have access. Because this is a private test environment, the administrator creates an authorization rule that is not secure. The administrator runs the cmdlet Add-PswaAuthorizationRule * * *, which uses the wildcard character * to represent all users, all computers, and all configurations. This rule is the equivalent of the following: Add-PswaAuthorizationRule –UserName * -ComputerName * -ConfigurationName *. Security Note An administrator must allow users to connect to target computers in an environment that includes both workgroups and domains, where workgroup computers are occasionally used to connect to target computers in domains, and computers in domains are occasionally used to connect to target computers in workgroups. The administrator has a gateway server, PswaServer, in a workgroup; and target computer srv1.contoso.com is in a domain. User Chris is an authorized local user on both the workgroup gateway server and the target computer. His user name on the workgroup server is chrisLocal; and his user name on the target computer is contoso\chris. To authorize access to srv1.contoso.com for Chris, the administrator adds the following rule. Add-PswaAuthorizationRule –userName PswaServer\chrisLocal –computerName srv1.contoso.com –configurationName Microsoft.PowerShell The preceding rule example authenticates Chris on the gateway server, and then authorizes his access to srv1. On the sign-in page, Chris must provide a second set of credentials in the Optional connection settings area (contoso\chris). The gateway server uses the additional set of credentials to authenticate him on the target computer, srv1.contoso.com. In the preceding scenario, Windows PowerShell Web Access establishes a successful connection to the target computer only after the following have been successful, and allowed by at least one authorization rule. 1. Authentication on the workgroup gateway server by adding a user name in the format server_name\user_name to the authorization rule 2. Authentication on the target computer by using alternate credentials provided on the sign-in page, in the Optional connection settings area Note [-] Using a single set of authorization rules for multiple sites Authorization rules are stored in an XML file. By default, the path name of the XML file is %windir%\Web\PowershellWebAccess\data\AuthorizationRules.xml. The path to the authorization rules XML file is stored in the powwa.config file, which is found in %windir%\Web\PowershellWebAccess\data. The administrator has the flexibility to change the reference to the default path in powwa.config to suit preferences or requirements. Allowing the administrator to change the location of the file lets multiple Windows PowerShell Web Access gateways use the same authorization rules, if such a configuration is desired. [-] Session management By default, Windows PowerShell Web Access limits a user to three sessions at one time. You can edit the web application’s web.config file in IIS Manager to support a different number of sessions per user. The path to the web.config file is $Env:Windir\Web\PowerShellWebAccess\wwwroot\Web.config. By default, Web Server (IIS) is configured to restart the application pool if any settings are edited. For example, the application pool is restarted if changes are made to the web.config file. Because Windows PowerShell Web Access uses in-memory session states, users signed in to Windows PowerShell Web Access sessions lose their sessions when the application pool is restarted. Windows PowerShell Web Access sessions time out. A time-out message is displayed to signed-in users after 15 minutes of session inactivity. If the user does not respond within five minutes after the time-out message is displayed, the session is ended, and the user is signed out. You can change time-out periods for sessions in the website settings in IIS Manager. [-] Using the web-based Windows PowerShell console After Windows PowerShell Web Access is installed and the gateway configuration is finished as described in this topic, the Windows PowerShell web-based console is ready to use. For more information about getting started in the web-based console, see Use the Web-based Windows PowerShell Console. [-] Troubleshooting access problems [table=width: 700, class: grid, align: center] [tr] [td]Problem[/td] [td]Possible cause and solution[/td] [/tr] [tr] [td]Sign-in failure[/td] [td]Failure could occur because of any of the following. An authorization rule that allows the user access to the computer, or a specific session configuration on the remote computer, does not exist. Windows PowerShell Web Access security is restrictive; users must be granted explicit access to remote computers by using authorization rules. For more information about creating authorization rules, see Step 3: Configuring authorization rules and site security in this topic. The user does not have authorized access to the destination computer. This is determined by access control lists (ACLs). For more information, see “Signing in to Windows PowerShell Web Access” in Use the Web-based Windows PowerShell Console, or the Windows PowerShell Team Blog. Windows PowerShell remote management might not be enabled on the destination computer. Verify that it is enabled on the computer to which the user is trying to connect. For more information, see “How to Configure Your Computer for Remoting” in about_Remote_Requirements in the Windows PowerShell About Help Topics. [/td] [/tr] [tr] [td]When users try to sign in to Windows PowerShell Web Access in an Internet Explorer window, they are shown an Internal Server Error page, or Internet Explorer stops responding. This issue is specific to Internet Explorer.[/td] [td]This can occur for users who have signed in with a domain name that contains Chinese characters, or if one or more Chinese characters are part of the gateway server name. To work around this issue, the user should install and run Internet Explorer 10, and then perform the following steps. 1. Change the Internet Explorer Document Mode setting to IE10 standards. Press F12 to open the Developer Tools console. In Internet Explorer 10, click Browser Mode, and then select Internet Explorer 10. Click Document Mode, and then click IE10 standards. Press F12 again to close the Developer Tools console. 2. Disable automatic proxy configuration. In Internet Explorer 10, click Tools, and then click Internet Options. In the Internet Options dialog box, on the Connections tab, click LAN settings. Clear the Automatically detect settings check box. Click OK, and then click OK again to close the Internet Options dialog box. [/td] [/tr] [tr] [td]Cannot connect to a remote workgroup computer[/td] [td]If the destination computer is a member of a workgroup, use the following syntax to provide your user name and sign in to the computer: <workgroup_name>\<user_name>[/td] [/tr] [tr] [td]Cannot find Web Server (IIS) management tools, even though the role was installed[/td] [td]If you installed Windows PowerShell Web Access by using the Install-WindowsFeature cmdlet, management tools are not installed unless the IncludeManagementTools parameter is added to the cmdlet. For an example, see To install Windows PowerShell Web Access by using Windows PowerShell cmdlets in this topic. You can add the IIS Manager console and other IIS management tools that you need by selecting the tools in an Add Roles and Features Wizard session that is targeted at the gateway server. The Add Roles and Features Wizard is opened from within Server Manager.[/td] [/tr] [tr] [td]The Windows PowerShell Web Access website is not accessible[/td] [td]If Enhanced Security Configuration is enabled in Internet Explorer (IE ESC), you can add the Windows PowerShell Web Access website to the list of trusted sites, or disable IE ESC. You can disable IE ESC on the local server properties page in Server Manager. The following error message is displayed while trying to connect when the gateway server is the destination computer, and is also in a workgroup: An authorization failure occurred. Verify that you are authorized to connect to the destination computer. When the gateway server is also the destination server, and it is in a workgroup, specify the user name, computer name, and user group name as shown in the following table. Do not use a dot (.) by itself to represent the computer name.[/td] [/tr] [tr] [td]The following error message is displayed while trying to connect when the gateway server is the destination computer, and is also in a workgroup: An authorization failure occurred. Verify that you are authorized to connect to the destination computer.[/td] [td][table=width: 500, align: center] [tr] [td]Scenario[/td] [td]UserName Parameter[/td] [td]UserGroup Parameter[/td] [td]ComputerName Parameter[/td] [td]ComputerGroup Parameter[/td] [/tr] [tr] [td]Gateway server is in a domain[/td] [td]Server_name\user_name, Localhost\user_name, or .\user_name[/td] [td]Server_name\user_group, Localhost\user_group, or .\user_group[/td] [td]Fully qualified name of gateway server, or Localhost[/td] [td]Server_name\computer_group, Localhost\computer_group, or .\computer_group[/td] [/tr] [tr] [td]Gateway server is in a workgroup[/td] [td]Server_name\user_name, Localhost\user_name, or .\user_name[/td] [td]Server_name\user_group, Localhost\user_group or .\user_group[/td] [td]Server name[/td] [td]Server_name\computer_group, Localhost\computer_group or .\computer_group[/td] [/tr] [tr] [td]Sign in to a gateway server as target computer by using credentials formatted as one of the following. Server_name\user_name Localhost\user_name .\user_name [/td] [/tr] [/table] [/td] [/tr] [tr] [td]A security identifier (SID) is displayed in an authorization rule instead of the syntax user_name/computer_name[/td] [td]Either the rule is no longer valid, or the Active Directory Domain Services query failed. An authorization rule is usually not valid in scenarios where the gateway server was at one time in a workgroup, but was later joined to a domain.[/td] [/tr] [tr] [td]Cannot sign in to a target computer that has been specified in authorization rules as an IPv6 address with a domain.[/td] [td]Authorization rules do not support an IPv6 address in form of a domain name. To specify a destination computer by using an IPv6 address, use the original IPv6 address (that contains colons) in the authorization rule. Both domain and numerical (with colons) IPv6 addresses are supported as the target computer name on the Windows PowerShell Web Access sign-in page, but not in authorization rules. For more information about IPv6 addresses, see How IPv6 Works.[/td] [/tr] [/table] [-] To uninstall Windows PowerShell Web Access by using the Remove Roles and Features Wizard 1. If Server Manager is already open, go on to the next step. If Server Manager is not already open, open it by doing one of the following. On the Windows desktop, start Server Manager by clicking Server Manager in the Windows taskbar. On the Windows Start screen, click Server Manager. 2. On the Manage menu, click Remove Roles and Features. 3. On the Select destination server page, select the server or offline VHD from which you want to remove the feature. To select an offline VHD, first select the server on which to mount the VHD, and then select the VHD file. After you have selected the destination server, click Next. 4. Click Next again to skip to the Remove features page. 5. Clear the check box for Windows PowerShell Web Access, and then click Next. 6. On the Confirm removal selections page, click Remove. 7. After uninstallation is finished, go on to the procedure To delete the Windows PowerShell Web Access website and web applications by using IIS Manager. [-] To uninstall Windows PowerShell Web Access by using Windows PowerShell cmdlets 1. Do one of the following to open a Windows PowerShell session with elevated user rights. If a session is already open, go on to the next step. On the Windows desktop, right-click Windows PowerShell on the taskbar, and then click Run as Administrator. On the Windows Start screen, right-click Windows PowerShell, and then click Run as Administrator. 2. Type the following, and then press Enter, where computer_name represents a remote server from which you want to remove Windows PowerShell Web Access. The –Restart parameter automatically restarts destination servers if required by the removal. Uninstall-WindowsFeature –Name WindowsPowerShellWebAccess -ComputerName <computer_name> -Restart To remove roles and features from an offline VHD, you must add both the -ComputerName parameter and the -VHD parameter. The -ComputerName parameter contains the name of the server on which to mount the VHD, and the -VHD parameter contains the path to the VHD file on the specified server. 3. Uninstall-WindowsFeature –Name WindowsPowerShellWebAccess –VHD <path> -ComputerName <computer_name> -Restart When removal is finished, verify that you removed Windows PowerShell Web Access by opening the All Servers page in Server Manager, selecting a server from which you removed the feature, and viewing the Roles and Features tile on the page for the selected server. You can also run the Get-WindowsFeature cmdlet targeted at the selected server (Get-WindowsFeature -ComputerName <computer_name>) to view a list of roles and features that are installed on the server. 4. After uninstallation is finished, go on to the procedure To delete the Windows PowerShell Web Access website and web applications by using IIS Manager. [-] To delete the Windows PowerShell Web Access website and web applications by using IIS Manager 1. Open the IIS Manager console by doing one of the following. If it is already open, go on to the next step. On the Windows desktop, start Server Manager by clicking Server Manager in the Windows taskbar. On the Tools menu in Server Manager, click Internet Information Services (IIS) Manager. On the Windows Start screen, type any part of the name Internet Information Services (IIS) Manager. Click the shortcut when it is displayed in the Apps results. 2. In the IIS Manager tree pane, select the website that is running the Windows PowerShell Web Access web application. 3. In the Actions pane, under Manage Website, click Stop. 4. In the tree pane, right-click the web application in the website that is running the Windows PowerShell Web Access web application, and then click Remove. 5. In the tree pane, select Application Pools, select the Windows PowerShell Web Access application pool folder, click Stop in the Actions pane, and then click Remove in the content pane. 6. Close IIS Manager. Note Source Deploy Windows PowerShell Web Access
