Managing Roles

Entgra IoTS is shipped with a set of default roles. However, if required, tenant administrators are able to create new customized roles. Tenant administrators can use roles to manage the users and their devices, while end users allocated with device operation permissions can manage their own devices via the Entgra IoTS Console. Administrators can create roles, assign them to a user or a group of users, and edit or delete existing roles.

Adding a Role and Assigning Permissions

Follow the instructions below to add a role:

Sign in to the Entgra IoT Server console.

If you want to try out Entgra IoT Server as an administrator, use admin as the username and the password.
You can navigate to the ADD ROLE page via the following methods:
1. Method 01:
  
  Click on the Menu.
  
  Select USER MANAGEMENT.
  
  Select ROLES.
  
  Select ADD ROLE.
2. Method 02: Click Add under ROLES.
Provide the required details and click Add Role.
- Domain: Provide the user store type from the list of items.
- Role Name: Provide the role name.
- User List: Define the users belonging to the respective role. When you type the first few characters of the username, the Entgra IoT Server will prompt a list of users having the same characters. You can then select the users you wish to add.
Define the permissions that need to be associated with the role you created by selecting the permissions from the permission tree.

As the permissions are categorized, when the main permission category is selected, all its sub-permissions will get selected automatically.

Make sure to select the Login permission. Without this permission, the users are unable to log in to Entgra IoT Server.

Assiging Role Permissions

Permissions	Description
Applications Management	You can install applications on devices registered with Entgra IoT Server via the App Store or you can install applications via the internal REST APIs that is available on Entgra IoT Server. This permission ensures that a user is able to install and uninstall applications via the internal APIs that are available in Entgra IoT Server. For more information on installing applications via the App Store, see Installing Mobile Apps.
Certificate Management	Entgra IoT Server supports mutual SSL, where the client verifies that the server can be trusted and the server verifies that the client can be trusted by using digital signatures. Following permissions grant access to client-side mutual SSL certificates: device-mgt > certificates > manage: This permission enables to create certificates and access own certificates. device-mgt > admin > certificates: These permissions ensure that a user is able to access all available certificates. Users with these permissions can: View all certificates in a list view and in a detailed view Create and remove certificates Verify certificates: This allows an authorized user to authenticate and authorize a device by implementing on-behalf-of authentication.
Configurations Management	The monitoring frequency is configured under the general platform configurations in Entgra IoT Server. The IoT server uses this parameter to determine how often the devices enrolled with Entgra IoT Server need to be monitored. This permission enables users to configure, update and view the general platform configurations in Entgra IoT Server. In the general platform configurations, you need to define the monitoring frequent, which is how often the IoT server communicates with the device agent. For more information, see General Platform Configurations.
Manage Devices	device-mgt > any-device > permitted-actions-under-owning-device: This permission enables you to view and manage all the devices shared with you. device-mgt > devices > owning-device: These permissions enable users to: Enroll and disenroll devices Publish events received by the device client, to the analytics profile Setup geofencing alerts Modify device details such as name and description Retrieve analytics for devices
	This permission enables you to disenroll or unregister Android and Windows devices.
	This permission enables you to enroll or register Android, iOS and Windows devices with Entgra IoT Server.
Device Status	This permission enables you to change a device status.
Device Operations	Entgra IoT Server offers various device operations based on the mobile platform. This permission enables users to view and carry out device operations on their devices. Expand the preferred platform and select the operations that need to be enabled for users that belong to the role you are creating.
Platform Configurations	In Entgra IoT Server the settings can be customized for each platform. This permission enables you to maintain and customize the notification type, notification frequency, and the End User License Agreement (EULA) to suit the requirement of Android, iOS, and Windows mobile platform. For more information, see Android platform settings, iOS platform settings and Windows platform settings.
View Notifications	The failure to carry out operations will be notified to the Entgra IoT Server administrator and the device owner. This permission enables you to view the notifications that were sent.
Manage Policies	In Entgra IoT Server, you can define policies, which include a set of configurations. Entgra IoT Server policies are enforced on the Entgra IoT Server users' devices when new users register with the Entgra IoT Server. The Entgra IoT Server policy settings will vary based on the mobile OS type. This permission enables you to add, modify, view, publish, unpublish and remove policies. For more information on working with policies, see the relevant section (Android, iOS or Windows) under the Device Management Guide.
Manage Roles	Entgra IoT Server allows you to create new customized roles. This permission enables you to add, modify, view and remove roles. For more information on working with roles, see Managing Roles.
Manage Users	Entgra IoT Server allows you to create and manage users. This permission enables you to add, modify, view and remove users. For more information on working with users, see Managing Users.
Manage Groups	These permissions enable you to manage groups pertaining to devices and user roles. The user role related permission enables viewing all user roles available in Entgra IoT Server. The device related permissions enable you to: Create and remove device groups Assign devices to a group Remove devices from a group View the list of groups attached to a device View the list of roles that have access to a group View the groups accessible by the logged in user
Mobile Application Management	You are able to create mobile apps in the App Publisher that is available in Entgra IoT Server. In order to create, publish, delete, install and update mobile applications the required permissions must be selected. To enable users to subscribe to applications and install an application on a device via the App Store you need to select Subscribe that is under the Web App permissions.
Device Type Management	Following permissions enable managing device types: device-mgt > device-type > add: This enables the ability to add or delete event definitions for device types. device-mgt > devicetype > deploy: This enables deploying device type components via API. It is recommended to grant this permission to device admin users.
Authorization Management	Users with this permission can check whether a user has the permission to access and manage a device. It is recommended to grant this permission to device admin users.

Click Update Role Permission.

Configuring Role Permissions

This section provides details on how to configure permissions by defining permissions to an API and the permissions associated with the APIs.

Defining Permissions for APIs

If you wish to create additional permission, follow the steps given below:

Navigate to the JAX-RS web application that of your device types API folder. For more information, see the permission XML file of the virtual fire-alarm.
Define the new permission using the @permission annotation.
The scope defines to whom the API is limited to and the permission that is associated with a given API.
Example:

@Permission(scope = "virtual_firealarm_user", permissions = {"/permission/admin/device-mgt/user/operations"})
Restart Entgra IoT Server and you will see the new permission created in the permission tree.
Now only users who have this specific permission assigned to them will be able to control the buzzer of the fire-alarm.

Permission APIs

Let’s take a look at the default permissions associated with the APIs.

Permissions related to the Entgra IoTS Administrator (admin)

Permissions	Description
device-mgt/admin/dashboard	Permission to access the WSO2 IoT Server analytics dashboard.
device-mgt/admin/devices	Permission to access the APIs related to devices.
device-mgt/admin/devices/list	Permission to access the get all devices API.
device-mgt/admin/devices/view	Permission to access and retrieve device information from the APIs.
device-mgt/admin/groups	Permission to access the APIs related to groups.
device-mgt/admin/device-mgt/admin/groups/list	Permission to access the get all groups API.
device-mgt/admin/groups/roles	Permission to access the API that gets all the roles added to a group.
device-mgt/admin/groups/roles/permission	Permission to access the API that gets all the permissions associates with the roles that can access groups.
device-mgt/admin/groups/roles/add	Permission to access the API that enable a role to be added to a group.
device-mgt/admin/groups/roles/delete	Permission to access the API that enable a role to be deleted from a group.
device-mgt/admin/information/get	Permission to access the get all information API.
device-mgt/admin/notifications	Permission to access the APIs related to notifications.

Default Roles and Permissions

By default, Entgra IoTS includes a set of roles. These default roles and permissions have been explained in the following subsections.

Default User Roles

The following roles are available by default in Entgra IoTS:

admin
internal-devicemgt-user
internal-appmgt-user

i. admin- Role assigned to the super tenant administrator by default.

If you are defining the permissions for an IoTS administrator who needs to perform operations and configure policies, make sure to select admin. The admin permission allows the user to perform operations and configure policies for devices.

If you wish to create a user with administrative permission other than the default administrator in Entgra IoTS, follow the steps given below:
1. Add a new a role.
2. Configure role permissions by specifically selecting the admin permission.
ii. internal-devicemgt-user - This is a system reserved role with the minimum set of permissions to carry out operations. When a user creates an account before accessing the device management console the user is assigned the internal-device-mgt role by default.

iii. internal-appmgt-user - This role has the minimum set of permissions to carry out application management on the device.

Permissions Associated with User Roles

User Role	Allows Actions
admin	The super tenant administrator belongs to this role. By default, a super tenant administrator will have full control on all the device management consoles.
devicemgt-user	Carryout external operations on a device based on the permissions assigned via the permission tree. Example: getting device details, registering a device control the buzzer and many more.
app-mgt-user	Carryout application management operations via the store and publisher, based on the permissions assigned via the permission tree. Example: Managing application lifecycle and subscriptions, installing and uninstalling apps etc.

