K2 Services - Part 2

April 08, 2011

7 Mins. Read.

This blogpost is outdated. Please see K2 SmartObject Services – Configuration update static endpoint if you have any problems with the K2HostServer.config file changes.

Back when 1230 came out, I wrote a pretty long blogpost about the K2 SmartObject Services and (what was the beginning of) K2 Services. K2 Services is the Web Service that exposes a number of interfaces. K2 SmartObject Services is the K2 Server hosted WCF endpoint which allows SmartObject functionality. This post focuses only on K2 Services. The only change to the K2 SmartObject Services that 1290 brought was CRUDE (E for Execute) functionality to the RESTful part of K2 SmartObject Services. I’ll do another post on that new functionality.

This post is a follow up, since the K2 Services has more features in the 1290 release. The service now offers the following endpoints:

SyncREST.svc
SyncWCF.svc
REST.svc
WCF.svc
WS.asmx

The WCF.svc and WS.asmx have already been covered in the 1230 post. They have changed, but not much, you can read about it in this KB1227 article.

The new sync services are designed with batch processing in mind. This also includes batch-actioning of worklist items so you can do things offline and have your app sync at a later stage. Sync simply stands for synchronization, something you can do with batch processing more easily.

What does it expose?

The web.config will define which .SVC provides what interface. The default configuration provides Task, Identity and Core services at the SyncREST.svc and SyncWCF.svc endpoints along with Worklist, Process, Identity and Core services at the REST.svc and WCF.svc endpoints.

Process

The process interface gives you the ability to manage processes. It allows Starting processes, Read and Update Process Datafield and Process XmlFields.

Identity

The Identity interface is used to get user information from the K2 system. As you might know, K2 can support a different user back-end then AD. You could use a simple database so applications that use Forms Based authentication can seamlessly use those same users (as an example). The Identity interface provides access to that user base. You can use this to build redirect and delegate functionality within your client application.

Worklist

Worklist is used to get everything from a WorklistItem. It gives access to the Worklist, the items in it, the process data which belongs to those items and other information surrounding that WorklistItem. Everything you do with the WorklistItem object in the K2 API, you can do with this Worklist.

Task

For synchronization or batch processing of items, there’s the Task interface. It provides roughly the same functionality as Worklist, but using less output, which is more lightweight and easier to use for mobile clients. Task also provides the ability to do batch updating/actioning of WorklistItems.

Core

And last, Core. This only has a WhoAmI method which can be used to get the client’s credentials. This interface does NOT use the K2 API’s or the K2 backend. Although the interface is nearly empty, it does contain schema information for the success and error messages.

Getting started

When you’ve installed the 1290 release, you’ll want to test the K2 Services. The first thing I did was browse to the REST.svc. A quick test you can do is going to http://[k2workspacehostname]/K2Services/REST.svc/Identity/Users. Which results (on my machine) to this:

Identity/Users — Identity interface, users method, XML output (default).

For the REST.svc and SyncREST.svc both should work like the screenshot. The WCF.svc and SyncWCF.svc will provide a nice metadata page.

Configuration

When you’ve installed the KB1290 upgrade, you’ll have a web.config which works pretty well – a bit too well actually. That’s why KB1240 was published. There is a small bug in the configuration that you get out of the box. The whitepaper that’s associated with KB1240 explains it. The whitepaper really is a must-read when you’re new to the K2 Services web.config file.

Although you should read the whitepaper, the article explains that:

A service has endpoints, which are the interfaces mentioned above. The interface is defined in the contract attribute of the endpoint element.
Every endpoint defines an associated via the bindingConfiguration, so every endpoint has a corresponding bindingConfiguration.
The REST endpoints use webHttpBinding, the WCF/SOAP use basicHttpBinding.
The bindingConfiguration defines which security mode and which transport is used.
The attribute/element defines if SSL is used or not.
The attribute/element defines what credential types will be supported (Basic, Windows (NTLM or Kerberos) or Ntlm).

Basic Authentication – Requires SSL and development

