Service Settings

Basic Authentication

The <sourceCode.services><basicAuthentication> tag contains the attributes that configure the Basic authentication used by K2 Services.

• requireSSL (Boolean) – the HTTPS requirement is configured by default at the binding level.  This setting can be used to override the SSL requirement of the HTTP binding configurations.
• True (default): will cause an error if SSL is not enabled on the hosting web site
• False: will cause an error if SSL is enabled on the hosting web site
• enabled (Boolean) – determines if K2 Services endpoints are enabled 
• True (default): will enable K2 Services endpoints
•  False: will disable K2 Services endpoints 
• realm (String) – sets the Basic realm to apply to incoming users
• {ServerName} (default): K2 services will utilize the server name if this value is not provided
• cachingEnabled (Boolean) – determines if K2 Services will use caching for batch operations
• True (default): will enable K2 Services endpoint caching 
•  False: will disable K2 Services endpoint caching
• cachingDuration (Integer) – determines duration (in minutes) to cache batch results
•  15 (default): will cache batch results for 15 minutes
• defaultSecurityLabel (String) – sets the default security label to apply to incoming user names
•  K2 (default): will apply “K2” as the security label for user names

Inclusions

The <sourceCode.services><inclusions> tag contains the default settings for inclusions in data returned K2 Services.

• userExtendedProperties (Boolean) – determines if K2 Services will return all user details
•  False (default): will not return extended properties for users
• hiddenFields (Boolean) – determines if K2 Services will return hidden fields
• False (default): will not return hidden fields
• maxWorklistItems (Integer) – determines the maximum worklist items K2 Services will return
• 0 (default): will return all worklist items
•  processDataFields (Boolean) – determines if K2 Services will return process data fields
•  False (default): will not return process data fields.  Use Query Options to override the default behavior.
• processXmlFields (Boolean) – determines if K2 Services will return process XML fields
• False (default): will not return process XML fields.  Use Query Options to override the default behavior.
• activityDataFields (Boolean) – determines if K2 Services will return activity data fields
•  False (default): will not return activity data fields.  Use Query Options to override the default behavior.
• activityXmlFields (Boolean) – determines if K2 Services will return activity XML fields
•  False (default): will not return activity XML fields.  Use Query Options to override the default behavior.
• <include> – optional granular control on the categories of data and XML fields K2 Servies will return.  K2 Services will return all categories if none are explicitly found (default). 
• category (String) – determines if K2 Services will return specific categories of data and XML fields
• None (special keyword): will not return any categories for data or XML field

Service Endpoints and Bindings

The <services><service> section contains the default configuration for the endpoints provided by K2 Services.  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. 

Each endpoint defines an associated <binding> via the bindingConfiguration attribute.  This allows each endpoint to support a different security binding allowing for the mixing of authentication and SSL requirements for the same virtual directory.  The REST endpoints are associated with <webHttpBinding> bindings while WCF/SOAP endpoints are associated with <basicHttpBinding> bindings.  For example, the default bindingConfiguration for the Task service at SyncREST.svc endpoint is SourceCode.Services.SyncRestBinding+HTTPS found in the <bindings><webHttpBinding><bindingname="SourceCode.Services.SyncRestBinding+HTTPS"> section.

The <bindings> section contains the configuration details for each binding.  The two main configuration elements related to K2 Services bindings are <security> and <transport>.

The <securitymode=""> element/attribute defines whether or not SSL is supported.  Although None *should* allow IIS to manage the binding requirements this is not the case with WCF.  Unfortunately, WCF will not allow both SSL (HTTPS) and non-SSL (HTTP) support on the same endpoint.  Therefore, K2 Services must have multiple endpoints and mappings to multiple bindings to support both SSL (HTTPS) and non-SSL (HTTPS) for the same service.  Example configurations for these have been provided in comments in the web.config and the product documentation.

K2 recommends setting <securitymode="TransportCredentialOnly"> for standard non-SSL (HTTP) support and <securitymode="Transport"> to enable SSL (HTTPS) support.  Remember that when bindings are enabled, an associated service endpoint must also be enabled.

The <transportclientCredentialType=""/> element/attribute defines what credential types will be supported by client requests headers.  <transportclientCredentialType="None"/> allows for the greatest flexibility by allowing the client application to provide the appropriate supported header – Basic, Windows (NTLM or Negotiate) or NTLM.  Changing this value to Windows or NTLM will force the endpoint to require a Windows-based request thus disabling Basic authentication.

K2 recommends setting <transportclientCredentialType="None"/> to enable support for Basic and Windows (NTLM or Negotiate) depending on the client request header.  Remember that when bindings are enabled, an associated service endpoint must also be enabled.

Below is an example web.config file with the default security configuration for the service endpoints bindings. Update these sections to change the endpoints and bindings. 

Multiple Service Hosting

It is possible to host multiple services which include both non-SSL and SSL services.  To add the SSL service a few manual steps are required post installation.  Take the following into consideration:

Microsoft Framework .NET 3.5 does not support multiple bindings in IIS without configuring a single address and setting up a prefix filter as per the following MSDN KB (Refer to section ‘Multiple IIS Binding Support in .NET Framework 3.5’): http://msdn.microsoft.com/en-us/library/aa751841.aspx
Some of the following errors may occur when bindings are incorrectly configured:
• Could not find a base address that matches scheme http for the endpoint with binding WebHttpBinding. Registered base address schemes are [].
• No protocol binding matches the given address 'http://api.denallix.com:85/K2Services/REST.svc/Worklist/Items'. Protocol bindings are configured at the Site level in IIS or WAS configuration.
• The resource cannot be found.
• This collection already contains an address with scheme http. There can be at most one address per scheme in this collection. Parameter name: item

The K2 installation will not configure entries. To configure K2 Services to support a web site with multiple bindings add a prefix entry for the binding you wish to support in the section of the K2 Services web.config found at [Installation Directory]\WebServices\K2Services\web.config.

The HTTPS port needs to be set manually to 443 in the web.config as well.
Example of supporting the http://api.denallix.com:81 binding on an IIS site with multiple bindings:

Note that the HTTPS section in the web.config file is commented out by default.  The following section therefore needs to be enabled. Note that the first two lines are headings only and should stay commented out.  The highlighted section below needs to be enabled: