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.

Bellow 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 imporatant 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". 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.

Feature Needed Permissions Forwardable
See Connections tab in main menu Device_connection:Read No
Enabled Edit button Device_connection:Read No
Enabled Refresh button in Connections Device_connection:Read Device_connection:Write No
See Reserved User option Device_connection:Read Device_connection:Write User:Read No
See Allow User Change option Device_connection:Read Device_connection:Write User:Read No
See Last User filter option Device_connection:Read Device_connection:Write User:Read No
See Reserved User filter option Device_connection:Read Device_connection:Write User:Read No

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 permisisons, 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.

Feature Needed Permissions Forwardable
See Devices tab in main menu Device:Read No
Enabled Refresh button Device:Read No
Enabled Export to CSV button Device:Read No
Enabled Add button Device:Read Device:Write No
Enabled Access Group option in Add window Device:Read Device:Write Group:Read No
Enabled Edit button Device:Read Device:Write No
Enabled Access Group option in Edit window Device:Read Device:Write Group:Read No
Enabled Delete button Device:Read Device:Delete No
Enabled Group option in filter menu Device:Read Group:Read No
Enabled Tag option in filter menu Device:Read Tag:Read No
TAG TAB
Enabled Tag tab Device:Read Tag:Read No
Enabled Refresh button in Tag tab Device:Read Tag:Read No
Enabled Apply button in Tag tab Device:Read Device:Write Tag:Read No
Enabled Remove button in Tag tab Device:Read Device:Write Tag:Read No
EVENTS TAB
Enabled Events tab Device:Read Device_event:Read No
Enabled Refresh button in Events tab Device:Read Device_event:Read No
Enabled Export to CSV button in "Events" tab Device:Read Device_event:Read No
PACKAGES TAB
Enabled Packages tab (Installed and In Progress subtabs) Device:Read Device_management:Read No
Enabled Refresh button in Packages tab Device:Read Device_management:Read No
Enabled Install button in Packages tab Device:Read Device_management:Read Device_management:Write No
Enabled Uninstall button in Packages tab Device:Read Device_management:Read Device_management:Write No
Enabled History subtab in Packages tab Device:Read Device_management:Read Device_management-registry:Read No
BUNDLES TAB
Enabled Bundles tab Device:Read Device_management:Read No
Enabled Refresh button in Bundles tab Device:Read Device_management:Read No
Enabled Start button in Bundles tab Device:Read Device_management:Read Device_management:Execute No
Enabled Stop button in Bundles tab Device:Read Device_management:Read Device_management:Execute No
CONFIGURATION TAB
Enabled Configuration tab (Services and Snapshots subtabs) Device:Read Device_management:Read No
Enabled Refresh button in Configuration tab Device:Read Device_management:Read No
Enabled Save button in Configuration tab Device:Read Device_management:Read Device_management:Write No
Enabled Discard button in Configuration tab Device:Read Device_management:Read Device_management:Write No
Enabled Refresh button in Snapshots subtab Device:Read Device_management:Read Device_management:Write No
Enabled Download button in Snapshots subtab Device:Read Device_management:Read Device_management:Write No
Enabled Rollback to button in Snapshots subtab Device:Read Device_management:Read Device_management:Write No
Enabled Upload And Apply button in Snapshots subtab Device:Read Device_management:Read Device_management:Write No
COMMAND TAB
Enabled Command tab Device:Read Device_management:Read Device_management:Execute No
ASSETS TAB
Enabled Assets tab Device:Read Device_management:Read No
Enabled Refresh button in Assets tab Device:Read Device_management:Read No
Enabled Save button in Assets tab Device:Read Device_management:Read Device_management:Write No
Enabled Discard button in Assets tab Device:Read Device_management:Read Device_management:Write No

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.

Feature Needed Permissions Forwardable
See Batch Jobs tab in main menu Job:Read No
Enabled Refresh button Job:Read No
Enabled Add button Job:Read Job:Write No
Enabled Edit button Job:Read Job:Write No
Enabled Delete button Job:Read Job:Delete No
Enabled Start button Job:Read Job:Execute No
Enabled Stop button Job:Read Job:Execute No
Enabled Restart button Job:Read Job:Execute No
TARGETS TAB
Enabled Targets tab Job:Read Device:Read No
Enabled Refresh button Job:Read Device:Read No
Enabled Add button Job:Read Job:Write Device:Read No
Enabled Delete button Job:Read Job:Delete Device:Read No
Enabled Start button Job:Read Job:Execute Device:Read No
STEPS TAB
Enabled Steps tab Job:Read No
Enabled Refresh button Job:Read No
Enabled Add button Job:Read Job:Write No
Enabled Edit button Job:Read Job:Write No
Enabled Delete button Job:Read Job:Delete No
SCHEDULES TAB
Enabled Refresh button Job:Read Scheduler:Read No
Enabled Add button Job:Read Scheduler:Read Scheduler:Write No
Enabled Delete button Job:Read Scheduler:Read Scheduler:Delete No
EXECUTIONS TAB
Enabled Refresh button Job:Read

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.

