Node.js Authorization Library

oso is packaged as a npm module for use in Node.js applications.

API documentation lives here.

To install, see installation instructions.

Working with JavaScript Types

oso’s Node.js authorization library allows you to write policy rules over JavaScript types directly. This document explains how different types of JavaScript values can be used in oso policies.

Note

More detailed examples of working with application objects can be found in Policy Examples.

Objects

You can pass any JavaScript object into oso and access its properties from your policy (see Application Types).

Class Instances

Any new-able JavaScript object (including ES6-style classes) can be constructed from inside an oso policy using the New operator if the constructor (a class or function that responds to the new operator) has been registered using the #registerClass method. An example of this can be found here.

Numbers and Booleans

Polar supports both integer and floating point numbers, as well as booleans (see Primitive Types).

Strings

JavaScript strings are mapped to Polar Strings. JavaScript’s string methods may be called in policies:

policy.polar
allow(actor, action, resource) if actor.username.endsWith("example.com");
app.js
class User {
  constructor(username) {
    this.username = username;
  }
}

const user = new User('alice@example.com');
oso.isAllowed(user, 'foo', 'bar').then(
  result => assert(result)
);

Warning

Polar does not support methods that mutate strings in place.

Lists

JavaScript Arrays are mapped to Polar Lists. JavaScript’s Array methods may be called in policies:

policy.polar
allow(actor, action, resource) if actor.groups.includes("HR");
app.js
class User {
  constructor(groups) {
    this.groups = groups;
  }
}

const user = new User(["HR", "payroll"]);
oso.isAllowed(user, 'foo', 'bar').then(
  result => assert(result)
);

Warning

Polar does not support methods that mutate lists in place, unless the list is also returned from the method.

Likewise, lists constructed in Polar may be passed into JavaScript methods:

policy.polar
allow(actor, action, resource) if actor.hasGroups(["HR", "payroll"]);
app.js
class User {
  constructor(groups) {
    this.groups = groups;
  }

  hasGroups(other) {
    return other.every(group => this.groups.includes(group));
  }
}

const user = new User(["HR", "payroll"]);
oso.isAllowed(user, 'foo', 'bar').then(
  result => assert(result)
);

Iterators

oso handles JavaScript iterators by evaluating the yielded values one at a time.

policy.polar
allow(actor, action, resource) if actor.getGroup() = "payroll";
app.js
class User {
  getGroup() {
    return ["HR", "payroll"].values();
  }
}

const user = new User();
oso.isAllowed(user, 'foo', 'bar').then(
  result => assert(result)
);

In the policy above, the body of the allow rule will first evaluate "HR" = "payroll" and then "payroll" = "payroll". Because the latter evaluation succeeds, the call to Oso.isAllowed will succeed. Note that if getGroup returned an array instead of an iterator, the rule would fail because it would be comparing an array (["HR", "payroll"]) against a string ("payroll").

Asynchronous Iterators

oso handles async iterators in the same manner as synchronous iterators.

Promises

oso will await any Promise and then use the resolved value during evaluation of a policy.

Summary

JavaScript -> Polar Types Summary

JavaScript type

Polar type

number (Integer)

Integer

number (Float)

Float

boolean

Boolean

string

String

Array

List