5 May 2017: I’ve updated this post for 4.6.10 and above here.
Be it on smartforms or your custom ASP.NET forms, the OpenWorklistItem call will return the following error if the current User did not pass the validation rule on K2 Server:
For the K2 Designer and Admins, it’s a simple fact that the User is not the Destination User of this Activity. To the Users of this System, they will be like “What the heck are you trying to say?!?”. So how can we help the Users to better understand what is going on without calling us every time a cryptic message appears?
Find these cryptic out-of-box messages
These messages are stored as a template in [K2 blackpearl folder]\Host Server\bin\HostServerLogging.config.
In this file, you will find all the message templates used by K2. The first three numbers of the MsgID represents a logical section. So for example, MsgID starting with 244 are relating to security.
Of course, you can just modify this file directly, restart your K2 blackpearl Server services and all messages will be friendlier. But what happens on upgrade? Well, there’s a high chance that it will be replaced by the default copy in the installer, so it will be a hassle to make comparisons and update the entire list every time you upgrade. My take? Don’t touch this file unless you are willing to do all the additional work.
Friendly message via ASP.NET
Once you know the message you are looking out for, the rest will be using your try-catch block to capture the error thrown and look out for the MsgID in your error message body.
// do something else
Console.Writeline("Sorry, you do not have the rights to work on this task.");
Console.Writeline("Sorry, an error had occurred. Please contact the System Administrator and provide the following message:<br/>"+ex.Message);
Friendly message via K2 smartforms
In smartforms, you will need to make use of the Error Handling condition – Error Occurred and read the message via the System Values > Error node.
Open your Rule Configuration Wizard.
Add the Error Occurred condition. This will be executed when an error occurs in this Rule.
Add the An advanced condition is true condition. This condition should be with Error Occurred to create a AND condition like the following:
Click on an advance condition link, followed by the Add button to add a new row.
From the Context Browser, expand System Values > Error. Drag the Error Message node and drop it to the Left column text box. Select Contains for the Operator and fill in the MsgID code you are looking for in the Right column text box. Click OK to save and close the dialog.
Add your friendly message and any other rules(e.g. disable form, navigate to another form etc).
There are times when you need to provided a dedicated login page to your K2 smartforms Forms or even embed the K2 smartforms Form into your custom ASP.NET website (iFrame). The main issue with these approaches is that K2 smartforms uses Claims Authentication with its K2 Windows STS and thus your users may need to log into your custom ASP.NET website, then log into K2 again, which is not a pretty solution.
This article will show you how to configure your ASP.NET website to authenticate against K2 Windows STS for a seamless login experience.
Note: This procedure is for integration with K2 Windows STS Issuer only. To integrate with K2 Forms STS requires additional work, which will be discussed in a future post.
Add Site Realm and Audience information to K2
Log into K2 Designer and navigate to the Manage Site Realms Form. (All Items > System > Management > Security > Forms > Manage Site Realms)
Run the Form.
Click on the New button under the Realms section.
Fill in the URI, Reply URI and select K2 Windows STS for Linked Issuers. Click OK.
URI: This is the IIS website URL for your ASP.NET Web Application. If it is a sub-site, e.g. K2/CustomSite, then you will need to include the full URL path e.g. http://k2blackpearl.somewhere.com/CustomSite/
Reply URI: This is the URL that will be called by K2 Issuer. If your site is the root IIS website, then pass in a “/”. If it’s a sub-site, e.g. K2/CustomSite, pass in the sub-site path will do. e.g. “/CustomSite/“.
Home Realm: No idea yet. This is something I’ll need to find out more.
Linked Issuers: We are authenticating with K2 Windows STS, so obvious choice to choose (=
IMPORTANT: For both URI and Reply URI, the trailing forward-slash (/) is very important. In earlier versions of K2 blackpearl, the slash is assumed to be always present and thus will throw a “Index and length must refer to a location within the string.” error.
Leave the K2 Designer open for now.
IIS Website Application Pool
Make sure your website’s Application Pool is running .NET Framework v4.0 and Managed Pipeline Mode = Integrated.
Visual Studio Web Application Configuration
Update Web Application’s Web.Config
Download and copy WindowsSTS_web.config to your website’s web.config file. Run through the following sub sections to update the config file.
Update WindowsSTS Thumbprint value
Go back to K2 Designer, navigate to and run the Manager Issuers Form. (All Items > System > Management > Security > Forms > Manage Issuers).
On the Form, copy the Thumbprint value for K2 WindowsSTS record. The Use For Login value should be True here, since we are going to authenticate with it.
Open the web.config file updated earlier and change the thumbprint attribute value on the path configuration / system.identityModel / issuerNameRegistry / authorithy / keys / add.
Save the web.config file. Leave the K2 Designer open. You will need to make use of this form again in the next section.
Update Federation Configuration
In the web.config file, go to the section configuration / system.identityModel.services / federationConfiguration.
If your K2 smartforms is configured for HTTPS protocol, you will need to update the requireSsl and requireHttps attributes to true.
Next, you will need to update the issuer, realm and reply attribute values and save the web.config file.
issuer: This is your K2 WindowsSTS issuer URL. Go back to your K2 Designer Manager Issuer Form that was opened earlier to copy the URL.
realm: This is the website URL used when you add the Realm to K2 in the earlier part of this article. In my example, my URL will be http://K2WindowsSTSLogin.domain.com/.
reply: This is the reply uri added earlier in this exercise. Important thing to note here is that the full URL is required. So meaning if it not replying to a sub-site, then the URL will be http://K2WindowsSTSLogin.domain.com/. If it is replying to the sub-site named “/site1”, then the URL will be http://K2WindowsSTSLogin.domain.com/site1/.
It is important that the trailing forward slash (/) is included for both the realm and reply attribute values. If not, you will get the error “Index and length must refer to a location within the string.” when your run the authentication later.
There should not be a trailing forward slash (/) for the issuer attribute value.
Since the authentication will be looking up the issuer, realm and reply URL, make sure that the web server machine is able to resolve the domain name or NetBios name.
Adding assembly references to your website
You will need to add the following assemble references to your website.
Download and copy the file content (Global.asax) to your global.asax.cs. This file contains the codes to manage Federation Authentication issues. It is not the perfect set, but solves most of my issues.
Add something to test
Now, to test that the Claims Authentication works and the federation token is recognized by K2, we need a test page.
In our test, let’s create a default.aspx WebForm and add a response.redirect method in the Page_Load method to go to your K2 Designer URL.
Grand Finale – Testing Claims Auth with K2 Windows STS
Now, to run the test, publish your Web Application to IIS, open your web browser and navigate to your custom website. When the site loads, you will notice that it is redirected to your K2 WindowsSTS for authentication.
Go ahead to fill in the user name and password to login. You will notice that the authentication will be successfully and redirected to your reply uri. Your default.aspx page will be loaded and redirect to your K2 Designer site. There is no additional login at your K2 Designer site and it loads your credentials correctly!
No connection could be made because target machine actively refuse it 127.0.0.1:5555
This error will occur when you have a distributed setup – blackpearl and smartforms server on different boxes.
To resolve this, make sure you have the HostName key in your ASP.NET web.config’s appSettings section. This key’s value should be your K2 blackpearl server/cluster’s FQDN.
Carry out an IIS reset and everything should work now.