Introduction

This article provides guidance for those in technical roles who need to troubleshoot and improve K2 performance. Knowledge of the K2 platform, authentication, and SharePoint is required.

K2 allows for different authentication methods and can be configured to work with most identity stores. Use this article to learn about and troubleshoot authentication issues.

Also see the other articles in this series:

Considerations

Use the following questions and answers to learn more about authentication issues and how to address them:

A – Yes. The K2 installer sets the type of authentication according to the user manager of the environment. With the K2 smartforms 4.6.7 release, SharePoint and Appit integration changed. Appit is dependent on Azure Active Directory, which uses Claims-Based Authentication (CBA). This means that CBA is the default authentication mechanism. K2 has the ability to authenticate using Windows or Forms and ultimately is based on claims authentication. The _trust/Login.aspx in the highlighted field in Internet Information Services (IIS) indicates that CBA is being used in the Forms Authentication, but it also applies to Windows as well.

Image

SharePoint, both on-premises and Online, uses CBA. This can impact authentication performance as multiple redirection calls occur between the K2 server and SharePoint. The diagram below illustrates the redirection between the K2 server and SharePoint.

Image

When you open a form in SharePoint, three authentication processes occur:

  • Sign in to SharePoint portal site
  • Sign in to the Application web where the application.aspx runs – if you load a new form
  • Sign in to SmartForms within the iFrame that resides inside the application. This is where the Secure Token Service (STS) redirects occur.

Beginning with K2 smartforms 4.6.7, the Windows and Forms STSs were added to fully support CBA. This introduced more authentication redirects, but these typically only cost the platform a few milliseconds of additional time. The Redirect URL that is sent to the STS is sent back to K2 smartforms containing a GUID and a Return URL. The URL can be long and is stored in an OAuth session state in the server database to avoid limitations in the overall URL length, a limitation with most browsers.

The image below indicates a typical authentication process when SharePoint accesses K2 smartforms. Chrome Developer Tools are used in the example below. To test this in your environment, open Chrome Developer Tools, and go to the Network tab. Open a SmartForm used in SharePoint and notice the server requests listed under the Network tab. Next to each call is a Status column that lists the status code for each request. These codes indicate if the request was successful or if there is an issue or actual error. Note the time taken for each request listed in the Time column. The long green line on the example indicates where to target your investigation of slow performance.

To enlarge click on the image below

Image

Use the following status code categories to identify errors:

  • 1XX - Information
  • 2XX - Success
  • 3XX - Redirection
  • 4XX - Client Error (such as 404 Not Found)
  • 5XX - Server Error (such as 502 Bad Gateway)

Using the codes above, here is what occurs in the example:

  • The 302 status codes indicate that redirection occurs.
  • The 200 status code means the request is successful.
  • The spauthorize.aspx.cs code handles the session token checks and the URL redirects. It also checks the claims type mappings and cache, and sets the OAuth session state accordingly. During this process, connections are made through the connection pool. Finally, in spauthorize.aspx.cs, a Return URL is acquired from the OAuth session state and this URL is used to populate the iFrame in the SharePoint page so that the form is available in SharePoint. The form cache is checked to see if an instance of the form already exists before the form is loaded.

Based on the above explanation, various factors can lead to a slower loading of a form:

  • Authentication token retrieval and validation delay issues
  • Issues when a claims identity is created based on the token
  • Connection issues when accessing the connection pool
  • Delay in the redirect from the STS
  • OAuth calls can sometimes take a long time, especially if a refresh token is not cached and needs to be obtained first using an authorize token
  • An instance of the requested form is not cached
  • If the browser already has a few tabs open, it may take longer to complete the URL redirects within the iFrame. The iFrame loads already have a negative performance impact, and redirects within iFrames can compound this delay.

If you do not use SharePoint in your environment, you can change the authentication method to Windows authentication to improve performance, effectively bypassing CBA and the use of the STSs. See the resources below for information on SharePoint authentication, SharePoint session lifetime, K2 authentication, and K2 authorization. 

A - Typically, the STS redirect is not the part that is time consuming. Rather the process that follows to authenticate a user and generate a token is typically the source of delay. See the next two questions to change token values and Windows STS settings to improve performance.

A – Yes, you can change the values in the STS’s web.config file to shorten or lengthen the token lifetime. The SessionTokenLifetime and MaximumTokenLifetime keys control how many seconds the Session Token remains valid. This is normally set to around 8 hours (28800 seconds).

To change the settings:

    1. Access the web.config file in the following location:

      <install drive>:\Program Files (x86)\K2 blackpearl\WebServices\Identity\Sts\Windows\Web.config

    2. Change the following values to the required seconds:

      <add key="SessionTokenLifetime" value="3600" />

      <add key="MaximumTokenLifetime" value="3600

This means that the Session Token expires after an hour which can be helpful when you’re debugging performance issues related to the STS.

A – Yes. When the Security Assertion Markup Language (SAML) returns, it contains all the groups to which the user belongs. This can be any Identity Provider such as Azure Active Directory for online/hybrid or Active Directory for on-premises.

