Installing the K2 Workspace (Web Server) in a Distributed Environment

After you have installed all the prerequisites, created the service accounts, enabled DTC, you are now ready to install the K2 Workspace.

It is important to copy the installation files local to the server before installing. Do not install from a network share or UNC path.
Installing all K2 components using the K2 Service Account is recommended. Log on to the server as the K2 Service Account before installing.

Installation steps

  1. Launch the K2 Setup Manager.
  2. On the Welcome page, click Next.
  3. On the Checking for Latest Version page, the installation will verify the version, click Next.
  4. On the End User License Agreement page, read through the EULA. You must select the I agree to the terms and conditions of the license option before you can continue with the installation. You can print out the EULA for your records. Once you have read the EULA, click Next.
  5. On the Installation Type page, select the Custom Installation option and type in an Installation Folder, and click Next.
  6. On the Select Components page, check the box next to K2 Workspace
  7. On the Database Configuration page, provide the details for the K2 Database
  8. On the Workspace Web Site Configuration page you can choose to create a new web site or use an existing site.If this is a clustered workspace, be sure to select the Web Site Cluster checkbox and enter the URL used to access the cluster. Using the fully qualified URL to your workspace web site is recommended.
    For information on the Bindings button and pop-up page, see the topic Workspace Web Site Configuration.
  9. On the K2 Workspace Application Pool Configuration page, select an existing Application Pool to use or Update / Create a new Application Pool. Selecting the Set K2 Workspace SPN will allow the Setup Manager to set the SPN for you, leaving the checkbox clear means you need to set the SPN manually after the install.
  10. The SQL Reporting Services Configuration page allows you to integrate with SQL Server Reporting Services, which provides import / export capabilities between K2 reports and SSRS. This integration is not required for viewing or creating K2 reports.
  11. On the Configuration Summary page, validate the settings. You can go back to make any necessary changes, and you can print this page for reference later or copy it to the Clipboard. Once you are satisfied with your settings, click Next.
  12. The Additional Actions page shows you actions the Setup Manager will perform as part of the installation. Click Next to continue.
  13. The Setup Manager will update and show you the progress of the components on the Installing Components page as it installs the software, followed by the Configuration Status page which shows the progress of the configuration of installed components.
  14. Once the installation is done, the Configuration Analysis tool will be available to help troubleshoot any errors detected during the installation.
  15. When the installation has completed, you will see a Finished page. There will also be a link to the created configuration log file.

In a distributed environment where components are installed on more than one server and the double-hop issue exists, Kerberos security must be configured. One of the components of Kerberos is the Service Principal Name (SPN). Whenever user credentials must be passed from one system to another, the system that is attempting to pass the credentials must be trusted for delegation. For this step to take place successfully, Kerberos delegation must be configured.

Configuring SPNs is an advanced task and should only be performed by an appropriately trained professional. The steps and configurations given in this help file are to be used as a guide - your system may require additional configuration due to different hardware and software compatibilities. For information on the setspn command, see the Microsoft Command-Line Reference.
Also note that the graphical interface (GUI) to set SPNs is available and started by executing ADSIedit.msc from the Windows > Start > Run menu. How to use ADSIedit is beyond the scope of this document but the simpler command-line method of setting SPNs has been included.

Set SPNs

In order to access the K2 Workspace from another machine, you need to set the SPNs for the K2 Web Service Account.

The following placeholders are used in the commands:

  • domain\K2 Web Service Account - The K2 Web Service Account that runs the K2 blackpearl application pool.
  • MachineName - The name of the computer on which the K2 Workspace is running.
  • MachineName.FQDN - The fully qualified domain name of the computer on which the K2 Workspace is running.

Be sure to set all the SPNs as listed below. Also, the service account is required so be sure to specify the account properly.

If you have the K2 Workspace running on a cluster, be sure to use the name of the cluster and the fully qualified cluster name instead of a single node's machine name.
If you are using Host Headers to access your K2 Workspace, use the HostHeader value instead of the MachineName in the commands below. An SPN for each Host Header will need to be created.

