Skip to main content
Kinetic Community

Getting Started with KSL

The Kinetic Security Language (KSL) is a strategy for defining and managing access control.  At a high level, KSL uses the same technology as the task handler parameters and connectors in order to determine whether a request should be allowed or denied.  Kinetic Task 3.0 leverages KSL to restrict API access, however usage of KSL will grow to be used in many other areas in both Kinetic Task and other Kinetic products.

Background

Many resources in an application need to have access restricted: administration consoles, management consoles, API access, viewing a record, etc, and it is rare that any two companies want to secure these resources in the same way.  Therefore, it was important to find a strategy that could be applied to many differing resources and flexible enough to be able to implement the varying security logic.  Using access control lists (IE defining users and groups and/or roles) is a common technique for restricting access, however we knew it would be extremely undesirable to manage users and groups in yet another place.  Additionally, there are many security rules that access control lists have problems with, such as restricting access to everyone "not in group X" or restricting access based on time.  KSL is a access control strategy which attempts to address these issues.

As of Kinetic Task 3.0, "API Access" is the only resource that KSL can be applied to.  The Kinetic Task API is used by source roots to trigger the execution of a task tree, or to complete a deferred task (for more information about the Kinetic Task API, see the API Reference guide in the Kinetic Task Developer Guides section).  In many environments, which leverage firewalls or other network level security, it may not be necessary to add additional security to restrict the creation of Kinetic Task trigger.  If this type of network perimeter level security does not satisfy the desired security policy, KSL can be used to further restrict how trigger records are created.

KSL was designed to be used for much more than Kinetic Task API Access.  We are working to incorporate KSL in other areas of Kinetic Task as well as in our other products.  Other areas that you are likely to see KSL in the future include restricting access to console functionality, Kinetic Request service items, and Kinetic Calendar private calendars.  KSL has incredible flexibility, is can leverage Active Directory, Remedy, or just about anything else to help determine if a request shoudl be allowed access.

Getting Started

For the purpose of this guide, we will look at adding two "API Access" security policies to a ficticious "Sample" source root.  One policy will restrict access to requests coming from a list of IP addresses, and the other policy will restrict access to requests that include a special pre-shared security token.

Before we begin, lets create the "Sample" source root that we will be applying KSL policies to.  Source Roots are defined on the Source Roots tab of the Source Configuration Console, which requires Kinetic Task Administrator privlidges.  The console can be accessed directly using the URL http://TASK_SERVER:PORT/kineticTask/SourceConfigurationConsole, or by clicking on the Sources link from any of the other Kinetic Task consoles.

Source Configuration Console - Source Roots Tab (Empty).png

From here, we can can add a new Standard Source by clicking on the Add Standard Source button.  The only configuration we will do at this point is to set the name (to "Sample").

Source Configuration Console - Source Roots Tab (Add Sample Source Root).png

After clicking on the Save button, we will now see the "Sample" source root listed in the Standard Source Roots table.

Source Configuration Console - Source Roots Tab (With Sample Source Root).png

There are three steps to leveraging the power and flexibility of KSL:

  • Define one or more Policies
  • Apply Policies to a Resource
  • Access the Resource

Define one or more Policies

The first step in leveraging KSL is to define a set of policies.  Policies are defined on the Policy Rules tab of the Source Configuration Console.

Source Configuration Console.png

We need to create a new policy that will restrict access to a specified list of IP addresses, which can be done by clicking on the Add Policy Rule button.

Source Configuration Console - Add Policy Rule.png

As we can see, a policy is comprised of four things:

  • The Policy Type specifies what type of resource the policy can be applied to.  Each policy type also defines one or more variables that are exposed to the policy rule and policy message.  For Kinetic Task 3.0, the only type of policy is "API Access".
  • The Policy Name is a short, human understandable, description of the policy.  A policy only needs to be defined once, but can be applied to multiple resources, and the policy name is used to reference the policy when it is being applied to a resource.  Example policy names could be: "Deny All Access", "Restrict to Localhost", or "Require Security Token".
  • The Policy Rule defines logic to specify whether access should be allowed or denied.  It is a small snippit that is evaluated just like a task node connector in the Kinetic Task Tree Builder.  The simplest example of a policy rule is false (indicating that access is never allowed).
  • The Policy Message is a small snippit of logic that is evaluated just like a task node parameter in the Tree Builder.  This may be static text, or may include dynamic variables or functions.  If access is denied to a resource by any of the applied policies, the policy messages from each of the denying policies will be returned rather than the requested resource.

