Not everyone needs access to all data and all objects within the flespi platform, right? Access control is a handy mechanism to give different permissions to different types of platform users.
Not so long ago we added access restrictions for API tokens using access control lists (ACLs). Now it’s easy to customize permissions for various tokens (see the Tokens menu item on flespi.io) depending on the requirements: e.g. token working with specific channels/devices/streams only, token with read-only access to collect statistics from the platform components, etc.
What’s not allowed is forbidden. ACL mechanism only grants access — by default all actions are denied for the token with enabled ACL and any action not specified in ACL is forbidden.
Token types. The access property determines the "power" of the token — i.e. how far it can reach.
Standard — a basic token sufficient for working with all Telematics hub features of the flespi platform (does not allow creating other tokens).
Master — the almighty token granting access to the flespi platform API and allowing the creation of other tokens.
ACL — a flexible type of token allowing customization of permissions by module and object type. There is no way to allow tokens to create other tokens via ACL. ACL mechanism is not designed for flespi administration.
Token ACL consists of access control entries (ACEs). ACE contains all the necessary data to allow the specific action for the token. Since all the ACL stuff applies to the flespi platform REST API, the ACE structure contains module names or object types, HTTP requests names, and optional object identifiers. Let's take a closer look at the ACE fields:
Module name or object type (URI field in API). The first value you should select when creating a new ACE in ACL. It defines what specific platform module or object type the ACE applies to: After picking the module/object type, click the Add button to customize the new ACE.
Allowed HTTP requests (methods field in API). Determines which of the four HTTP request methods (GET, POST, PUT, DELETE) can apply to the specified module or objects (see the previous step).
Objects identifiers (ids field in API) [optional]. Grant access to a specific set of objects. Obvious note: Only identifiers belonging to the current customer account are allowed.
Possible object identifier values:
specific ids — grant access to the objects with listed ids
all keyword — allows the token to access all existing objects of the specified type and all objects of this type created in the future (for the current customer)
disabled (eye icon crossed) — enables the user to not only access but also manage (create) objects of the given type.
Submodules (NEW!) — you can separately fine-tune permissions for different submodules within a module. E.g. you can grant access to the device settings while not allowing to modify the device itself:
Note: You can add several ACEs for a single token. To do so just pick another module in the acl dropdown and click Add — the new ACE will be added to the list. To delete one of the ACEs from the token click the red trash bin icon at the bottom of the ACE configuration.
Token for MQTT broker
One of the standard scenarios is the need for a token to access the flespi MQTT broker. To create one, pick the mqtt module from the drop-down and customize the topic, actions, and methods depending on the roles. You may need to create several tokens — one with full privileges, one for consuming messages only, etc.
To create a token capable of getting this data from respective MQTT topics, you need to create REST ACLs to the desired elements.
NOTE: you shouldn't create an "mqtt" ACL!
E.g. you want to access the stats on the channel with id=10101. Your ACL should grant access to "gw/channels/", since you only want to read the stats, tick GET method only, and list the "10101" in the id field.
Here's how it looks:
Now, you'll be able to get current traffic value (flespi/state/gw/channels/10101/traffic topic), channel status (flespi/state/gw/channels/10101/enabled topic), and a lot more:
The same holds true for other flespi elements (e.g. devices, streams, etc.) as well as for the platform as a whole.
Requests with keyword all in place of identifiers list in the URI work fine in ACL. In such a case, a token only works with the objects it has enough permissions for.
During the validation process, only one ACE is selected to verify the access for the token. This one ACE is the most suitable for the current request by the following criteria:
it matches the request URI better than other ACEs (e.g. for request by URI /gw/channels/all/messages ACE with URI field gw/channels matches better than ACE with URI field gw; for the same request ACE with URI field gw/channels and with specified identifiers matches better than ACE with URI field gw/channels and without identifiers)
it matches the request HTTP method.
These criteria apply to the ACEs in ACL sequentially. The first and the only one matching ACE is selected to continue the validation process. If the matching ACE does not contain identifiers value, the current request processing continues as is. Otherwise, access only for the specified identifiers is allowed. If there are more ACEs matching the selection criteria, they are not taken into account. If no matching ACE is found, access to the current request is denied at all.
From the previous paragraph, it follows that ACL can contain any number of ACEs with the same specified platform module or objects and their identifiers. It allows to reduce the size and to improve the readability of an ACE. But the current implementation requires putting specifications for the same objects or modules and the same request type into one ACE. Short example. Say there is an ACL with two ACEs: the first allows PUT requests for gw/devices objects with identifiers 1 and 2, the second allows PUT requests for gw/devices objects with identifiers 1, 2, and 3. The attempt to modify the device 3 via PUT request would be declined because the first most suitable ACE allows using PUT with devices 1 and 2 only.
As you can see from the numerous examples above, the access control mechanism empowers customers of the flespi platform to manage permissions to the elements of the infrastructure depending on the needs and duties of specific users. Tighten the bolts where needed and give full control where allowed.
BTW, we also prepared a video tutorial on how to create a flespi token: