The ClearBlade Platform allows for Systems to define and customize their own user registry. The users that get created have special permissions, allowing them to only view and edit properties related to them.

Users are granted roles (see below) which then describe and grant users specific authorities. Following an oAuth model, users are given tokens, when successfully authenticated, which then allow for all future API calls to be correctly permissioned and audited.

ClearBlade Overview

Users, Roles, Permissions

The ClearBlade platform’s security design is based off of the idea of Role Based Access Control (otherwise known as RBAC).

The central idea is that permissions are applied to roles, rather than directly to the user. In ClearBlade’s implementation, the users are then associated with those roles. You can think of a user on the ClearBlade Platform as a tuple consisting of an identifier and a list of roles. There is no “root user” exposed to the consumers of your applications written with the platform. The only user with complete permissions over everything is the Developer user. Which is, as it says, reserved for developers and should never be used from within applications built with the platform.

The user identifier is important for auditing purposes and general ease of use. We use the user’s identifier to keep records of actions performed by that user, in addition to using it for authentication purposes. Roles are important because they define the actions that can be performed by the users those roles are associated with. These permissions include CRUD on collections and executing code services. In the near future they will also include publish and subscribing to certain MQTT topics.

The process for authenticating to the platform is fairly simple. The user performs a POST request against the /api/v/1/auth endpoint with their username, password, the System Key, and System Secret. If the login information is valid, the user is returned a token. The token is valid for a configurable number of days (the default is 30 days). That token is attached as a header to each subsequent API request. The token is required for virtually all transactions within the platform (except logging in).


Another simple, but important concept is the Session. When a user logs into the platform, they are issued a token that they must use for every platform request. That token will become invalid upon logout, or token expiration. Each token is associated with a session, which is a record of who is logged in at any given moment. The session does not correspond to the permissions applied to a role, so if the permissions are changed on a role, the changes will apply even to users who are currently in a session.

Creating users can be done via HTTP endpoint or via the GUI. It requires an email for the user and a password. Other information that the developer may require can be processed via that endpoint.

Once a user is created, it has no default permissions to any resource on the platform. Roles must be associated with users.

The developer must supply the registration sigil, their first and last name, their organization, and an email and password to register.

Creating Roles

This may be done via the GUI or via an endpoint. Roles are created and permissions are assigned to them. Those permissions correspond to operations on various resources.

Note that users may have multiple roles. So, if a user has a role that has certain permissions and has another role that doesn’t, the user will have the permissions, even though one of their roles doesn’t specify them.

Managing users

User management may be performed via the API or the GUI. It’s possible to add and remove roles from users, alter the permissions of roles, and many other things. Note that if you alter or delete a role, that change will propagate to every user who has that role.

It’s also possible to delete users from the platform. This will immediately stop their session and log them out.

Role-based Permissions

Roles as we have mentioned in the “About” section are groups of permissions to be applied to various resources within the platform. The permissions that can be applied to a resource vary depending on the resource. We shall list the permissions below

Resource Type Permission Semantic Meaning
Collection Create Add a new item to a collection
Collection Read Perform queries on the collection
Collection Update Can update items within a collection
Collection Delete Can remove items from a collection
Users Read Can read information from the users table
Service Executable Can make a request to the code service. Is synonymous with read, but the end user never sees the Code.
Message History Read Can read message history
Push Can Push Just what it says on the tin, can make a push (if push is included with your installation)

Generally speaking, permissions map to endpoints. The CRUD permissions on a collection map to the POST,GET,PUT,DELETE HTTP verbs respectively. The executable permission maps to calling POST to a code service, etc etc.