Removing a Role

Follow the instructions below to update a role:

Sign in to the IoTS device management console and click the menu icon.
Click User Management.
Click Role.
Click Remove on the role you wish to remove.

Click REMOVE to confirm that you want to remove the role.

Searching, Filtering and Sorting Roles

Searching for Users

Follow the instructions given below to search for roles:

Sign in to the IoTS device management console and click the menu icon.
Click User Management.
Click Role.
Search for roles using the search bar.

Filtering Users

Follow the instructions below to filter roles:

Sign in to the IoTS device management console and click the menu icon.
Click User Management.
Click Role.
Filter the roles by the role name.

Updating a Role

Follow the instructions below to update a role:

Sign in to the IoTS device management consoleSign in to the IoTS device management console) and click the menu icon.
Click User Management.
Click Role.
Click Edit on the role you wish to update.
Update the required filed and click Update Role.
- Domain: Provide the user store type from the list of items.
- Role Name: Provide the role name.

Updating Role Permissions

Follow the instructions below to configure the role permissions:

Sign in to the IoTS device management console and click the menu icon.
Click User Management.
Click Role.
Click Edit Permissions on the role you wish to configure.
Select or remove the permissions as required. The levels of authority for granting permissions are illustrated in the table below.

As the permissions are categorized, when the main permission category is selected, all its sub-permissions will get selected automatically.

Authority Levels for Granting Permission

Authority Level	Permission Level
	Make sure to select the Log-in permission. Without this permission, the users are unable to log in to Entgra IoT Server.
	First Level expansion of authority levels.
	First level of device management permission levels with enterprise, roles, authorization, topics and device-type expanded and randomly selected. enterprise: user - if selected, the user will be able to modify and view as well. modify - user is able to modify access to enterprise. view - user can only view who has access to enterprise. roles: roles - when selected, the user is able to view and manage role permissions. view - user is able to modify access to enterprise. manage - user can only view who has access to enterprise. authorization: authorization - when selected, the user is able to authorize and verify the enrolled device. verify - user can verify the device. topics: topics - user can modify and view the topics. view - user is only able to view the topics. device-type: features features - the user is able to view and change features. view - user can view the features. config - user can verify the device. config - user can change the device configuration. view - user can only view the configurations. view - user can view the device type. add - user can add new device types.
	First level of device management permission levels with notifcations and devices expanded and selected. notifications: notifications - the user is able to activate notifications. view - user can only view notifications. devices: dep - the device is enrolled with DEP and is able to perform functions allowed by DEP. add - view - disenroll - enroll - any-device - tenants - change-status - owning-device -
	First level of device management permission levels with reporting and admin expanded and randomly selected. reporting analytics-admin query view delete add analytics bluetooth-beacon view admin device-type device-type view config certificates certificates verify details delete view add groups view add devices permenant-delete update-enrollment
	First level of device management permission levels with device, platform-configurations and metadata expanded and randomly selected. device application review subscription admin owning-device
	First level of device management permission levels with analytics, devicetype and policies expanded and randomly selected. tenants application review subscription admin owning-device
	First level of device management permission levels with certificates, groups, applications and users expanded and randomly selected. tenants application review subscription admin owning-device
	Application management permission levels expanded and randomly selected. First level: Store application application - user is able to view and update all the in-house corporate applications through the Store. review - user is able to review the application. subscription - user can view, update subscriptions to the application. admin - user has administration rights to the application via the Store. review review - user can review access to the Store. update - user is able to able to update the application via the Store. view - user is able to view the application. subscription subscription - user can access/update subscritions to applications in the Store. install - user is able to install selected apps via the Store. uninstall - user has rights uninstall selected apps via the Store. admin subscription subscription - user can update subsriptions to the applications. view - user is able to view subscriptions to the applications. review review - user is able to review application administration access. update - usercan update access to application administration. Publisher admin: review review - user is able to view and review the application in the Publisher portal. view - user is able to view the application. application application - user is able to access and update the application. update - user can update the application. application: application - user is able to view and update the application via the Publisher portal. view - user can only view the application. update - user is able to update the application.

Select the appropriate permission levels and click Update Role Permissions.