/
Hobson REST Authorization

Hobson REST Authorization

Mar 01, 2017

Users, roles and policies allow fine-grained authorization to the Hobson REST API.

Users

A user is an entity that can authenticate with Hobson and invoke REST API functions. A user can be assigned a role.

Roles

A role is a named entity that can be assigned to one or more users. A role will have an associated policy.

Policies

A policy is a set of criteria that determine what a role is allowed to do via a set of declarative statements.

Statements

A statement declares authorization to use a facet of the REST API. It is comprised of an action and one or more resources.

Statement actions

Statement actions indicate an allowable function and are detailed in the table below. Note that actions have two components - a category and a function separated by a : character. Note that the function can be a * character indicating any function in that category. For example:

*             (any action)
device:*      (any device action)
device:create (device creation action)

 

Action

Description

Resource Format

dataStream:create

Creates new data streams

{hubId}

dataStream:delete

Delete data streams

{hubId}:{dataStreamId}

dataStream:read

Get details about data streams

{hubId}:{dataStreamId}

dataStream:update

Update details of data streams

{hubId}:{dataStreamId}

device:configure

Update device configurations

{hubId}:{pluginId}:{deviceId} 

device:create

Create new devices

{hubId}

device:delete

Delete devices

{hubId}:{pluginId}:{deviceId} 

device:execute

Execute device actions

{hubId}:{pluginId}:{deviceId}:{actionClassId}

device:read

Get details about devices

{hubId}:{pluginId}:{deviceId} 

device:update

Change device variables

{hubId}:{pluginId}:{deviceId}:{variableName}

hub:configure

Update hub configurations

{hubId}

hub:execute

Execute hub actions (e.g. shutdown)

{hubId}

hub:read

Get details about hubs

{hubId}

plugin:configure

Update plugin configurations

{hubId}:{pluginId}

plugin:delete

Delete hub plugins

{hubId}:{pluginId}

plugin:execute

Execute plugin actions

{hubId}:{pluginId}:{actionClassId}

plugin:install

Install new hub plugins

{hubId}

plugin:read

Get details about plugins

{hubId}:{pluginId}

task:create

Create new tasks

{hubId}

task:delete

Delete tasks

{hubId}:{taskId}

task:read

Get details about tasks

{hubId}:{taskId}

task:update

Update the details of tasks

{hubId}:{taskId}

Statement resources

Each statement action will have one or more resources associated with it. The format of the resource is action specific and shown in the table above. Each segment of a resource is separated by a : character and can have a value of * to indicate all resources at that level. For example, the plugin:read action could specify one of the following resources:

*                                          (all plugins for all hubs)
local:*                                    (all plugins for the local hub)
local:com.whizzosoftware.hobson.hub.sample (only the sample plugin for the local hub) 

Examples

The following is an example of two roles: an admin that can perform any action on the local hub and an operator that is only allowed to read and update any local device.

[
  {
    "role": "admin",
    "statements": [
      {
        "actions": [
          "*"
        ],
        "resources": [
          "local:*"
        ]
      }
    ]
  },
  {
    "role": "operator",
    "statements": [
      {
        "actions": [
          "device:read",
          "device:update"
        ],
        "resources": [
          "local:*"
        ]
      }
    ]
  }
]