K2 blackpearl Product Documentation: Installation and Configuration Guide
Install K2 Workspace on the IIS Server
K2 blackpearl Installation and Configuration Guide > Installation > Installing a distributed environment > Install K2 Workspace on the IIS Server Send feedback

Install K2 Workspace on the IIS Server

Download: You can download an Excel Workbook to help you organize your K2 blackpearl installation by clicking here. Use this checklist to ensure that all topics have been read, understood and implemented successfully before, during and after K2 blackpearl installation. The checklist includes all possible items for both Standalone and Distributed installations. Please read the Reference Topic to determine if the item applies to your environment.

There is also a worksheet where users can record their configured settings as reference.

Prerequisites

 

The K2 Workspace is a web based application used to manage processes and the K2 environment. The K2 Workspace requires the following prerequisites:


K2 blackpearl Prerequisites for the K2 Workspace
Operating System
Windows Components

  • IIS 7.0 with IIS 6.0 Compatibility or IIS 7.0 Management Tools or IIS 8 Manager
  • Distributed Transaction Coordinator (DTC)
  • IPv4 (IPv6 can exist, but IPv4 must also be configured)
  • ASP.NET
  • Windows Authentication Role Services
Additional Software
  • Microsoft .NET Framework 3.5 SP1

http://www.microsoft.com/en-us/download/details.aspx?id=30653

Rights and Permissions

The K2 Workspace Service Account is the account that the K2 Workspace application pool will run under.

The rest of this guide will use domain\K2 Workspace Service Account as a placeholder for the K2 Workspace Service Account name. When installing K2 in your environment, replace this placeholder with your actual account name.

The K2 Workspace Service Account will need the following permissions:

Web Server
Permission Used For
IIS_WPG Local Group

In order to function properly as an application pool within IIS, the K2 Workspace Service Account needs to be a member of this group if Windows Server 2003 is used.
IIS_IUSRS In order to function properly as an application pool within IIS, the K2 Workspace Service Account needs to be a member of this group if Windows Server 2008 is used
Rights Folder or Registry Key
Modify %SYSTEMROOT%\temp

In K2 blackpearl 4.5 the K2 Workspace Report Designer does not use the SSRS server.

SSRS integration is still supported for customers:

Reporting Services Server
Permission Used For
Content Manager

The K2 Workspace Application pool Account (i.e. the Service Account) must be added in the Content Manager role on the SQL Server Machine, where the SSRS Server has been installed and configured.

Application Pool Rights

The K2 Workspace Service Account will require elevated permissions to run the application pool. We will use the aspnet_regiis command to configure this. This tool ships with the .NET Framework, and takes the pain out of configuring all the required NTFS permissions, IIS_WPG group membership, security policy user rights assignments, and IIS metabase access rights. For more information, see the MSDN article on setting security rights for .NET Applications, at http://msdn2.microsoft.com/en-us/library/ms998297.aspx.  

To use the aspnet_regiis command, perform the following steps:

  1. Open a command prompt (Start > Run > cmd)
  2. Change directories to the .NET Framework folder (C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727)
  3. Type aspnet_regiis -ga domain\K2 Workspace Service Account and hit Enter
  4. After the command completes, type iisreset and hit Enter
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 panel 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.

Kerberos / Pass Through Authentication

When components are installed on separate servers, credentials must be passed between the services. This can be accomplished by setting up Kerberos, which should be configured prior to installing K2. Any time where two or more hops are required for user authentication, Kerberos must be configured.

Pass Through Authentication is a K2 proprietary authentication methodology specifically for authenticating users whose credentials need to be passed between machines that interact with the K2 APIs. This authentication model can be used as an alternative to Kerberos, but is not in any way intended to be a replacement for Kerberos within the overall infrastructure.

Install Steps

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

Once the installation is done, the Configuration Analysis tool will be available to help troubleshoot any errors detected during the installation.

It is important to copy the installation files local to the server before installing. Do not install from a network share or UNC path. The installation will not work properly.

It is recommended to install all K2 components using the K2 Service Account. Log on to the server as the K2 Service Account before installing.

To install the K2 Workspace component, follow the below steps:

From the local installation folder, double-click on the Setup.exe file

On the Welcome screen, click Next

On the End User License Agreement screen, read through the EULA. You must select the I agree 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

On the Installation Setup screen, select the Custom Installation option and type in a Installation Folder, and click Next

On the Select Components screen, you should see that the components for which the prerequisites are met are:

  • K2 blackpearl Server,
  • K2 Workspace,
  • K2 blackpearl Setup Manager

    You will want to uncheck the box next to K2 blackpearl Server, as you will not be installing the K2 Server on this machine. You will also see a link to Check Dependencies for the other components.

If you want to install one of the components on this server that have a Check Dependencies action, cancel the installation and fix the dependency. Then, restart the installation and you should be able to select that component.