Open a command prompt on a server that has the Windows Support Tools installed, and execute the following commands:

  • setspn -S HTTP/MachineName domain\K2 Web Service Account
  • setspn -S HTTP/MachineName.FQDN domain\K2 Web Service Account

After the commands have successfully executed, you can verify the SPNs were set by executing the following command:

  • setspn -L domain\K2 Web Service Account

After the SPN has been set, a new Delegation tab is available in Active Directory Users and Computers for the Service Account. By default, the option selected is the Do not trust this user for delegation. You need to set the account to be trusted for delegation, by following the below steps:

If you are running your Active Directory domain in Windows 2000 native mode, the Delegation tab will not be present. Instead, on the Account tab, you will see a Trust this user for delegation check box.

  1. Open Active Directory Users and Computers (Start > All Programs > Administrative Tools > Active Directory Users and Computers).
  2. Find the domain\K2 Web Service Account and view its properties.
  3. On the Delegation tab, select the Trust this user for delegation to specified services only option.
  4. Select the Use Kerberos only option, and click on Add.
  5. Click on Users or Computers and select the domain\K2 Service Account you created as the K2 Server Service Account.
  6. In the Available Services section, select both the K2HostServer and K2Server items listed:

  7. Click OK. Your properties should resemble the following:

  8. Click OK. This will allow the K2 Web Service Account to delegate to the K2 Server Service Account.
    Also, since the SQL Reporting Services reports will also be rendered in the K2 Workspace, the K2 Web Service Account should also be allowed to delegate to the SQLRS Account.
  9. Click Add again.
  10. Click on Users or Computers and select the domain\Reporting Services Service Account you created as the SQL Reporting Services Service Account.
  11. In the Available Services section, select the HTTP item listed:

  12. Click OK. Your properties should now resemble the following:

  13. If you are using SharePoint Integrated process, K2 Web Service Account should also be allowed to delegate to the SharePoint Account.
  14. Click Add again.
  15. Click on Users or Computers and select the domain\MOSS Account you created as the SharePoint Server Account.
  16. In the Available Services section, select the HTTP item listed.
  17. Click OK.

While infrastructure changes are required by K2, each environment is different and has its peculiarities which must be taken into account. Modifying the infrastructure could have unforeseen results if the changes are not appropriately understood or managed. Given the broad spectrum of underlying infrastructure utilized, it is recommended that a page or committee with appropriate skill in each area concerned be assembled to outline the underlying infrastructure changes and gauge the impact of the required changes.

After installing and configuring the K2 Workspace component, you can validate that the Workspace is functioning properly by running the K2 Service in console mode and then accessing the K2 Workspace from a different machine. Console mode is a useful troubleshooting tool, as all error and informational messages are sent to the console window so you can watch what is going on. It is important that you run the service as the Service Account in order to accurately troubleshoot permissions and other errors. It is also important that you have your browser settings configured correctly to pass through your credentials.

To run in console mode, perform the following steps:

  1. Open the Services manager (Start > All Programs > Administrative Tools > Services).
  2. Scroll down to the K2 blackpearl Server service, select it and click the Stop Service button.
  3. Once the service shows as stopped, you can close the Services manager.
  4. Right-click on the K2 blackpearl Server item in the Start menu (under Start > All Programs > K2 blackpearl) and select Run as...
  5. Select The following user option, and type in the domain\K2 Service Account as the User Name and enter the password, then click OK.
    The K2 Server will start and initialize. You will see several messages starting the various components. Once you see the line stating "Info 7010 MSMQ Thread Listing", you know the service has started successfully.
  6. Next, open Internet Explorer from the K2 Server machine. Access the K2 Workspace home page. You should see the K2 Workspace home page, with no items available in the worklist:
  7. Also, you should see a message in the K2 Server console window showing that Kerberos was used for authentication: