Kerberos Authentication with K2 Servers

Kerberos authentication is a type of Integrated Windows Authentication that allows delegation of user credentials across multiple servers, allowing a server to pass the credentials of the user to another server or service. In contrast, NTLM, another type of Integrated Windows Authentication, can only pass user credentials to a single server, which is typically between client and server. If those credentials are required by a second server, the NTLM "double-hop" problem is introduced. In a single server environment where all K2 blackpearl components are installed on one server, NTLM can be used. However, Kerberos authentication is required in a distributed environment where K2 blackpearl components or supporting technologies are installed on different servers on the network. An alternative to Kerberos is K2 Pass-Through Authentication (K2PTA), but this may not be suitable in all scenarios. See the K2PTA topics for more information.

You only need Kerberos when there is the potential for two or more hops, like having a your web server separate from your K2 server, for example as seen in the Distributed Environments supported topology topic. You do not need Kerberos in a scenario like in the Single Application server, Separate SQL Server supported topology topic.

The following notes are based on customer support issues that may pertain to your environment. For more information read Kerberos Authentication Overview for Windows Server 2012 (https://technet.microsoft.com/en-us/library/hh831553.aspx).

  1. In Workspace, when configuring a SharePoint service instance to use impersonation, you may need to setup Constrained Delegation for the K2 Service account to delegate credentials to SharePoint. When using Full Delegation it fails with a 401 error when K2 calls SharePoint. Note that this does not apply to SharePoint 2013 or later.
  2. When searching for SmartObjects to create a BDC Application, the Central Administration AppPool account needs to delegate credentials to K2 and must be configured to use Kerberos authentication. This is typically not a problem if the portal site has been configured to use Kerberos and the Central Administration site uses the same AppPool account as the portal site. Configure the Central Admin AppPool account to use Constrained Delegation with Protocol Transition.
  3. It is sometimes necessary to configure the SSRS AppPool account to use Constrained Delegation when delegating credentials to the K2 host server to get reporting data. Using Full Delegation it fails with a 401.

The information in this section is based on the following assumptions:

  1. The administrator or person responsible for configuring Kerberos is familiar with the K2 blackpearl installation documentation.
  2. K2 blackpearl Host Server and other components have been successfully installed.
  3. K2 blackpearl Configuration Analysis tool has been run and completed successfully.
  4. K2 blackpearl Host Server can be started up successfully.
  5. SQL Server and SQL Reporting Services are running properly.
  6. SharePoint Server is running properly (if applicable in the environment).

Kerberos configuration can occur either before or after the installation of K2 blackpearl. The configuration of K2 blackpearl, which occurs directly after installation, allows for the automatic setting of the K2 blackpearl Server SPNs.

RUNTIME RIGHTS REQUIRED BY THE K2 ACCOUNTS

K2 supports a variety of installation configurations, including single server, distributed and server farms.

  • Single Server Installation

    All the K2 blackpearl components, dependencies and prerequisites are installed locally on the same physical machine, with the exception of the SQL 2005 Server, which can be installed on a remote or adjacent physical machine.

    Kerberos is not required in a single server environment. However it is recommended to use Kerberos authentication if K2 solutions will be migrated and deployed to a distributed system environment such as for testing and production.
  • Distributed Installation

    K2 blackpearl components, dependencies and prerequisites are installed on multiple servers across a network. Kerberos must be configured for a distributed installation to function correctly.
  • Server Farm
    A K2 server farm is a clustering environment for multiple K2 Host Servers. There are multiple vendors offering solutions for system clustering and load balancing. Configuration for clustering and / or load balancing systems is beyond the scope of this article.

The following server components and web services require Kerberos authentication when K2 blackpearl is installed in a distributed environment. Some specific K2, SQL and SQL Reporting Service, and SharePoint rights are discussed as they pertain to successfully using the feature or service. In some cases, Kerberos and K2 Impersonation are required for user authentication and for the server or service to act on the users behalf.

The diagrams in the K2 Platform Architecture section of the K2 blackpearl Developer Reference, depict the communication flow of a typical distributed environment. They are separated into the runtime and design time environments. Be aware that although this will give you a better idea how K2 blackpearl components communicate, it may not be representative of your specific environment, and because of that you will need to verify with your network experts the exact nature of the communication flow in your environment.

See the K2 blackpearl Developer Reference for this and more architectural diagrams of the K2 platform.

SharePointService.asmx: The SharePointService web service is a K2 web service that is used to initiate process instances from SharePoint Events. The web service requires Kerberos authentication in a distributed environment to pass credentials from SharePoint to the SharePointService and then to the K2 blackpearl Server. In a SharePoint Workflow Integration process, K2 impersonation is used to pass credentials from the web service to the K2 blackpearl Server.  Note that this does not apply to SharePoint 2013 or later.

SharePoint Wizards (wizards or event templates that allow interaction with SharePoint components, such as documents, search results, list items, records, publishing sites, regular sites and users): The blackpearl server calls the K2 integration components in SharePoint using the blackpearl service account to interact with SharePoint for these events. Note that this does not apply to SharePoint 2013 or later.

K2 Reports (non-SQL Server Reporting Services (SRSS) reports): Authentication occurs as the end-user via Kerberos. K2 Workspace delegates the user's credentials to the blackpearl server to execute the desired action.

K2 Reports (published to SSRS): SSRS delegates the user's credentials to blackpearl to obtain and return the report data based on the users' View and / or View Participate permissions. When publishing a report from Workspace Report Designer, both the blackpearl server and the SSRS server are accessed as the Workspace Application Pool account.

SRSS Reports (imported into Workspace): User accesses the reports on the Workspace home page or accesses the Workspace Reports Designer to run a report in SSRS. Authentication occurs as the end-user via Kerberos. Workspace delegates the user’s credentials to the SQL Reporting Services web site to run the report. The user must have appropriate permissions (at minimum "Browser") in SSRS to run the report. SSRS delegates the user's credentials to the blackpearl server to run the report and return the data based on the users' View and / or View Participate permissions. When importing a report from Workspace Reports Designer, both the blackpearl server and the SSRS server are accessed as the Workspace Application Pool account.

Workspace: A user accesses the Workspace Web site from a remote client and must authenticate using Kerberos. Workspace will delegate the user's credentials to the blackpearl server and authenticate using Kerberos.

K2 Web Designer: Process deployment uses the SharePoint Application Pool account, which must have Export Server Rights in the K2 Workflow Server. The blackpearl database is also accessed directly using the identity of the SharePoint Application Pool account. This account must have at least db_datareader and db_datawriter Roles in the database.

SQL Server (for blackpearl): The blackpearl server accesses the blackpearl databases using the blackpearl service account or via SQL Authentication as the account specified during the install. SPNs for MSSQLSERVER may or may not be required, depending on the environment. In many cases SQL creates SPNs and in other cases, such as when using a named instance, SPNs must be manually created.

SharePoint SmartObject Service instance: If a security provider / username / password is not configured for the Service Instance and Impersonate is not checked, the Service Instance will run under the context of the blackpearl service account and authenticate in SharePoint as such. Note that the Impersonate checkbox should not be used when configuring the service instance as there typically will not be a user to impersonate. Note that this does not apply to SharePoint 2013 or later.

K2 blackpearl Worklist Web part: A user accesses a page in SharePoint that is configured with the K2 Worklist web part and must authenticate using Kerberos. The Web part will delegate the user's credentials to the blackpearl server and authenticate using Kerberos to retrieve the worklist, open worklist items, and action worklist items. The Worklist web part does not use K2 Impersonation and requires Kerberos authentication in a distributed environment.

Forms Generation Client Event: When a user opens a Forms Generation Client Event .ASPX web page they are authenticated using Integrated Windows Authentication. The RuntimeServices Application Pool account authenticates against the blackpearl server and impersonates the user to retrieve the worklist item. The same thing occurs when the user actions the workflow using the form, however the actioning also calls the ClientEventServer.asmx web service. This web service is not used if the process is actioned from the context menu in the Workspace worklist.

The identity used for the RunTimeServices Application Pool must have Impersonate Server Rights in the Workflow Server. Since the ClientEventService.asmx Web service uses impersonation when communicating with the blackpearl server, it will not work with Kerberos alone in a distributed environment as they work in conjunction for authentication and authorization.