User Management

This tutorial demonstrates how to manage users in Edge Builder. It covers how to:

Initialise Edge Builder server components and CLI
Log-in as admin user
Add a node
Add a new user to Edge Builder
Assign the user a role
Issue commands as new user
Add a new role
Add permissions to role(s)
Remove permissions from role(s)

Initialise the Edge Builder server components and CLI

To initialize the Edge Builder server components and CLI, complete the following steps:

Set up the environment as described in Tutorials Setup
SSH into the master node:
```
vagrant ssh master
```
Start the Edge Builder server components using the following command:
```
sudo edgebuilder-server up -a 192.168.56.10
```

Edge Builder comes with a default user account, which has admin permissions. In this tutorial, we use this account to create new users and manage your team.

Login to the admin account using the following default credentials and the address of the controller:

edgebuilder-cli user login -u iotech -p EdgeBuilder123 -c "http://192.168.56.10:8085"

The following message displays:

INFO: User "iotech" logged in successfully

Confirm that you have a valid license in the Vagrant project directory (edgebuilder-vagrant)

Add the license using the following command:

edgebuilder-cli license add -l DemoLicense -f /vagrant/EdgeBuilder_test_Evaluation.lic

You should see the output similar to that shown below:

INFO: License added successfully
+-------------+--------------------------------------+---------------------------------+-----------+-----------+
| NAME        | ID                                   | FILENAME                        | MAX NODES | EXPIRY    |
+-------------+--------------------------------------+---------------------------------+-----------+-----------+
| DemoLicense | b65c2ba0-c78b-4031-aaf4-cc030d3d763d | EdgeBuilder_test_Evaluation.lic | 100       | unlimited |
+-------------+--------------------------------------+---------------------------------+-----------+-----------+
INFO: Viewing 1 result(s)

Add a node

In this section, we add a node to Edge Builder. It is accessible on 192.168.56.11.

To add an edge node, complete the following steps:

Confirm that the example node configuration file is available using the cat command:

cat /vagrant/examples/single-node-config.json

The output is similar to the following:

{
  "NodeConfig": [
      {
          "name": "node1",
          "description": "virtual node 1",
          "nodeaddress": "192.168.56.11",
          "username" : "vagrant",
          "password" : "vagrant",
          "serveraddress": "192.168.56.10",
          "labels" : []
      }
  ]
}

Add the node to Edge Builder using the following command:

 edgebuilder-cli node add -f /vagrant/examples/single-node-config.json

The output is similar to the following:

INFO: SSH Node(s) added successfully:
+-------+--------------------------------------+
| NODE  | ID                                   |
+-------+--------------------------------------+
| node1 | e01c540b-fa87-4721-b38c-5f0109210381 |
+-------+--------------------------------------+
INFO: Viewing 1 result(s)

Confirm that the node has been added using the following command:

edgebuilder-cli node view --all

The output is similar to the following:

INFO: Finding all nodes...
INFO: *** Node View Results ***
+-------+----------+------------+--------------+----------------+--------------------------------------+
| NAME  |  STATUS  | DEBUG MODE | METRICS MODE | DESCRIPTION    | ID                                   |
+-------+----------+------------+--------------+----------------+--------------------------------------+
| node1 | Deploying| Off        | Local        | virtual node 1 | e01c540b-fa87-4721-b38c-5f0109210381 |
+-------+----------+------------+--------------+----------------+--------------------------------------+
INFO: Viewing 1 result(s)

Note

The status of the node is initially shown as Deploying. After a few minutes, you can re-issue the command and the status will have changed to Up
You can also use the watch command with the node view above to automatically track the status changes

Add a new user to Edge Builder

Add a new user to Edge Builder using the user add command. The new username must be unique and contain only alphanumeric, space, _ and - characters (no spaces). The password must be at least 8 characters in length and contain non-space characters only. For example:

edgebuilder-cli user add --username edge_user --password p@ssw*rd123!

The following message displays (however the ID will be different):

INFO: User created:
+-----------+--------------------------------------+
| NAME      | ID                                   |
+-----------+--------------------------------------+
| edge_user | 93df7984-6b87-4549-827e-6d20be002197 |
+-----------+--------------------------------------+
INFO: Viewing 1 result(s)

Verify the new user exists with the command:

edgebuilder-cli user view -A

Example output:

