Kapua Permissions Explained

Kapua has a lot of different permissions for various purposes, all of which can be mixed to get different combinations for different users and purposes - this naturally adds complexity to them but also opens a world of possibilities. This way we can have users that can see and edit Devices but cannot delete them or users that can only see Tags or Roles with "Permissions" tab...

This document was created because adding, editing and using permissions in Kapua can be rather difficult some times, so end users like you will not waste time with searching and debugging which permission(s) is/are needed for certain operation but will rather focus on the primary task itself.

Below there is a description for every service/grid in Kapua and which permissions need to be granted in order to see certain tabs or to enable certain buttons or features. For most of them the process and logic are pretty straightforward but some of them must be "studied" a bit in detail.

Forwardable Permissions

But before we dive into Kapua's permissions we have to mention one important thing that can be more confusing than others - so called Forwardable option in permissions.

Forwardable permission is a link between a parent account and child account; It enables parent account to edit child account's settings, view its Users... In short, this permission can limit certain user to viewing users only in his "scope". The best way to explain this is through an example. Imagine you have account named account0 and in this account you have the following users:

• user0 (permissions: Account:Read, Account:Write, User:Read - forwardable set to False)
• user1 (permissions: Account:Read, Account:Write, User:Read - forwardable set to True)

Create a child account within account0 named account0_1. Now login as user0 and go to Child Accounts view - try to see account0_1's Users - Kapua will return an error. This is because this user does not have Forwardable option on User permission set to true and thus user cannot see Child Account's users. Same thing happens if you navigate to upper right corner where the [username]@[account name] button is, you click Switch to Account..., select account0_1 and then navigate through the GUI - Kapua will start reporting errors that you do not have proper permissions to do this.

Same thing happens with Account:Write permission - if this user tries to change account's parameters, Kapua will return an error saying that user does not have proper permissions, which is again OK, since user's Account:Write permission is not Forwardable. This may be a bit odd for you, but we will talk more about this in a moment.

If you now login as user1, there will not be such problems, since all the permissions are forwardable - as user1 you will be able to see all of the child account's settings and also all of the users and their parameters.

If we now take a deeper dive into this, you can see, that Forwardable permission opens several options - you can close user in his so called scope - so he can only see his account and his users, but if he also has Forwardable permission, he can also see Users in Child Accounts and all of their settings. This is also explained in Child Accounts section of this text.

In this document only specific permissions and permission mix will be described, simple Read/Write/Delete permissions will be skipped if their functionalities are straightforward - but if you still have any questions after reading this document, please post a question/issue on Github or join us on one of community meetings!

Welcome and About

Welcome and About are used to show some basic information about Kapua. These two tabs are enabled by default, so user can always see and use them (even if the user has no permissions). User can also always change its password (upper right corner).

Connections

Connections in Kapua are one of the special items in Main menu grid. Because user cannot add or delete connections (that can only Broker do), user can only edit parameters of certain connection (that is why table bellow does not describe how to enable Add or Delete buttons).

Connections view is also closely related to Users in Kapua - connections can be connected/reserved to/for a certain user only (Reserved User and Allow user Change options) or can be open to all users. Because of this, Connections view has two "User" filter options - Reserved User and Last User which are enabled only if user has User:Read permission - otherwise these filter options are not available.

Devices

Kapua is a device management software and therefore it is logical that we have Device view. With it, we can monitor the device's condition, status and many other things. If user has Command permissions, we can even send some simple commands to it remotely or reboot it, if necessary. Devices view is the most complex view in Kapua, since it has more than 10 tabs and subtabs all of which need some special permissions for viewing/editing. If user has only Device:Read permission, the Description tab will be enabled and user will be able to see all the info of a certain device (if there are any, since user cannot add devices without Device:Write permission). Export to CSV button and refresh button are also enabled (even if there are no devices in the list).

One of the specialities is in Tags tab - user needs Device:Write permission to be able to add and delete tags and not Device:Delete or Tag:Write/Delete since there permissions are used for deleting devices and editing/deleting tags respectively.

Other buttons/features do no require any special permissions as you can see from the table bellow.

Batch Jobs

Another interesting and generally useful feature in Kapua are Jobs. User can start/stop bundles, write assets or configuration, download and install a package and lots more on remote devices - they can even be scheduled in advance! All in all it is a powerful tool for device management.

Everything you need to start working with Jobs is in bottom table - it is pretty straightforward. If in doubt, do not hesitate to ask us for more clarification.

Data

Data tab is one of the simplest tabs in Kapua which is used to see the data that is sent from devices. It literally needs only one permission for showing the Data tab and "Device:Read" permission to show two additional tabs ("By Device" and "By Assets"). Because user cannot write (or delete) data in kapua, there is no need (for now) for user to have "Data:Write/Delete" permissions.

Tags

Tags are interesting feature in Kapua, allowing user to tag certain devices with a specific tag for various purposes. This is different than grouping, since user can see all the devices regardless of their tags, but cannot see devices in ceratain groups if he has insufficient permissions (see Group option in permissions). Also device can have multiple tags but can be part of only one group.

