K2 smartforms and SharePoint Single Sign On

So you have K2 smartforms and your SharePoint site installed on different servers and SharePoint is configured for Forms Based Authentication (FBA)? Then you probably hit the double login issue like below:

Sharepoint FBA and K2 smartforms login

Or if you use Windows Authentication without Kerberos configured you probably get a second Windows login challenge, once your logged in to SharePoint, like this:

Windows login challenge for smartforms runtime site

To overcome these double login issues you’ll have to introduce some kind of Single Sign On solution so that user’s don’t need to login to the K2 smartforms runtime site just for loading these forms within SharePoint.

In this post I will describe how you’ll need to setup your SharePoint and K2 smartforms environment in combination with a custom SharePoint login form. The custom SharePoint login form can be used by both ASP.net Membership Provider users and Windows Domain users.

Before you can use the ASP.Net Membership provider with the K2 platform you’ll need to develop a custom security provider for K2. There’s already an implementation which you can download on the K2 Underground site, so I’ll skip this step in this post: K2 Custom Security Provider for ASP.Net Membership. I implemented this solution and supplied the following security label: ASP. Make sure you can use the custom security provider in K2, for instance you can try to add a user for the security label ASP to a role, if you can find the ASP.net membership users it will work:

ASP.net membership user in K2 role

Note: I’m using the ASP.Net membership provider in this solution. But you can of course use any custom security provider as long as you develop a custom security provider for K2 and SharePoint. I used the ASP.Net membership provider since SharePoint already supports this out of the box and there are a lot of examples on the internet how to set this up with SharePoint.

1. K2 smartforms runtime site for FBA

If you don’t already have created a separate K2 smartforms runtime site configured for FBA then this is the first thing you’ll need to do.

1. Create a copy of the default runtime site

Copy C:\Program Files (x86)\K2 blackpearl\K2 SmartForms Runtime to C:\Program Files (x86)\K2 blackpearl\K2 SmartForms Runtime FBA

K2 smartforms runtime folder duplication

2. Add an IIS application to the K2 web site

In IIS Manager add an application to the K2 web site:

IIS manager add application

Supply the following details and click OK:

Alias: RuntimeFBA
Physical path: C:\Program Files (x86)\K2 blackpearl\K2 SmartForms Runtime FBA

IIS manager add application dialog

3. Add K2 web site binding smartforms.denallix.com

To have the single sign on working you’ll need a FQDN for your FBA runtime site on the same root domain as your SharePoint site, in this case the root domain is: .denallix.com.

Select the K2 web site and click Bindings… in the Actions pane:

IIS manager edit bindings

Add a new site binding for host name smartforms.denallix.com:

Add site binding for smartforms.denallix.com

Don’t forget to update your DNS of course.

4. Edit the web.config of the FBA site and enable Forms authentication

Open the web.config in C:\Program Files (x86)\K2 blackpearl\K2 SmartForms Runtime FBA and change the authentication from Windows to Forms and set the following attributes and save the file:

mode: Forms
name: smartforms (this will be the cookie name)
domain: .denallix.com (this must be the root domain)

smartforms forms authentication section

5. Test the smartforms FBA runtime site

Open http://smartforms.denallix.com/RuntimeFBA and you should be redirected to the login page:

smartforms forms login page

You can login with any security label you like, in this case I used the default Windows authentication that has the K2 security label. Custom security providers are also supported, I will cover this in a future blog post.

After successful login you’ll be redirected to the ReturnUrl, in this case the homepage of the FBA runtime site:

smartforms home page

2. Install the K2 Underground SharePoint Authentication solution

As previously mentioned I use the ASP.Net membership provider. I expect you already have a SharePoint site setup which you want to use with K2 smartforms configured with Forms Based Authentication and the ASP.Net membership provider. If you didn’t, here’s a good blog post on how to do this: Step-by-step Forms-Based Authentication (FBA) on SharePoint 2010.

1. Download the K2 Underground SharePoint Authentication solution ,  K2 Community SharePoint Authentication solution