INFO: Finding all users...
INFO: *** User View Results ***
+---------------------+--------------------------------------+---------------------+-----------------+
| NAME                | ID                                   | ROLE(S)             | NO. PERMISSIONS |
+---------------------+--------------------------------------+---------------------+-----------------+
| eb_provisioner_user | 1024d878-c1be-49e1-92ae-324dab799b76 | eb_provisioner_role |               1 |
| eb_salt_user        | 3ed412c2-4845-46db-a457-c799fc7b9a27 | eb_salt_role        |               1 |
| edge_user           | 750e3b77-c735-4ca3-b9f7-9c132cf87c7b | <none>              |               0 |
| iotech              | 5dde4975-2e45-43a6-be79-98bff491b954 | eb_admin_role       |              89 |
+---------------------+--------------------------------------+---------------------+-----------------+
INFO: Viewing 4 result(s)

You will see at least three users: iotech (the current user), eb_salt_user (used for internal processing only) and the new edge_user.

Note

edge_user has no roles or permissions yet, we will assign the user a role in the next section so they can begin using Edge Builder.

Assign the user a role

By default, new users have no permissions in EdgeBuilder. Assign edge_user the Edge Builder standard role to give grant read-only permissions:
```
edgebuilder-cli user assign -u edge_user -r eb_standard_role
```
The response is similar to the following:
```
INFO: added 1 role(s) to user "edge_user" (ID = 750e3b77-c735-4ca3-b9f7-9c132cf87c7b)
```

Verify the role assignment was successful with the user inspect command:

edgebuilder-cli user inspect -u edge_user

The response provides detailed information on the user, with any role(s) and associated permissions displayed within embedded fields. In the example below, the list of permissions has been shortened for readability:

{
  "CreatedBy": "iotech",
  "ID": "750e3b77-c735-4ca3-b9f7-9c132cf87c7b",
  "ModifiedBy": "iotech",
    "Roles": [
      {
        "CreatedBy": "EdgeBuilder",
        "Description": "EdgeBuilder standard role - read-only permissions (protected) ",
        "ID": "478b16cd-a45d-4268-a9a0-2bc662bbd433",
        "ModifiedBy": "EdgeBuilder",
        "Name": "eb_standard_role",
        "Permissions": [
          {
            "CreatedBy": "EdgeBuilder",
            "ID": "05f51ff0-74c6-4ec6-9ebd-7766778af7e2",
            "Method": "GET",
            "Path": "/api/v1/app_definitions/inspect/{id}",
            "TimestampCreate": 1639412754
          },
          .
          .
          .
          {
            "CreatedBy": "EdgeBuilder",
            "ID": "fc173bd1-7f35-4928-b0ea-a11728da6b7d",
            "Method": "GET",
            "Path": "/api/v1/nodes/provision",
            "TimestampCreate": 1639412754
          }
        ],
        "TimestampCreate": 1625845225,
        "TimestampModify": 1626173571,
      }
    ],
  "TimestampCreate": 1639412847,
  "TimestampModify": 1639413666,
  "Username": "edge_user"
}

Issue commands as new user

The user edge_user is now ready to begin using Edge Builder. Try issuing some commands from their account.

Log-in using the relevant credentials and the same controller address as before:

edgebuilder-cli user login -u edge_user -p p@ssw*rd123! -c "http://192.168.56.10:8085"

Try viewing nodes:

edgebuilder-cli node view --all

The request is successful because eb_standard_role includes the GET /api/v1/nodes permission. Example output:

INFO: Finding all nodes...
INFO: *** Node View Results ***
+-------+--------+------------+--------------+----------------+--------------------------------------+
| NAME  | STATUS | DEBUG MODE | METRICS MODE | DESCRIPTION    | ID                                   |
+-------+--------+------------+--------------+----------------+--------------------------------------+
| node1 | Up     | Off        | Local        | virtual node 1 | 0489f68a-1529-4410-9812-4b6e0d2b0bcc |
| node2 | Up     | Off        | Local        | virtual node 2 | a2ee6b79-e138-4fe6-9a48-ba57ba06245a |
| node3 | Up     | Off        | Local        | virtual node 3 | 98e1067b-fa5a-4ae7-9d08-ba7fc8b8f5c8 |
+-------+--------+------------+--------------+----------------+--------------------------------------+
INFO: Viewing 3 result(s)

To illustrate what happens when a user tries to execute a command without sufficient API permissions, try to add a new user:

edgebuilder-cli user add --username edge_user2 --password p@ssw*rd123!

The permission for adding users is not included in eb_standard_role so this error displays:

ERROR: Exit Code (156): user create failed - unexpected StatusCode: "403 Forbidden" - {"err":"Insufficient Permissions Error - user 'edge_user' does not have POST /api/v1/users permissions"}

Add a new role

The default Edge Builder roles may not be sufficient to cover the unique requirements of your team. The sections covers how to create your own, customisable roles. As an example, you will create a role for managing App Definitions.