Before the K2 Workspace can be installed, an IIS Reset will be done to release the assemblies. You will be prompted to reset IIS, if you click No, you cannot continue the installation. If you click Yes, a command window will open and reset IIS, and then the Setup Manager will automatically continue.

On the K2 Database screen, type in the name of the SQL Server where you installed the K2 Database. This points the K2 Workspace to the K2 database set up by the K2 Server, to share configuration information. If you changed the K2 database name, update it here and click Next

On the K2 Workspace Web Site Configuration screen, select the IIS Web Site on which to install the K2 Workspace. If you do not have a K2 Workspace Web Site created, you can create a new one. Enter the address of your web site cluster if appropriate.
               

Select a K2 security Certificate or create a new one by clicking the Browse button. This is to allow both HTTP and HTTPS connections.

To create a new security certificate, select 'Create new Self-Signed Certificate', enter a name in the text box and click OK.

On the K2 Workspace Application Pool Configuration page, select the application pool to use or create/update an application pool.

On the Configuration Summary screen, validate the settings. You can go back to make any necessary changes, and you can print this page for reference later. Once you are satisfied with your settings, click Install.

The Setup Manager will update and show you the progress of the components as it installs.

When the installation has completed, you will see a finished screen. There will also be a link to the created configuration log file. When you click Finish, you will be prompted to restart now (click Yes) or restart later (click No). It is important to restart in order to complete the installation and configuration of K2 blackpearl.

K2 Workspace Service Account

In a distributed environment where components are installed on more than one server or if host headers are used, 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.

Set SPNs

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

The following placeholders are used in the commands:

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 below commands. 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:


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

Configure for Delegation

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.

Open Active Directory Users and Computers (Start > All Programs > Administrative Tools > Active Directory Users and Computers)

Find the domain\K2 Workspace Service Account and view its properties

On the Delegation tab, select the Trust this user for delegation to specified services only option

Select the Use Kerberos only option, and click on Add

Click on Users or Computers and select the domain\K2 Service Account you created as the K2 Server Service Account

In the Available Services section, select both the K2HostServer and K2Server items listed:

Click OK. Your properties should resemble the following:

Click OK. This will allow the K2 Workspace 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 Workspace Service Account should also be allowed to delegate to the SQLRS Account.

Click Add again

Click on Users or Computers and select the domain\Reporting Services Service Account you created as the SQL Reporting Services Service Account

In the Available Services section, select the HTTP item listed:

Click OK. Your properties should now resemble the following:

If you are using SharePoint Integrated process, K2 Workspace Service Account should also be allowed to delegate to the MOSS Account

Click Add again

Click on Users or Computers and select the domain\MOSS Account you created as the MOSS Server Account

In the Available Services section, select the HTTP item listed

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 panel 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.

Enable Direct Metabase Edit

Configuring Kerberos 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.

In order to allow Kerberos authentication on the K2 Workspace web site, you need to first enable the metabase edit in IIS:

  1. Open the Internet Information Services (IIS) Manager (Start > All Programs > Administrative Tools > Internet Information Services (IIS) Manager)
  2. Right-click the top node in the tree view and select Properties
    K2 Workspace - SPN Configuration
  3. Check the check box next to the Enable Direct Metabase Edit option
    Direct Meta Base Edit
  4. Click OK and when prompted, click OK to confirm

Configure K2 Workspace Web Site to use Kerberos

After allowing the Service Account to use delegation, the K2 wWrkspace Web Site still needs to be configured to use Kerberos as an authentication method. This will be done by using the ADSUTIL script.

To configure the K2 Workspace Web Site to use Kerberos, follow the below steps:

  1. Still in IIS Manager, click on the Web Sites node
  2. On the right hand side, you will see all of the configured Web Sites on this server. Locate the Site Identifier for the K2 Workspace web site. In the script below, this will be identified as Site Identifier Be sure to replace this place holder with your actual identifier in the below scripts.
  3. Open a command prompt (Start > Run > cmd)
  4. Change directories to C:\Inetpub\AdminScripts
  5. To force IIS to use Kerberos for the site, execute the following command:

    cscript adsutil.vbs set w3svc/NTAuthenticationProviders "Negotiate,NTLM"
    cscript adsutil.vbs set w3svc/Site Identifier/NTAuthenticationProviders "Negotiate,NTLM"

Important: This command and the parameters are case sensitive. Ensure that the case is correct and that you typed everything correctly. Pay particular attention to the spelling of Negotiate and use double quote marks, these are common errors.

  1. Type iisreset and hit Enter

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 password, and 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:

    Be sure to see the section on Post instillation common tasks once done with the install.

 

 

K2 blackpearl Product Documentation: Installation and Configuration Guide 4.6.11