Configuring SmartObject REST and WCF Services

K2 SmartObject Services is not enabled by default, and must be explicitly enabled through configuration.  This allows the K2 administrator to review all configuration options available before exposing any system or custom SmartObject data to via endpoints.  Additionally, the K2 Server is responsible for publishing these services and handling the requests from these services, and as such, extremely large queries may put an undo strain on the server. Before enabling the services, administrators should determine which SmartObjects are to be exposed and how large the queries are for those SmartObjects.

The configuration options allow to control items such as:

• Whether the service is on/enabled
• Whether dynamic endpoints are generated for newly deployed SmartObjects
• The base service URI (Uniform Resource Indicator) and SSL (Secure Sockets Layer) requirement
• Which categories and SmartObjects are exposed
• The binding options

Security and Authentication

K2 SmartObject Services supports two primary authentication modes, Windows and Basic.  Basic authentication is inherently insecure over non-SSL transports. K2 SmartObject Services are configured, by default, for Windows authentication over HTTP. It is recommended to use SSL whenever configuring endpoints using Basic authentication, and disabling the SSL requirement for Basic authentication should be used for development purposes only.

K2 SmartObject Services can support running both http and https side-by-side with the proper endpoint and binding configurations.

The authentication mode being used is based on a combination of the service endpoints configured  (<smoServices>) and the authentication binding for that endpoint (<bindings>).  Additionally, when the binding is configured to allow Basic authentication, and a Basic request is sent from the client, the {defaultlabel} attribute is the K2 security label used to match the user.

The root (base)URL address is set at installation time for new installations., To set a static URL, use the following command, replacing the placeholders with the appropriate values for your environment:
netsh http add urlacl url=http://[HostName]:[Port]/

Configuring an HTTP SPN

Certain environments require the K2 Service Account to have an HTTP SPN set for the local machine where the endpoints are hosted. If 401 and 400 HTTP errors are encountered, a HTTP SPN most likely needs to be set.

Example:

User: Domain\K2ServiceAccountUser

HTTP/MachineName
HTTP/MachineName.Domain.com

Or on Cluster environments (if the cluster name is used as the endpoint URL)

HTTP/ClusterName
HTTP/ClusterName.Domain.com

K2HostServer.exe.config

The SmartObject REST and WCF services are configured by editing the <smoServices> and <system.serviceModel>  sections are configured of the K2HostServer.exe.config file located at [Installation Directory]\Host Server\Bin\ on each server where the K2 service is installed.

The following is an example of these settings using a URI of “api.denallix.com” on a sample "denallix.com" domain.

The configuration section consists of four main components:

• <smoServices> – these attributes control the default functionality of the services, including if it is enabled to run or not
• <wcf><rest> – these attributes control the bindings for the WCF and REST endpoints, including overriding the default functionality
• <managedEndpoints> – these elements and attributes control which categories and SmartObjects are exposed by the services
• <system.serviceModel> – these elements and attributes control the security binding for the endpoints
  

Services

• enableEndpoints (Boolean) – determines if the K2 SmartObject Services service is started
• true  – start K2 SmartObject Services and load the configured endpoints
• false (default/omitted) – does not start K2 SmartObject Services or load any endpoints
• enableEvents (Boolean) – determines if additions and changes to SmartObjects are reflected dynamically without restarting K2 Server
• true (default/omitted) – when SmartObjects are created/changed/deleted the service dynamically reloads the AppDomain containing the affected SmartObjects
• false – when SmartObjects are created/updated/deleted the service will not reflect the changes without restarting K2 Server
• enableCrossDomainPolicy - false (default/omitted) – disables cross-domain support disallowing browser-based applications, including Silverlight applications, to make calls to the service endpoint from a different domain. Setting this to true is currently not implemented.
• enableMetadata (Boolean) – determine if a Service Metadata Document (aka, WSDL) will be generated for the endpoint via ?wsdl
• true (default/omitted) – a Service Metadata Document is created for the endpoint
• false – a Service Metadata Document is not be created for the endpoint
• scheme (String, required) – the default scheme (http or https if SSL is enabled) for the endpoints. Default: http
• server (String, required) – the DNS or fully qualified domain name of the server hosting the endpoints. Default: {Fully Qualified Machine Name}
• port (String) – the default port for the endpoints.
• Default: 8888,
• Omitted: 80
• serviceRoot (String) – the default service root for the endpoints.
• Default: SmartObjectServices
• specialCharacterReplacement (String) – allows administrators to control what character is used in place of disallowed generated characters such as spaces.
• Default/Omitted: _(underscore character)
• defaultSecurityLabel (String) – sets the default security label to prepend to the user name for basic authentication methods.

