Upgrade the Web Service

Starting with Privileged Identity version 5.5.2, the web service is a requirement for the web application to function. In prior versions, the web service was an optional component used only for PowerShell cmdlets, application launcher, session recording, and API access.

 

If the web service is installed on a machine that is NOT also hosting the web application, the web service will fail to load unless additional actions are taken. In this scenario, export the web application settings from the management console, then import them onto the web service host.

  1. To export the settings from the management console, follow the steps below.
  2. Click Manage Web App from the left action pane.
  3. Select the desired web application instance from the list.
  4. Go to Advanced and select Export web app registry config. This will export a regedit file.
  5. You will be prompted to generate the file for 64-bit Windows. Click Yes.
  6. Copy the registry export to the target web service host and double-click the file to import it.

These steps provide the web service with the necessary information to connect to the data store, the hardware security module, if configured, and the encryption key, as well as other settings. Any time these options change, it will be necessary to repeat these steps.

 

If the web service is hosted on a different machine than the web application host and the systems are accessed through a URL is different (specifically with regards to the protocol, server name, or port), your web browser will block access to the web service and many things will not function correctly. The basic steps to resolve this are to open the web.config file for the web service after installation, and to set EnableCORS to true. Additional configurations may be required in your specific browser and may not work in all configurations (non-Microsoft browsers especially).

Please refer to your browser's specific documentation for more information on enabling CORS support.

Web service prerequisites are outlined in Web Application Host Requirements , and its service account requirements are outlined in Service Account Requirements .

The web service cannot be pushed to a target system from the management console; it must be installed locally at this time. If installing the web service on the same machine as the management console, the installation of the web service package may be initiated from the management console, by clicking Manage Web App > Install Web Service at the bottom of the Manage Web Application Instances dialog. For remote systems, copy and use the manual installer (ERPMWebService.exe) found in the SupplementalInstallers sub-folder in the installation directory, typically %programfiles(x86)%\Lieberman\Roulette.

During an upgrade, your previous settings will be remembered and will already be selected. You will, however, need to re-enter the password for the COM identity.

  1. Launch the web service installer.
  2. Web Service Installer

  3. On the welcome page, click Next.
  4.  

    COM+ Object Identity

  5. On the COM+ Object Identity, choose an appropriate identity and click Next. Valid identity options are:
    • Network Service: use this option when using database native authentication mode to connect to the database (e.g. SA).
    • Interactive User (not recommended): use this option when it is desired for the user calling the web service to pass their authentication token as the authentication token to the database. This is valid when using Integrated Windows Authentication but will require considerably more security configurations in the program data store.
    • Specific User (default, recommended): use this option when using Integrated Windows Authentication to the database or when it is desired to minimize any rights granted to the COM application. This is the most compatible option. Usernames should be supplied in the format of DomainName\Username.

     

 

Web Installation Type

  1. On Web Installation Type, select the location in the local IIS instance to install the web service to, and click Next. Valid options are:
    • Virtual Directory (default, recommended): will install the web service to a virtual directory called ERPMWebService located under the parent web site you select. This is the safest option to choose for both security and configuration reasons.
    • Site: use this option to install the web service to the root web site. If there are multiple root web sites configured on the host, you will also be presented with a selection of root web sites to choose from.

 

Website options

  1. If you chose Virtual Directory on Web Installation Type, select a web site on Parent Site, and then click Next.

 

Authentication Type

  1. If you chose Site on Web Installation Type, configure site options on Web Site Configuration.
  2. Select the authentication method for connecting to the web service, then click Next. Only methods available to the target parent web site will be displayed. Valid methods include:
    • Anonymous Auth with SSL: use this option when SSL is configured but Integrated Windows Authentication will not be used.
    • Anonymous Auth without SSL (not recommended): use this option when neither Integrated Windows Authentication nor SSL will be used. Application Launcher will not work with this configuration.
    • Integrated Auth with SSL: use this option when SSL and Integrated Windows Authentication will be used.
    • Integrated Auth without SSL: use this option when Integrated Windows Authentication will be used without SSL. Application Launcher will not work with this configuration.
    • SSL with User Certificates - use this option when users must supply a user-based certificate (smart card, biometrics, etc.) to authenticate to the web site and web service. This will incur much more overhead in the overall configuration and may cause problems with Application Launcher.

 

Destination Folder

  1. Select the destination folder for the web service to be installed to and, click Next. The default location is %inetpub%\wwwroot\ERPMWebService, which already grants all required permissions to be properly hosted. Changing the location may require additional configurations on the web server.
  2. When ready, click Install.

 

If you chose to create a virtual directory, this process will create a virtual directory called ERPMWebService. This will inherit the authentication settings, SSL settings, and other settings from the parent web site. This is important because if the parent web site is configured to use anonymous authentication and the installer was configured to use Integrated Windows Authentication, the virtual directory will be created with incorrect settings, and it will be necessary to open IIS and reconfigure the authentication settings post install.

 

  1. Click Finish when the installer is done.

Web Service Tester

  1. Clicking Finish launches the web service page and web service tester. Make note of the Web Service REST URI as it will be required when configuring the web application. At this point, the web service will be non-functional, as it also requires settings from the web application to function. If the web site is installed on the same host as the web service, no further configuration actions will be required for the web service.

 

If you install the web service on a machine that is NOT also hosting the web app, you must export the web app settings from the management console and import them onto the web service host. Otherwise, the web service will fail to load.

To export the settings from the management console, follow the steps outlined below:

  1. Click Manage Web App from the left action pane.
  2. Select the desired web application instance from the list.
  3. From the top tools menu, select Advanced > Export web app registry config. This exports a regedit file, which you will save locally.
  4. When prompted to generate the file for 64-bit Windows, click Yes.
  5. slcCopy the registry export to the target web service host and double-click the file to import it.

These steps provide the web service with the necessary information to connect to the data store, the hardware security module, the encryption key, and other settings. Any time these settings change on the web app host, you must repeat these steps.

If the web service and web app have different host systems, and if the systems are accessed through different URLs (specifically the protocol, server name, or port), your web browser will block access to the web service, causing processes to malfunction.

To resolve this, enable cross-origin resource sharing (CORS). After you have installed the web service, open web.config and set EnableCORS to true.

Your specific browser may require additional configuration and may not work in all configurations. Please refer to your browser's documentation for more information on enabling CORS support.

Please see Post Installation or Upgrade Steps for additional steps and verifications.