For the purpose of this walkthrough, we know that the Policy Type will be "API Access" (in fact this is the only policy type available in the dropdown for Kinetic Task 3.0).

Writing our own KSL policies it outside of the scope of this article, so we will use one of the pre-written rules available on the KSL Snippits resource article.  Based on the description, we can use the "Restrict to IP Whitelist" Policy Rule snippit.  This leaves us with values like this:

Source Configuration Console.png

From here, we simply need to click the Save button to save this policy rule.  

Lets also add a second policy, this time based on the "Require Security Token" policy rule snippit.

Source Configuration Console - Policy Rules Tab (Token Policy Rule).png

Once we are done, the Policy Rules table should end up looking like this:

Source Configuration Console - Policy Rules Tab (Complete).png

Apply Policies to a Resource

Once policies are defined, they need to be applied to a resource.  The resource that we will be applying the policies to in this walkthrough is API Access to the "Sample" source root.  Kinetic Task API Access policies are applied on a per-source root basis.  This allows different source roots to have different security policies.

Policies are applied to a source root on the Source Roots tab of the Source Configuration Console.  Click on the "Sample" row of the Standard Source Roots table to configure it.

Source Configuration Console - Configured Policy Rule.png

From the details view of the "Sample" source root, shown below, we can see that the there are currently No policy rules applied.  To apply a policy rule, simply select it from the Add Access Policy dropdown, which lists the names of all of the configured policies.

Source Configuration Console - Kinetic Request 1.png

After selecting the access policy, it will be added to the list of policies applied to the source root.  Below, we can see that the "Restrict to IP Whitelist" API Access Policy has been applied to the source root.  Lets add the "Require Security Token" API Access Policy at this point as well.

Source Configuration Console - Source Roots Tab (Add Token Policy).png

After selecting the "Require Security Token" Access Policy, the soure root configuration should look like this:

Source Configuration Console - Source Roots Tab (Configured Policies).png

Now that all of the desired policies have been applied, click the Save button to save the source root configuration.

Access the Resource

API Access to the "Sample" source root is now restricted to the requests originating from one of the IP addresses configured in the whitelist that include the specified security token.  The easiest way to test a security policy is to attempt to create a Start trigger or Deferred trigger using the API.  However, because the "Sample" source root that we are using does not have an implemented integration, we will need to manually call the API.

Kinetic Task includes two helper pages that can be used to call the REST API to create a new Start trigger or a new Deferred trigger.  These are useful in cases such as this where we are testing a source root that may not be fully implemented yet.  They are available via the following two URLs and require Kinetic Task Manager privlidges.

For the purposes of this walkthrough, we will use the start_tasks.html page in order to validate that our security policies are working as desired.  Below is a form that calls the Kinetic Task API when it is submitted.  For the purposes of this test, the only value that matters is the Source Name value (which should be "Sample", the name of our source root).  The other values are necessary to create a start trigger, however they are not looked at until after the security policies have been evaluated.

Start Tasks 1.png

Once the values have been configured, click on the Submit button in order to submit the API request.  A message similar to the one shown below should appear. 

Start Tasks 2.png

From the message above, we can see that both of our security policies were successfully applied.  Both of the policy messages are included:

  • security token not provided
  • request does not originate from IP whitelist (IP_ADDRESS)

This form does not have the ability to set a security token header, so to continue testing lets remove the "Request Security Token" policy from our "Sample" source root.  Removing a security policy can be done by again clicking on the "Sample" row of the Standard Source Roots table of the Source Roots tab to configure the source root.  Simply click on the trashcan icon next to "Require Security Token" to remove it and click the Save button.

Source Configuration Console - Source Roots Tab (Remove Token Policy).png

Additionally, we could see from the access denied message that the IP address that our request originated from was not in the whitelist.  Lets add it to the Rule before attempting to create another start trigger using the API.  This can again be done by clicking on the desired policy rule from the Policy Rules tab of the Soure Configuration Console.

Source Configuration Console - Source Roots Tab (Update Whitelist Policy).png

After updating the "Restrict to IP Whitelist" rule, lets try again to create a start trigger using the start_tasks.html API helper form.

Start Tasks 3.png

After clicking Submit, there are no longer see any access denial messages.  This means that, if we had provided a valid Source GroupSource Id, and Tree Name combination that we would have been allowed access to create a trigger using the API.