You can switch off this process if no authorization decision is based on what groups the user is in at the time of authentication. This reduces the size of the SAML token and improves performance of the initial load of a page, especially if many of your users belong to many groups.

To change the group setting:

  1. Access the web.config file in the following location:

    <install drive>:\Program Files (x86)\K2 blackpearl\WebServices\Identity\Sts\Windows\Web.config

  2. Change the following value to false:
    <add key="AddGroupsToClaims" value="true" />

A – Yes. Internet Information Services (IIS) Application Pool recycling means the process that handles requests for the application pool terminates first and then a new one starts. This is necessary to avoid unstable states that can cause application crashes, hangs, or memory leaks. However, each time the app pool recycles, everything in the IIS cache must be recached, and this can take some time.

The default K2 smartforms Runtime Application Pool settings are as follows:

1. Start Mode - AlwaysRunning

2. Idle Time-out (minutes) - 1440

3. Idle Time-out Action – Suspend

Image

The above settings prevent slow startup because it stops the application pool from restarting each day. Be cautious, however, if you start seeing intermittent behaviors that could be related to a corrupt application pool that needs to be recycled more often.

After a recycle, when you access the site, the K2 smartforms Runtime Application Pool startup process initializes and, during that initialization, the page load is delayed. Subsequent page loads are much faster. Other applications starting at the same time also slow down the first load of the page. Use warm-up scripts to reduce the impact of such an application pool startup. The impact of this process is not relevant in K2 smartforms 4.7 and later due to the introduction of pre-caching.

A – Yes, connection pooling is when database connections do not close but rather return to the pool. They stay active in the pool and are reused by other parts of the same codebase inside the Application Domain (AppDomain). This improves performance since creating new database connections has a relatively high performance overhead.

To change the connection pool setting:

  1. Access the web.config file in the following location:

    <install drive>:\Program Files (x86)\K2 blackpearl\WebServices\Identity\Sts\Windows\Web.config

  2. Change the following value to true:
    <add key="ConnectAsAppPool" value="false"/>

Also see the following resource for more information:

Performance changes introduced with K2 smartforms 1.0.2

A – Yes. Exceptions or issues may occur during the time when connection and authentication occurs, meaning connections must be retried. Note any exceptions you find in the log files and you may also request debug files from K2 Support to investigate further.

One error you may see:

“SourceCode.Security.Claims.Sts.Windows.Controllers.wsFedController: Account 'WindowsIdentity' UPN Error: An operations error occurred.”

This error is logged from the debug assemblies. The exception occurs when the Active Directory Account Management object extracts the User Principal Name (UPN), and is usually due to a communications error such as the network being slow or down, a communications timeout, or DNS problems. More detailed logs and debugging are necessary to identify the specific operation error.

See the following resources for information on error logging:

A – Yes. Misconfigured caching proxies cause problems such as the inability to authenticate users, requests not completing, and the dreaded infinite spinner.

Transparent and reverse proxies can cause the following issues:

  • The connection does not complete and the connect to the server never happens.
  • The connection works locally but not for client requests.

Sometimes proxies require authentication. This happens in the background and affects things like AJAX calls in the form. If there is something wrong with the network, proxy, or firewall, issues can occur in the path between the client requests and the server response. To test this, see if you can access K2 smartforms from another location, preferably bypassing the proxy that is currently in place.

Additional Resources

Consider the following resources to further your learning and investigations.

Plan

Recommendation Resources What you will find
Plan authentication and authorization for your K2 platform. Planning for Authentication Understand and configure authentication within the K2 platform.
SharePoint Hybrid, Multiple Identity Providers & K2 White papers that explain multiple identity providers when configuring K2 authentication, its implications on the end-user experience, and how to design forms to limit the impact to form users.
An introduction to Claims Microsoft Developer Network article explaining Claims Based Authentication.
WS-Federation Microsoft article describing the use of the WS-Federation in selected application scenarios.
Authentication and Authorization in K2 White papers that discuss how:
  • User identities flow into K2, by what mechanisms, and how they are verified.
  • Users are authorized for resources internal to K2.
  • Users and the K2 server are authorized for resources external to K2.Users, groups and roles are managed by K2
K2 Pass-Through Authentication Why and how to configure K2 Pass-Through Authentication
Kerberos in K2 Various articles about Kerberos in K2

Tools

See the following resources for strategies on monitoring your environment, potential K2 performance and scalability, and web debugger tools. Some of these tools are used in the Considerations section.

Recommendation Resources What you will find
Monitor performance on your environment. Monitoring the K2 blackpearl Environment
K2 Performance Test Results by Version
Overview of the recommended performance monitoring options for K2 blackpearl environments, and useful counters and their descriptions.
Debug your web application to troubleshoot issues. Fiddler Web Debugger Tool A tool that helps you debug web applications. If you see the error “The proxy server isn’t responding”, see the following solution: Known issue with Fiddler
Chrome Developer Tools A set of web authoring and debugging tools built into Google Chrome.
Manually debugging forms How to manually debug forms.