Tags can be used to check devices that are in certain area or in certain state or anything similar. This gives end-user additional options over device management. All the permissions are pretty straight forward and do not need any extra explanation.

Users

Users in Kapua are basis for everything - without user you cannot even login! Nevertheless, let's take a closer look on some of the permissions. To see Users tab, end-user needs only User:Read permissions and nothing else. To edit and delete them, User:Write and User:Delete permissions are needed respectively.

For showing Credentials tab, user needs Credentials:Read permission (alongside with User:Read) and for editing/unlocking/deleting them Credentials:Write and Credentials:Delete respectively.

Roles tab is a bit different. For Roles tab to be visible user needs User:Read, Role:Read and Access_info:Read permissions, but for Add and Revoke buttons to be enabled user also needs Access_info:Write/Delete (and not "Role:Write/Delete" "- these are meant for adding, editing and deleting roles).

"Permissions" tab is again a bit different and deserves a bit more explanation then others. If user wants to see Permissions tab, "Access_info:Read", "User:Read" and "Domain:Read" permissions are needed - do not forget on Domain:Read permission! But why? If you look at "Grant Permission" window closely, you will see, that we have "Domain", "Action", "Access Group" and "Forwardable" options - and the first one, "Domain" has its own permission just for enabling this dropdown menu. You can imagine "Domain:Read" permission as "entry point" for all other permissions and this is its only task. It has no other function in Kapua except this. This is also the reason why "Domain:Write" and "Domain:Delete" permissions are not needed - user needs Access_info:Write/Delete to grant and revoke permissions.

Word of caution: Be careful which permissions you grant to users, because if you grant them Access_info:Read/Write in combination with User:Read, they can start granting permissions themselves and therefore do things they are not supposed to.

Roles

Roles are best to imagine as a "set of permissions"; User can add several permissions to a certain role and name it e.g. "user_roles" and this role can then be assigned to multiple users. End result is that this is much faster than adding every single role to every user - and it is also more elegant.

Roles have no special permission combinations, so user has to have Role:Read/Write/Delete permissions to see, edit and delete permissions and Access_info permissions in combination with Role permissions to see "Permission" tab.

If user wants to see which role is granted to which user, User:Read permission has to be added (see table bellow).

Access Groups

Access Groups have similar purpose in Kapua as Tags but with one important difference - every device can be part only of one group, whereas number of tags is not limited. This adds additional options in Kapua - it may seem obsolete but if there are hundreds of devices, every "sorting" feature like this comes in handy.

There are no special permissions needed for showing Access Groups item in the main menu - user only needs Access_group:Read/Write/Delete permissions and optional Device:Read for viewing "Assigned Devices" tab.

Child Accounts

Child Accounts are the basis for "extending" Kapua an its functionalities. Just as "Users" can "expand" Kapua "horizontally" (creating multiple users in one account), accounts can do this "vertically" - every account (if its parameters permit this) can have their own child accounts and so on. This way we get a lot of smaller entities/accounts with users that have specific permissions for performing small number of specific tasks or basically anything else.

Here also so called "Forwardable" permissions comes into play - in "Users" tab to be exact. Account:Read/Write/Delete permissions are pretty straight forward, but if user wants to see and use "User" tab, forwardable permission has to be set to True (e.g. User:Read:ALL:YES), otherwise Kapua will return an error that user needs additional permissions.

"Forwardable" permission is also important if user wants to see and edit Services in Child Accounts -> Account Settings. If "Forwardable" is not set to True, user will not be able to set these parameters for child accounts (but will be able to see them in main menu on the left).

Endpoints

Endpoints are a special feature, that does not behave like a "ordinary" Main menu item (such as Roles, Groups, Users...) - except for kapua-sys user that has full read/write/delete access, other users cannot see this item on the left. Although certain users have Endpoint:Read/Write/Delete permissions, this item will not be visible. Instead the added endpoints will be visible in Settings -> Deployment Info (under the Account Information), if user has Endpoint:Read permission. As in Connections, Endpoint:Write/Delete permissions are not used here.

We should also mention one special feature of Endpoints - if you create new endpoints in a child account, they are not added to old ones, but instead are used as a new "root". Example: If we have three endpoints (e.g. eth1/eth1/123, eth2/eth2/123, eth3/eth3/123) in kapua-sys account and we create one new endpoint in kapua-sys's child account "account0" (e.g. eclipse0/eclipse0/123), the three old ones "disappear from the list and only the last one is visible - all other child accounts created from account0 also see only "eclipse0/eclipse0/123" endpoint, until new ones are created in their scope. If all the endpoints in certain child account are deleted, endpoints from parent account are shown as these are now the new "root" endpoints.

Settings

If user has Account permissions, Settings tab is enabled in Main menu, which enables user to see account's settings (so called "infiniteChildItem" and "MaxNumberChildItem" parameters). This is particularly useful if user encounters errors while creating/editing/deleting items; Unfortunately these settings cannot be changed, as this can only parent user/account do.

As stated, Settings view is part of Account permissions - so this item is visible is user has Accoount:Read permission. There are no special features for this view; user needs Account:Write permission (Forwardable can be set to False) if Edit button should be enabled.