Because the sync services are primarily designed for mobile/remote work, the clients may not be able to use integrated authentication. This forces you into basic authentication which is unsafe because the username and password are easy to decode from the wire.

If integrated authentication fails, it simply jumps to basic authentication. That’s also the reason why you don’t have to configure IIS to use basic authentication. K2 does it for you. By default, K2 requires SSL when you’re doing basic authentication (for security reasons). If you do try to use basic authentication on the K2 services without using SSL, you’ll get a 403 header returned and a page with message “This type of page is not served”:

Error when trying to get to SSL site without it being allowed — Error, when SSL is required.

If you look at the source of this page, right at the bottom there’s actually a nice message (in html comment):

[HttpException]: SSL required for Basic Authentication
at SourceCode.Services.Authentication.BasicAuthenticationModule.context_AuthenticateRequest(Object sender, EventArgs e)
at System.Web.HttpApplication.SyncEventExecutionStep.System.Web.HttpApplication.IExecutionStep.Execute()
at System.Web.HttpApplication.ExecuteStep(IExecutionStep step, Boolean& completedSynchronously)

This is a good default, as you don’t want people to access your resources unsecured, but for development, you don’t really want to install a SSL certificate and all.
You can change the requiredSSL attribute in the basicAutentication node in the web.config from:

<basicAuthentication requireSSL="True" enabled="true" cachingEnabled="True" cachingDuration="15" defaultSecurityLabel="K2" />

To something like:

<basicAuthentication requireSSL="False" enabled="true" cachingEnabled="True" cachingDuration="15" defaultSecurityLabel="K2" />

You also have to change the bindingConfiguration for the endpoint you want to reach via basic authentication without SSL to something like this:

<binding name="SourceCode.Services.SyncRestBinding+HTTP">
	<security mode="TransportCredentialOnly">
		<transport clientCredentialType="None" />
	</security>
</binding>

Also make sure you’re service endpoints are configured to use the correct bindingConfiguration, for example:

<endpoint address="Task" behaviorConfiguration="SourceCode.Services.RestBehavior" binding="webHttpBinding" bindingConfiguration="SourceCode.Services.SyncRestBinding+HTTP" contract="SourceCode.Services.ServiceContracts.ITaskService" />

Note the bindingConfiguration=”SourceCode.Services.SyncRestBinding+HTTP” !

This is NOT A RECOMMENDED setting for production. It is very unsafe and you should only ever use it on your development environment!

Configure SSL

With web sites, it always seems easy to increase security. Simply put it on SSL. As you could already read, the also defines how the WCF service should behave. Setting it to “None” should allow IIS to manage if it uses SSL or not. But that does not work with WCF, because SSL and WCF requires a configuration change. The documentation explain what you need to do to get SSL working and what to change in you web.config. The whitepaper mentioned earlier is also a very good resource.

What’s next?

Read the articles mentioned. I know this is not really what you want to hear, but they really do help a lot in getting the configuration right.

Fiddler

When you do start working or testing things, it’s good to use Fiddler2 . I didn’t know at first, but this thing has a very nice query builder/tester. So fiddler can send the request and you can analyze the result. This makes it very easy when trying out the methods where you have to do a POST with some XML content.

Integrated authentication

Don’t forget to enable this checkbox when you’re doing integrated authentication:

Here’s ow the request tab looks:

And, if everything is correct, result. Select the proper request:

Basic authentication

Basic auth with Fiddler can also be done. I suggest you do one basic request using your normal browser and then copy/paste the request headers in Fiddler. With my MSIE, I couldn’t get it to do basic authentication because MSIE tries to be secure and jumps to NTLM – which is good, but not what I wanted. So, download Firefox or some other browser.

FireFox is able to do hook up to fiddler with the FiddlerHook. Make sure you install Firefox and then (re)install Fiddler and it works. Then look at the right hand-corner of firefox and click on it:

Selec “Use Fiddler automatically” and then simply browse to one of the URL’s of the REST service. Fiddler picks up the request and you’ll see the Authorization header in the Inspector tab:

Copy and paste that header into the request builder’s request headers:

And hit Execute!