2. Extract the .zip file to a convenient location on your SharePoint server

Extracted K2 Underground SharePoint Authentication solution

3. Install the SharePoint solution to your farm

Open the SharePoint 2010 Management shell and execute the following commands:

Add-SPSolution -LiteralPath C:\Downloads\K2Underground.SharePoint.Authentication.wsp
Install-SPSolution -Identity k2underground.sharepoint.authentication.wsp -GACDeployment

Add and install SharePoint solution

4. Activate feature at web application

The K2 Underground SharePoint Authentication solution will install a SharePoint feature scoped to Web Application level. Open SharePoint Central Administration and  go to Application Management, select the web application to configure and click on Manage Features:

SharePoint application management

Scroll to the K2 Underground SharePoint Authentication feature and click on Activate:

K2 Underground SharePoint Authentication Feature

By activating the feature it will copy the template Login.aspx from C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\IDENTITYMODEL\FORMS\K2Underground to the correct IIS Virtual Directory of the web application:

Custom login form deployment location

Note: on the internet you’ll find tons of blog posts on how to create a custom login form for SharePoint and deploy it somewhere to the _layouts folder. Although this seems to work fine it breaks the Protocol Discovery Requests functionality. K2 adds the HTTP header “X-FORMS_BASED_AUTH_ACCEPTED: f” to all it’s request to SharePoint so that SharePoint knows that it should skip the forms authentication and use Windows authentication instead. Maybe you won’t notice it directly, but K2 uses this in all the SharePoint connectivity (SharePoint events in the workflow, searching for SharePoint users when using K2 Workspace etc.). You’ll notice if you use a custom login form that’s deployed in the _layouts folder, K2 processes that use the SharePoint site will fail and errors are logged in the Windows event log with the message: Object moved to here and in the details the url of your login page.

5. Set the custom sign in page

Open SharePoint Central Administration and  go to Application Management, select the web application to configure and click on Authentication Providers:

Sharepoint authentication providers

Scroll to the Sing In Page URL section, select Custom Sign In Page and add the following and click on Save (saving will take some time, be patient):

~/_forms/K2Underground/Login.aspx

Custom sign in page

3. Edit the web.config files

To make things work the web.config files from both the K2 smartforms FBA runtime site and the SharePoint site must be edited.

1. Add the <machineKey> node to the web.config of the smartforms FBA runtime site

To make both web applications understand each others encrypted cookies the <machineKey> node needs to be the same. By default the copied K2 FBA runtime site doesn’t have a <machineKey> node, so generate one here: <machineKey> Generator. Of course for production environments you don’t want to use an online tool for this, use the Windows port of OpenSSL instead to generate the key pair: OpenSSL for Windows.

Add the generated <machineKey> node just below the <system.web> node

Add machinekey node

Now that you have the web.config of the K2 FBA runtime site open, scroll to the TripleDES comment in the <appSettings> section and copy these three lines (I deleted my values out of security considerations):

Triple DES section

2. Edit the web.config of the SharePoint web application

Locate the <machineKey section and replace it with your custom generated key pair:

Machinekey section web.config SharePoint

Navigate to the <appSettings> section, if it doesn’t exist create it, and add the Triple DES section you copied earlier from the K2 smartforms FBA runtime web.config:

Triple DES section SharePoint web.config

Also add the following keys to the <appSettings> section, just below the Triple DES section:

<add key="cookieNameSmartFormsWebApp" value="smartforms.denallix.com" />
<add key="K2SecurityLabelAsp" value="ASP" />
<add key="K2SecurityLabelWindows" value="K2" />
<add key="timeOutInMinutes" value="30" />
<add key="WindowsDomain" value="DENALLIX" />

Change these settings according to your values. The purpose of each property is:

cookieNameSmartFormsWebApp – the name of the cookie that shows in the browser
timeOutInMinutes – the default time-out for the cookie
K2SecurityLabelAsp – the K2 security label for Asp.Net authentication
K2SecurityLabelWindows – the K2 security label for Windows authentication
WindowsDomain – the Windows domain name

