User Management

The authentication model is based on users who may or may not have permission to perform certain actions. Without authentication, by default, only a limited number of actions are available.

Every user has a name and a password which are used for authentication.

Login

Command line tools usually provide the -u <username> switch to provide a user name. Please refer to the documentation of the respective tool.

Graphical tools usually provide a graphical way of authentication.

Permissions

Most API functions require a certain permission to be executed. If the permission is not held by the user an error is returned or thrown.

Every user has a set of access roles and every access role has a set of permissions. The permissions of a user consist of the permissions of their access roles. Mindful assignment to access roles allows for a fine-grained access control in a multi-user environment.

See vnx.access_role_e for the set of default access roles and their permissions.

Configuration

Available access roles and their sets of permissions can be configured via the config key vnx.authentication.permissions which is an object with access roles (as strings) as keys and a list of permissions (as strings) as values.

Users and their access roles can be configured with the key vnx.authentication.users which is a list of user objects. Note that the passwords for the config map vnx.authentication.passwd are usually kept separately (in a subdirectory) so that they can be protected from reading and writing.

Here is the default configuration config/default/generic/vnx/authentication.json:

{
        "users": [
                {
                        "name": "neo-user",
                        "access_roles": ["USER"]
                },
                {
                        "name": "neo-installer",
                        "access_roles": ["INSTALLER"]
                },
                {
                        "name": "neo-admin",
                        "access_roles": ["INSTALLER", "ADMIN"]
                }
        ],
        "permissions": {
                "OBSERVER": [
                        "READ_CONFIG",
                ],
                "USER": [
                        "pilot.permission_e.MOVE",
                        "pilot.permission_e.CHARGE",
                        "pilot.permission_e.INITIALIZE",
                        "pilot.permission_e.RECORD_DATA",
                        "pilot.permission_e.EXECUTE_SCRIPT",
                        "vnx.addons.permission_e.READ_DIRECTORY",
                        "vnx.addons.permission_e.FILE_DOWNLOAD",
                ],
                "TASK": [
                        "VIEW",
                        "CONST_REQUEST",
                        "pilot.permission_e.MOVE",
                        "pilot.permission_e.CHARGE",
                        "pilot.permission_e.RECORD_DATA",
                        "pilot.permission_e.RELAY_CONTROL",
                        "pilot.permission_e.DISPLAY_CONTROL",
                ],
                "INSTALLER": [
                        "pilot.permission_e.MOVE",
                        "pilot.permission_e.CHARGE",
                        "pilot.permission_e.INITIALIZE",
                        "pilot.permission_e.RECORD_DATA",
                        "pilot.permission_e.REMOTE_CONTROL",
                        "pilot.permission_e.RELAY_CONTROL",
                        "pilot.permission_e.DISPLAY_CONTROL",
                        "pilot.permission_e.CHANGE_GRIDMAP",
                        "pilot.permission_e.CHANGE_ROADMAP",
                        "pilot.permission_e.UPLOAD_SCRIPT",
                        "pilot.permission_e.EXECUTE_SCRIPT",
                        "pilot.permission_e.INTERVENE_SCRIPT",
                        "vnx.addons.permission_e.READ_DIRECTORY",
                        "vnx.addons.permission_e.FILE_DOWNLOAD",
                        "vnx.addons.permission_e.FILE_UPLOAD",
                        "vnx.addons.permission_e.FILE_DELETE",
                ]
        }
}

As can be seen, built-in permissions (of type vnx.permission_e) such as VIEW and READ_CONFIG can be specified without the full namespace. A permission can also be removed by adding a ! in front of the name: !VIEW.

For more information regarding configuration files see Configuration.

Adding Users

To add new users create a config file config/local/vnx/authentication.json:

{
        "users+": [
                {
                        "name": "foo",
                        "access_roles": ["USER", ...]
                },
                ....
        ]
}

By removing the + in users+ you can discard the default users which were set in config/default/generic/vnx/authentication.json.

Passwords

Passwords can be set or changed via the vnxpasswd command line tool, see Tools.