Log-in as the admin user:

edgebuilder-cli user login -u iotech -p EdgeBuilder123 -c "http://192.168.56.10:8085"

Create the role with a suitable name and description (both fields required), for example:

edgebuilder-cli role add --role AppDefRole --description "Role for managing app defnitions"

The response is similar to the following:

INFO: Role(s) created:
+------------+--------------------------------------+
| NAME       | ID                                   |
+------------+--------------------------------------+
| AppDefRole | e5514574-5f72-42c3-8960-8be8c223c0ad |
+------------+--------------------------------------+
INFO: Viewing 1 result(s)

Add permissions to role(s)

To grant permissions to the new role, collect the permission IDs with the permission view command. You can view all permissions relating to app definitions using a wildcard in the argument of the --path flag:
```
edgebuilder-cli permission view --path "/api/v1/app_definitions*"
```
The permissions below define the actions of creating, deleting, inspecting and viewing app definitions in Edge Builder.

Note

The permission IDs will differ in your instance of Edge Builder.

Take note of these IDs as these will be used in the next step (copy and paste into a .txt file, for example).

INFO: Finding permissions with path(s): ["/api/v1/app_definitions*"]
INFO: *** Permission View Results ***
+---------------+--------------------------------------+--------+--------------------------------------+
| NAME          | ID                                   | METHOD | PATH                                 |
+---------------+--------------------------------------+--------+--------------------------------------+
| AppDefInspect | 38893ff4-32ed-4678-8700-5ce94868539d | GET    | /api/v1/app_definitions/inspect/{id} |
| AppDefUpdate  | 541d47f9-4b8b-45df-af6b-170c895b9f8a | PATCH  | /api/v1/app_definitions/{id}         |
| AppDefDelete  | 9c043cfa-bdb4-409b-9039-d094ab500221 | DELETE | /api/v1/app_definitions              |
| AppDefCreate  | b1805e3b-c218-46b7-8228-3e6170b3a6f0 | POST   | /api/v1/app_definitions              |
| AppDefList    | df6d7cd2-d758-4c18-88bc-864925a52608 | GET    | /api/v1/app_definitions              |
+---------------+--------------------------------------+--------+--------------------------------------+
INFO: Viewing 5 result(s)

2. Add the permissions to the new role using the role update command with the --add flag. The command takes the role name and list of permission IDs as arguments. For example:

edgebuilder-cli role update --add -r appDefRole -p 38893ff4-32ed-4678-8700-5ce94868539d,541d47f9-4b8b-45df-af6b-170c895b9f8a

The response is similar to the following:

INFO: added 2 permission(s) to role "AppDefRole"

This new role can then be assigned to users to give them AppDefinition permissions.

Verify the permissions have been added to the role using the role inspect command:

edgebuilder-cli role inspect --role AppDefRole

The response is similar to the following:

{
  "CreatedBy": "iotech",
  "Description": "Role for managing app defnitions",
  "ID": "972cfaa6-4def-4f05-97dd-aecf20672c97",
  "ModifiedBy": "iotech",
  "Name": "AppDefRole",
  "Permissions": [
    {
      "CreatedBy": "EdgeBuilder",
      "ID": "38893ff4-32ed-4678-8700-5ce94868539d",
      "Method": "GET",
      "Name": "AppDefInspect",
      "Path": "/api/v1/app_definitions/inspect/{id}",
      "TimestampCreate": 1639570689
    },
    {
      "CreatedBy": "EdgeBuilder",
      "ID": "541d47f9-4b8b-45df-af6b-170c895b9f8a",
      "Method": "PATCH",
      "Name": "AppDefUpdate",
      "Path": "/api/v1/app_definitions/{id}",
      "TimestampCreate": 1639570689
    }
  ],
  "TimestampCreate": 1639574127,
  "TimestampModify": 1639575031
}

Remove permissions from role(s)

To remove permissions from roles, use the role update command with the --remove flag. For example, to remove the DELETE /api/v1/app_definitions permission from AppDefRole, obtain the correct permission and issue the command:

edgebuilder-cli role remove --role AppDefRole

The response is similar to the following

INFO: Processing roles: [AppDefRole]
INFO: Attempting to remove 1 role(s)
INFO: Do you want to continue? (Y/N)
INFO: 1 role(s) removed successfully

User Management

Initialise the Edge Builder server components and CLI

Login as admin user

Add a node

Add a new user to Edge Builder

Assign the user a role

Issue commands as new user

Add a new role

Add permissions to role(s)

Remove permissions from role(s)