WCF

The <wcf> section contains the default binding configuration for the WCF endpoints and optional WCF specific Service URI components.

• binding (string, required) – sets the default binding type for the WCF endpoint
• Support for basicHttpBinding, wsHttpBinding
• Default: wsHttpBinding
• bindingConfiguration (string, required) – sets the configuration in the <system.serviceModel> section which contains the binding details for the endpoint.
• Default: wsHttpBinding+Windows
• bindingConfiguration (string, required) – sets the configuration in the <system.serviceModel> section which contains the binding details for the endpoint.
• individualSmartObjects(Boolean, optional) – sets the configuration for endpoint generation to per Category or per SmartObject
  • true – generate an endpoint for each category and additional endpoints for each SmartObject in the category using the [CategoryName_SmartObjectName] format
  •  false (default/omitted) – generate an endpoint for each category with the SmartObjects contained in that endpoint
• scheme (string) – if present, overrides the default scheme and requires server
• server (string) – if present, overrides the default server and requires scheme
• port (string) – if present, overrides the default port
• serviceRoot (string) – if present, overrides the default service root
• defaultSecurityLabel (string) – if present, overrides the default security label

REST

The <rest> section contains the default binding configuration for the REST endpoints and optional REST specific Service URI components.

• binding (string, required) – sets the default binding type for the REST endpoint
• Support for webHttpBinding
• Default: webHttpBinding
• bindingConfiguration (string, required) – sets the configuration in the <system.serviceModel> section which contains the binding details for the endpoint.  
• Default: webHttpBinding+Windows
• scheme (string) – if present, overrides the default scheme and requires server
• server (string) – if present, overrides the default server and requires scheme
• port (string) – if present, overrides the default port
• serviceRoot (string) – if present, overrides the default service root
• defaultSecurityLabel (string) – if present, overrides the default security label
  
  

Managed Endpoints

The category is the default high-level object that is bound to the endpoint via the URI.  For example, if a category and SmartObject exist at the same level, the endpoint is bound to the category.  In addition to the default binding of SmartObjects methods within a category endpoint, SmartObjects can be configured to also have their own endpoints which provides direct URI navigation to the SmartObject.  In the case where a category and a SmartObject have the same endpoint, the category will supercede the SmartObject and be bound to the endpoint. An error is logged for the conflict but the category functions correctly.

Managing the endpoints allows the administrator to control which categories and SmartObjects are available via WCF and REST services. There are two main sections:

• Excluded - means the category path and the SmartObjects in that category are excluded. Each subcategory is not automatically excluded and requires a separate entry.  
• Static - means the specific category and, depending on the scenario, a specific SmartObject is included.

Excluded

Configure excluded endpoints to prevent a category or subcategory, and the SmartObject methods in that category/subcategory, from having an endpoint generated.

• all (Boolean, required) – determine if all categories will be excluded
• true (default) – exclude all categories from endpoint generation. This allows for only static endpoints to be available.
• false – generate endpoints for all categories not explicitly excluded
• <endpoints> contains an <endpoint> for each category path to explicitly exclude
• categoryPath (string, required) – the path to the category/subcategory
• Example 1: Exclude the Task Allocation category from endpoint generation. All subcategories of Task Allocation are still included unless excludeSubCategories is true.
  <endpointcategoryPath="Task Allocation"/>
• Example 2: Exclude the Workflow Reports/Workflow General subcategory from endpoint generation. The parent category, Workflow Reports, and any subcategories are still included unless excludeSubCategories is true.
  <endpointcategoryPath="Workflow Reports/Workflow General"/>