Feature Needed Permissions Forwardable
See Data tab in main menu Datastore:Read No
Enabled Refresh button Datastore:Read No
"BY DEVICE" TAB
Enabled Refresh button Device:Read Datastore:Read No
"BY ASSET" TAB
Enabled Refresh button Device:Read Datastore:Read No

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.

Feature Needed Permissions Forwardable
See Tags tab in main menu Tag:Read No
Enabled Refresh button Tag:Read No
Enabled Add button Tag:Read Tag:Write No
Enabled Edit button Tag:Read Tag:Write No
Enabled Delete button Tag:Read Tag:Delete No
ASSIGNED DEVICES TAB
Enabled Assigned Devices tab Tag:Read Device:Read No
Enabled Refresh button Tag:Read Device:Read No

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 permissons, 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.

Feature Needed Permissions Forwardable
See Users tab in main menu User:Read No
Enabled Refresh button User:Read No
Enabled Add button User:Read User:Write No
Enabled Edit button User:Read User:Write No
Enabled Delete button User:Read User:Delete No
See Reserved for Connection option User:Read Connection:Read Device:Read No
CREDENTIALS TAB
Enabled Credentials tab User:Read Credential:Read No
Enabled Refresh button User:Read Credential:Read No
Enabled Add button User:Read Credential:Read Credential:Write No
Enabled Edit button User:Read Credential:Read Credential:Write No
Enabled Delete button User:Read Credential:Read Credential:Delete No
Enabled Unlock button User:Read Credential:Read Credential:Write No
ROLES TAB
Enabled Roles tab User:Read Role:Read No
Enabled Refresh button User:Read Role:Read Access_info:Read No
Enabled Assign button User:Read Role:Read Access_info:Read Access_info:Write No
Enabled Remove button User:Read Role:Read Access_info:Read Access_info:Delete No
PERMISSIONS TAB
Enabled Permissions tab User:Read Access_info:Read Domain:Read No
Enabled Refresh button User:Read Access_info:Read Domain:Read No
Enabled Grant button User:Read Access_info:Read Domain:Read Access_info:Write No
Enabled Revoke button User:Read Access_info:Read Domain:Read Access_info:Delete No

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).

Feature Needed Permissions Forwardable
See Roles in main menu Role:Read No
Enabled Refresh button Role:Read No
Enabled Add button Role:Read Role:Write No
Enabled Edit button Role:Read Role:Write No
Enabled Delete button Role:Read Role:Delete No
PERMISSIONS TAB
Enabled Permissions tab Role:Read Access_info:Read Domain:Read No
Enabled Refresh button Role:Read Access_info:Read Domain:Read No
Enabled Add button Role:Read Access_info:Read Role:Write Domain:Read No
Enabled Delete button Role:Read Access_info:Read Role:Delete Domain:Read No
GRANTED USERS TAB No
Enabled Granted Users tab Role:Read User:Read No
Enabled Refresh button Role:Read User:Read No

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.

Feature Needed Permissions Forwardable
See Access Groups in main menu Group:Read No
Enabled Refresh button Group:Read No
Enabled Add button Group:Read Group:Write No
Enabled Edit button Group:Read Group:Write No
Enabled Delete button Group:Read Group:Delete No
ASSIGNED DEVICES TAB
Enabled Assigned Devices tab Group:Read Device:Read No
Enabled Refresh button Group:Read Device:Read No

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).

Feature Needed Permissions Forwardable
See Child Accounts in main menu Account:Read No
Enabled Refresh button Account:Read No
Enabled Add button Account:Read Account:Write No
Enabled Edit button Account:Read Account:Write No
Enabled Delete button Account:Read Account:Delete No
USERS TAB
Enabled Refresh button Account:Read User:Read Yes (User:Read)
Enabled Add button Account:Read User:Read User:Write Yes (User:Read/Write)
Enabled Edit button Account:Read User:Read User:Write Yes (User:Read/Write)
Enabled Delete button Account:Read User:Read User:Delete Yes (User:Read/Write)

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.

Feature Needed Permissions Forwardable
See Endpoints in main menu / /
See Endpoints in Settings Account:Read Endpoints:Read No

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.

Feature Needed Permissions Forwardable
See Settings in main menu Account:Read No
Enabled Edit button Account:Read Account:Write No

results matching ""

    No results matching ""