Users and Access Rights¶

Overview¶

This section covers the following use cases:

• How to add a new user
• How to reset a pin counter for account activation
• How to add a machine user
• How to create and revoke access tokens
• How to change the access permissions of a user
• How to create and change permission roles
• How to export and import permission roles
• How to assign permission roles to user groups

Add a new user¶

Step 1: Create new user¶

Navigate to the Admin application and click the button + Profile in the section Users.

Create a new user

Step 2: Enter user details¶

Enter the information about the user, at least "Username" and "E-Mail" (please make sure, the email address is entered all in lower case letters). Click Save.

• An activation email will be automatically sent to the email address of the user. The users can follow the instructions of the email to activate the account and set a password.
• 2FA stands for 2 Factor Authentication via VPN (Virtual Private Network). Per default, it is not configured, so leave it switched off.
• Optionally, you can already upload a profile picture.

User details form

Step 3: Add or remove the user to/from a user group¶

The newly created users (Human and Machine) have to be added to a user group to get the related permissions.

Navigate to the Admin application and in the section Groups select the group you want to add your users (e.g. "Study Team").

1. You see if a user has already activated his/her account
2. In the list "Available Users" you can click the Add User button in the column "Actions" to add a user to the group. Users that are already in the group appear in the list "Selected Users" and are greyed out in the list "Available Users".
3. After you added all users to the group, click the Save button.
4. To remove a user from a Group, click the related Removebutton in the "Selected Users" list and then click the Savebutton.

Manage users in groups

Reset pin counter¶

If a user fails five times to enter the correct pin to activate their account, an Admin can reset the pin counter by navigating to the Admin app and then to the Users section. In the list of users, the status of the pin trials is displayed. After clicking on a user with red status, the pin trials can be reset using the button reset pin counters.

Reset pin counters

Add a machine user¶

Follow steps 1 to 3 of the section Add a new user above, but in step 2 "Enter Details", change User kind to Machine from the drop-down menu (see picture below). For machine users, only a username has to be defined.

Add a machine user

Instead of username and password, machines use a token to authenticate themselves. While it is also possible to generate tokens for human users, it is a requirement for machine users. Follow the section Create and revoke access tokens below to create an access token for your newly created machine user.

Create and revoke access tokens¶

Navigate to the Admin application and in the section Users click on the user in the list, for which you want to create a new token.

If you do not see the user in the list, make sure that the right User kind, ie. Human or Machine, is selected in the filter above the list.

In the detail view of the user, scroll down to the section Token (see image below).

Create and revoke an access token

Create and revoke token:

1. Enter a name as label of your token. Make the name meaningful to be able to revoke the right token at a later point in time.
2. Click the button + Token to create the token.
3. A pop-up will appear (see image below) with the key and its public identifier. This is the only time the key will be displayed. Make sure to save the key securely. Afterwards, close the pop-up using the cross in the top-right corner.
   
4. All created tokens are displayed in the list. You can toggle to show or hide tokens, which have already been revoked again.
5. In case revoked tokens are included in the list, they are labeled accordingly with a red No in the column titled "Enabled".
6. To revoke a token, click the Revoke button in the corresponding row of the list.

Change the access permissions of a user¶

You can change the access rights of a user by changing its user group. To do so, follow the instructions in section Add or Remove the User to/from a User Group.

Create or change a permission role¶

Roles are a set of permissions (e.g. view permission for a device model object), which can be granted to a user group.

If you know how to configure roles, proceed with following steps:

1. To create a new role, navigate to the Admin application and click the button + Role in the section "Roles" (see image below). Enter the name of the role. Optionally, you can add a description. Once you're done, click the Save button.
   
2. To change an existing role, click on it in the displayed list of roles.
3. You are now on the configuration screen of the roles. You can toggle each right individually. Once you're done, click the Save button.

Export and import a permission role¶

If you want to replicate a role on a new Device Hub instance, you can import it as JSON file. To do so, follow these steps:

1. Navigate to the role you would like to export and open its configuration by clicking on it in the list of available roles.
2. Scroll to the bottom of the page, where you will find the section "Export / Import Role" (see image below.)
   
3. Click on either "Export (all)" or "Export (only true permissions)". The latter is useful in case you would like to combine multiple roles into one, since it will only import true permissions to the new role you like to create, without changing the status of other permissions.
4. The role is automatically saved to your clipboard in JSON. Navigate to the "Export / Import Role" section of the role, to which you would like to import the copied information. Paste the copied JSON into the "Import JSON" text box.
5. Click the Import button to apply the configuration to your new role.
6. Adapt the role as necessary or import additional permissions using the "Export (only true permission)" function.
7. Once you're done, click the Save button.

Assign permission roles to user groups¶

In order to grant a user group certain permissions, an object authorization needs to be defined. An object authorization grants a user group the permissions defined in a role to a selection of objects from the system (e.g. the "Admin" user Group is granted the permissions of the "Device Update" Role to a specific instance of the Product object called "SuperECG").

If you need to first define a new user group, follow these steps:

1. Navigate to the Groups section in the Admin application.
2. Click the + Group button. Define the name of the group and optionally a description. Once done, click the Save button.
3. Add users to the group as described in Add or Remove the User to/from a User Group.

Now, you can perform an object authorization for that group as follows:

1. Navigate to the Object Authorizations section in the Admin application. Click the + Object Authorization button. This will open the form pictured below.
   
2. Choose the object type, for which the authorization should apply from the related drop-down menu. When doing so, keep in mind that permissions of a role will be applied to the assigned object including all its child objects and parent objects! To understand the object hierarchy, consult the role configuration page, which is structured accordingly.
   For example (see illustration below):
   You can choose to apply a role with edit rights for Profile objects and Model objects to a specific Product object, which will grant the edit permission for all Model objects of thatProduct. Alternatively, you can choose to apply the role to a specific Model object of a Product, which will not grant edit permissions to the other Models of the same Product. In both cases, the edit permission for Profile will not be granted, since that is neither a child object nor a parent object of Product. To also grant the edit permission for Profile objects, you would either have to assign the role to the Organization object or create a second object authorization for the same user group, where you assign the role to the Profile object.
   
3. Choose the role with the permissions you would like to apply to that object from the related drop-down menu.
4. Choose the user group, which should receive these rights.
5. Optionally, add a description for this object authorization. This is highly recommended, to keep the overview when maintaining access rights.
6. Once done, click the Save button.