<span style="text-decoration: underline;"><strong>Update</strong></span>
2 Aug 2015 - Added troubleshooting section
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.
- System.IdentityModel – GAC
- System.IdentityModel.Services – GAC
- SourceCode.Security.Web – C:\Program Files (x86)\K2 blackpearl\Host Server\bin\SourceCode.Security.Web.dll
- SourceCode.Security.Claims.Web – C:\Program Files (x86)\K2 blackpearl\Host Server\bin\SourceCode.Security.Claims.Web
Add a Global.asax for 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.