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:
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.
The process interface gives you the ability to manage processes. It allows Starting processes, Read and Update Process Datafield and Process XmlFields.
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 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.
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.
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.
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:
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.
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.
attribute/element defines if SSL is used or not.
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”:
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!
With web sites, it always seems easy to increase security. Simply put it on SSL. As you could already read, the
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.
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.
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.
And hit Execute!
Other blog posts
This is just a brief introduction, that’s primarily focused into getting you introduced to the K2 Services. I do have some other posts planned that actually help you get results from these services. So, I hope to see you soon. If there’s any specific things you’d like to see, leave a comment and maybe I can work on that specifically!