K2 SharePoint authentication settings web.config

Search for the <forms section and make sure you set the domain to your root domain, in this example: .denallix.com. This is very important! By setting the domain to the root domain the browser will send all cookies to every application that has this root domain in the url. So the smartforms.denallix.com web site will accept a cookie with the domain set to .denallix.com. Because the web.config of the SharePoint site and the smartforms FBA runtime site have the same <machineKey> the smartforms FBA runtime can now decrypt the cookie, retrieve the K2 authentication token and log the user in automatically.

<forms> node SharePoint web.config

Save the web.config file.

3. Disable the SharePoint Health Analysis Rule timer job

SharePoint manages the <machineKey> of every front-end web server with the Health Analysis rule timer job. Unfortunately the <machineKey> section comes from the SharePoint Config database, which means the custom <machineKey> section gets overwritten every night. In the morning you’ll find out: users are complaining that they see a smartforms login page inside of SharePoint (see first screenshot in this blog post). To prevent the <machineKey> section from changing every night to the default you should disable the SharePoint Health Analysis Rule with the following command in PowerShell:

Get-SPHealthAnalysisRule ViewStateKeysAreOutOfSync | Disable-SPHealthAnalysisRule

More details: SharePoint 2010 Health Analyser Timer Job Changed Custom Web.Config Machine Key

4. Test your login page

Open the SharePoint site, the login form on location /_forms/K2Underground/Login.aspx should be loaded.

To log in with an Asp.Net membership user just supply the username and password:

Login form Asp.Net membership user

For demo purposes I added a Page Viewer web part (which is basically an iframe) that loads a form from the smartforms runtime FBA site and shows the logged in user details. This demonstrates that the form is aware of the correct user. Compare the details to the SharePoint menu with the user name in the upper right corner. The Asp.Net membership user is logged in to SharePoint and also in to K2 smartforms:

Logged in Asp.Net membership user details

To log in with an Active Directory user supply the DOMAIN\username and password:

Login form Windows Active Directory user

The login form will detect the specified DOMAIN name, creates the authentication cookie for the K2 smartforms runtime FBA site and redirects the user to the Windows authentication page of SharePoint: /_windows/default.aspx. If Kerberos is configured correctly the user is logged in; if not a Windows login challenge is shown (screenshot 2 in this post). To prevent the Windows login challenge make sure Kerberos works correct for the SharePoint web site. In the screenshot below you can see that the details of the logged in Windows user are shown.

Logged in Active Directory user details

5. Some extra web.config configurations for the K2 smartforms runtime FBA site

1. Disable output cache profile

Because you don’t want to mix up user session you should disable the output cache profile. If you don’t do this the following will occur:

User 1 opens the home page with the user details form. The form is cached. Within 30 seconds the same form is retrieved by User 2 who also opens the home page. User 2 will now see the cached form, meaning the user details of User 1.

Disable smartforms output cache profile

2. Change the loginUrl to the SharePoint login form

Since we have the SharePoint login form to generate the authentication cookies for the K2 smartforms runtime FBA site it is a good idea to change the default loginUrl to the FQN of the SharePoint login form. If a user opens a task and isn’t authenticated he will be redirected to the SharePoint login form.

smartforms forms authentication section updated

Conclusion

Because both SharePoint and K2 smartforms are built on Windows IIS and the Asp.Net framework we can leverage these frameworks to create a Single Sign On solution. You can even take this one step further and have a custom Asp.Net web site that serves as a Single Sign On website to which you redirect both the SharePoint and K2 smartforms site. Than it’s possible to have one single url for all login purposes, for instance: http://login.denallix.com.

You can download the SharePoint solution package from the K2 Underground:

http://www.k2underground.com/groups/sharepoint_fba_for_k2_smartforms/default.aspx

K2 Community website: K2 Community SharePoint Authentication solution

If you want to read the source code or use it in your own solution, this is available to on the same project site.

You can leave questions, comments or start a discussion in the comments sections below.