Security Policy Basics

Introduction

Security policies are definable expressions that control who is authorized to access/create/modify/delete specific resources.

Parts of a Security Definition

Each Security Definition has the same four elements.

Name

The Name is descriptive text that is presented in dropdowns. It must be Unique, even if it is for a different type.

Type

Because there is a different scope between Space and kapps, there are different types available.

Avaialble Types for Space:

Type (where they can be used)Available Bindings
Spaceidentity(...), space(...)
Teamidentity(...), space(...), team(...)
Useridentity(...), space(...), user(...)
Datastore Formidentity(...), space(...), form(...)
Datastore Submissionidentity(...), space(...), form(...), submission(...)

Avaialble Types for Kapps:

Type (where they can be used)Available Bindings
Kappidentity(...), space(...), kapp(...)
Formidentity(...), space(...), kapp(...), form(...)
Submissionidentity(...), space(...), kapp(...), form(...), submission(...)

Message

The message is what is returned to the customer if the Rule evaluates to false.

Rule

The Security Definition rule is a single JavaScript expression that has to evaluate to be true or false. An extremely basic example is identity('username') === "han.solo".

More realistically, you'd set a rule to evaluate a function to check for a team or role.

JavaScript provides a mechanism for wrapping scope that also happens to be helpful for wrapping multiple statements and expressions into a single expression.

(function () {
    //insert multiple functions and expressions
})();

Adding something like this makes the definition much more flexible, but it can make it more complex. We use this model for many of the Security Definitions we create in kinops:

(function() {
__// Helper method__
  var hasIntersection = function(obj1, obj2) {
// Ensure the objects are not empty
obj1 = (obj1 === null || obj1 === undefined) ? [] : obj1;
obj2 = (obj2 === null || obj2 === undefined) ? [] : obj2;
// If the parameters are not lists, wrap them in lists
var list1 = (obj1 instanceof Array) ? obj1 : [obj1];
var list2 = (obj2 instanceof Array) ? obj2 : [obj2];
// Find the intersection
var intersection = list1.filter(function(n) {
  return list2.indexOf(n) != -1;
});
// Return whether any intersecting values were found
return list1.find(function(value) {return hasValue(list2, value)}) !== undefined;
      };
      __// Helper method__
      var hasValue = function(list, value) {
return (list instanceof Array) && list.indexOf(value) != -1
      };

  __// Employee Check - unique portion of the Rule__
  return hasIntersection(identity('teams'), ['Role::Employee']);
})()

While this looks complex at first glance, it really only contains three pieces that are marked by comments.

The Helper methods are included in all the predefined kinops Security Definitions like this one. The top two sections are there to make sure that the first object in the hasIntersection function is present in the second object. In the above example, the Identity of the person's team is part of the Role::Employee. To put it another way, the definition is asking "Is the person requesting access an employee?".

As a slightly more complex example, the definition below checks whether the person is a member of the assigned team or is the assigned individual for a submission. This would replace the employee check section of the JavaScript expression above.

return (
    // Assigned Team
    hasIntersection(values('Assigned Team'), identity('teams'))
    // Assigned Individual
    || hasIntersection(values('Assigned Individual'), identity('username'))
    // Last updater (this is necessary so that a user can see that they successfully
    // re-assigned a submission)
    || submission('updatedBy') == identity('username')
    );

Basically, this definition asks whether the person is a member of the assigned team, if they are the assigned individual, or if they are the last person to update the submission. The other JavaScipt functions are the same.

Note: Space Admin users are automatically granted permission to everything. That is why you see the Rule for Space Admins set to false by default you get to break the rule anyway.

Use

Security Definitions are used throughout the application to provide limits on access to different elements like forms, kapps, and submissions.

Expressions

Security policies give us the ability to apply security that is logically easy, but impossible to implement with traditional group-based security.

  • Ex: “A user can access this form if they are NOT in a specific team”
  • Ex: “A user can access this form if they have a matching attribute"
  • Ex: “A user can access this form if they are in Team A AND in Team B”
  • Ex: “This form is only available on “Weekends”
  • Ex: “This process is usable by people who have been employed > 1 year"

Security Policy Precedence

The Kinetic Platform leverages a number of nested scopes. Security Policies evaluate the highest scope first, and proceed until all appropriate policies have been evaluated.

  • Users with Space Admin privileges bypass all security policy evaluation
    • This is why invalid security policies sometimes don’t show up until users without Space Admin permissions begin using the system
  • If someone can modify a Kapp, they can access/create/modify all Forms and Submissions in that Kapp
    • This is new in Platform v5, pre-v5 Submissions were independent of Kapp Modification security
  • If someone can modify a Form, they can access/create/modify all Submissions of that Form

Submission Searching

Security policies needed to be coordinated with submission search patterns

  • Security Policies can not be a replacement for submission searching
  • If there are more than 25 submissions encountered in a search that the Submission Access policy denies, the entire query fails
    • Security Policies must be evaluated after querying the database
    • We limit failures to avoid "table scans" and the resulting performance degradation
Example Search:All submissions where the Assigned Team is “Facilities”
Example Good Submission Access Policy:The current user is in the Facilities Team
Example Bad Submission Access Policy:The current user has the attribute “Manager” set to true