• excludeSubCategories (Boolean, optional) – the path to the category/subcategory 
• true – exclude the parent category and all subcategories from endpoint generation.
• false (default) – generate endpoints for all subcategories not explicitly excluded
• Example: Exclude the Task Allocation category and all its subcategories from endpoint generation.
  <endpointcategoryPath="Task Allocation"excludeSubCategories ="true"/>
  

Static

Static endpoints can be configured to allow the following:

• A one-to-one mapping of a SmartObject to an endpoint
• Aliasing of the SmartObject URI
• Creation of a custom AppDomain
• A different binding type
• Selection of a specific SmartObject version
  

• categoryPath (String) (required) – the path to the category/subcategory
• Example: Including all SmartObjects in a category.
  <endpointcategoryPath="MyCategory/MyProject" />

• smartobjectName (string, optional) – the name of the specific SmartObject
• Specified – when specified, the endpoint is generated for the SmartObject
• Omitted – when not specified, all SmartObjects present in the category path are included in the endpoint 

• alias (string, optional) – the new path to be used for navigating to the endpoint for this SmartObject or Category. 

• The <wcf> or <rest> section, if present, overrides the WCF and/or REST configuration for the service for this static endpoint.
• binding (string) – if present, overrides the default binding type configured for the WCF or REST service 
• Support for basicHttpBinding, wsHttpBinding, webHttpBinding
• bindingConfiguration (string) – if present, overrides the default binding configuration for the WCF/REST service
• scheme (string) – if present, overrides the default scheme and requires server
• server (string) – if present, overrides the default server and requires scheme
• port (string) – if present, overrides the default port
• serviceRoot (string) – if present, overrides the default service root
• defaultSecurityLabel (string) – if present, overrides the default security label

Service Models

The <system.serviceModel> section controls the security binding for the configured 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 service.  The REST endpoints are associated with <webHttpBinding>bindings while WCF endpoints are associated with either <wsHttpBinding> or <basicHttpBinding> bindings.  For example, the default bindingConfiguration for the WCF service endpoints is wsHttpBinding+Windows found in the <bindings><wsHttpBinding><bindingname="wsHttpBinding+Windows"> section.

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

The <securitymode=""> element/attribute defines whether or not SSL is supported.  Although None allows K2 to manage the binding requirements this is not the case with WCF.  Unfortunately, WCF does not allow both SSL (HTTPS) and non-SSL (HTTP) support on the same endpoint.  Therefore, SmartObject Services must have multiple endpoints and mappings to multiple bindings to support both SSL (HTTPS) and non-SSL (HTTPS) for the same service.  Examples for all the supported binding configurations have been provided in the <system.serviceModel> section.

K2 recommends setting <securitymode="Message"> (WCF) or <securitymode="TransportCredentialOnly"> (REST) for standard non-SSL (HTTP) support and <securitymode="TransportWithMessageCredential" >(WCF) or <securitymode="Transport" >(REST) 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.  K2 recommends setting <transportclientCredentialType="Windows"/> when Windows credentials are available.  The setting of <transportclientCredentialType="Windows"/> should be used to enable support for Basic.  Remember that when bindings are enabled, an associated service endpoint must also be enabled.

Example

The following example shows the usage of all Service and Managed Endpoint configuration options.  The K2 SmartObject Services start when K2 Server starts and load endpoints at the http://api.denallix.com:8888/SmartObjectServices base URI. Other facts about this configuration include:

• Basic authentication via HTTP for WCF mapped to the K2SQL security label and Windows authentication via HTTPS for REST. 
• Cross Domain Policies are not supported. 
• When SmartObjects are created, updated or deleted their endpoints will be reloaded and generated using a “_” for special characters. 
• All categories and their SmartObjects are loaded except for those found at Task Allocation or Workflow Reports/Workflow General. 
• Finally, a static endpoint supporting Basic authentication for REST using the K2SQL security label is generated in a separate application domain for the K2 Examples/Employee at the aliased URI http://api.denallix.com:8889/SmartObjects/MySmartObjectAlias