.. _users:

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 :ref:`of the respective tool <tools>`.

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 :ref:`access roles <vnx.access_role_e>` and every
access role has a set of :ref:`permissions <pilot.permission_e>`.
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 :ref:`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 :ref:`user objects <vnx.User>`.
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``:

.. code-block:: javascript
	
	{
		"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 :ref:`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 :ref:`Configuration`.


Adding Users
------------

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

.. code-block:: javascript
	
	{
		"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 :ref:`tools`.