Users
=====

nEdge uses the concept of `users` to group devices together.

.. figure:: img/users.png
  :align: center
  :alt: Users View

  User configuration page

Depending on the specific context, the user can be used to either represent an
actual person or a group of people. In an home environment, for example, a user
"mike" could be created to represent a real person. In this case the user will
group Mike's devices together. In a corporate network, however, a user "employee"
would be more appropriate, to group all employees' devices.

In nEdge, the `Not Assigned` user is a special user that groups together all the new devices.
It can be used to define "default" policies to be applied, for example, on unknown devices. This
only works if the captive portal is disabled, otherwise the unassigned devices traffic will
blocked until proper authentication.

User Configuration
------------------

A user configuration includes the following information:

  - A flag which indicates if `Child Safe` is enabled on the user
  - The user policy configuration (fallback policy, total quotas)
  - Per-protocol and per category policies
  - The user routing policy (router mode only)

.. figure:: img/user_config.png
  :align: center
  :alt: User Configuration

  User configuration page

The `Child Safe` option enables child protection for the specified user by blocking
adult web sites. More information about policies can be found on the policies_ section.

Assigning Devices to a User
---------------------------

When creating a user, the *user* and *password* fields will be used as the access
credentials for the captive portal user authentication. After a successful authentication,
the device will be added to the specified user.

.. figure:: img/add_user.png
  :align: center
  :alt: Add a New User

  Add a new user

A device can also be manually assigned to a specific user by entering the device
page in nEdge and selecting a user from the users dropdown.

.. figure:: img/device_assign.png
  :align: center
  :alt: Device Configuration

  Manually assign a device to a user

It is also possible to kick a device out of the captive portal and force a new
authentication by assigning the device to the "Not Assigned" user.

.. _policies: policies.html

.. _programmatic_configuration:

Segmenting the Network
----------------------

Applying policies to individual devices can be difficult on a large or dynamic network.
This could be solved by enabling a `captive portal`_ and enforcing the devices authentication
through it. However, in some cases it is desirable to avoid displaying the captive portal
at all for example for an internal network. In this case, the LAN network should be segmented
by the means of routers and nEdge configured properly to include all the LAN segments via a
network CIDR. Here is an example.

.. figure:: img/segmented_lan_network.png
  :align: center
  :scale: 80%
  :alt: Segmenting LAN Network

  Segmenting LAN Network

In this example, all the devices connected to the Private access point should be able
to access the internet without captive portal authentication, whereas the devices connecting
to the Public access point must be authenticated. By using two routers to segment
the LAN network, it's now possible to identify the devices groups by their network address.
In particular, the private network is identified by the CIDR `192.168.1.0/24` whereas
the public network by `192.168.0.0/24`. From the users management page is now possible to
create a user "private" and then to add the network `192.168.1.0/24` to its members.

.. figure:: img/adding_network_to_user.png
  :align: center
  :alt: Binding the private LAN to a user

  Binding the private LAN to a user

All the devices with an IP address inside the `192.168.1.0/24` will now be part of the
"simone" user, so no captive portal will be shown for them.

.. note::
  The LAN network now consists of two subnets. In order to correctly identify both
  subnets as local in nEdge, it's necessary to set an appropriate CIDR into the LAN
  network configuration to include both subnets (`/23` in this case).

.. _`captive portal`: captive_portal.html

Programmatic Configuration
--------------------------

Configuration of users, policies, and device-to-user associations/disassociations can also
be done programmatically.


Users and Policies Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Users and policies can be configured programmatically by serving
ntopng Edge a configuration JSON.

The configuration JSON has the following structure

.. code:: json

   {
	  "users": {...},
	  "associations": {...},
   }


There are two keys at the outermost level of the hierarchy, namely,
:code:`users` and :code:`associations`. The former key is used to
create users and specify their policies, whereas the latter is used to
associate devices to the created users.

:code:`users`

The value of this key must be a JSON object with zero or more
key-value pairs:

- Keys are the usernames chosen for the users
- Values are other objects each one carrying the configuration for the user indicated in the key

The following snippet highlights, with an example, a key-value pair
with the configuration for a user named *maina* 

.. code:: json

        "maina" : {
            "full_name": "Maina Bar",
            "password": "ntop0101",
	    "routing_policy": "crew",
            "default_policy": "pass",
            "policies" : {
	       10 : "slow_pass",
               "Facebook": "slower_pass",
               "MyCustomProtocol": "drop",
               "YouTube": "drop"
	     }
	}


The user configuration is a JSON object that must contain the
following keys:

- :code:`full_name`: The full name (e.g., first and last name) of the
  user.
- :code:`password:`: The password the user will have to submit to the
  captive portal in order to access the Internet. This field is not
  used when the captive portal is off.
- :code:`routing_policy`: In case of multi-path routing configuration,
  with multiple WAN interfaces, this represents the name of the Routing
  Policy to be applied to the user.
- :code:`default_policy`: A policy to be used as last resort, that is,
  when no other policy in :code:`policies` matches.
- :code:`policies`: A JSON object containing zero or more key-value
  pairs with applications as keys and policies as
  values. An application key can be specified either using its string
  name as well as using its integer id.

Policies are in a one-to-one relation with the bandwidth classes
explained in bandwidth control. There is also an extra
:code:`drop` policy to block the matching traffic. The four policies available are:

- :code:`pass`
- :code:`slow_pass`
- :code:`slower_pass`
- :code:`drop`


:code:`associations`

The value of this key must be a JSON object with zero or more
key-value pairs:

- Keys are the Mac addresses of the devices that have to be associated
- Values are other objects each one carrying the username the device will
  be associated to.

An example of the associations JSON object is the following

.. code:: json

	  "associations" : { 
	        "DE:AD:BE:EE:FF:FF"  : {"group" : "maina" , "connectivity" : "pass"},
		"11:22:33:44:55:66"  : {"group" : "maina" , "connectivity" : "pass"}
	  }

Here, :code:`group` indicates the username and :code:`connectivity` is
not used and must stay at :code:`pass`. :code:`connectivity` will
become meaningful when creating associations at runtime
as shown in `Runtime Associations Configuration`_.

A full example of a JSON configuration can be found at https://github.com/ntop/ntopng/blob/dev/tools/serve_bridge_config.py


Serving the Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~

The configuration JSON must be served to ntopng Edge using a web
server. ntopng Edge, early during startup, will connect to the webserver to
read the JSON and apply the configuration.

An example of a web server that serves ntopng Edge the JSON configuration
is available at https://github.com/ntop/ntopng/blob/dev/tools/serve_bridge_config.py

.. note::

   To instruct ntopng Edge to fetch the configuration JSON, variable
   :code:`http_bridge_conf_utils.HTTP_BRIDGE_CONFIGURATION_URL` in
   file :code:`http_bridge_conf_utils.lua` must be manually edited to
   specify the server address and port.

   For example, to connect to a server on :code:`localhost` listening
   for connections on port :code:`8000`, the variable has to be
   changed to :code:`http_bridge_conf_utils.HTTP_BRIDGE_CONFIGURATION_URL = "localhost:8000"`.

.. warning::

   During startup, right before applying the JSON configuration, ntopng Edge flushes all the
   existing configured users, their policies, and all the defined applications.

   
Runtime Associations Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Associating members to their host pools is done at runtime using the
ntopng Edge endpoint :code:`/lua/admin/manage_pool_members.lua`.

A valid JSON must be :code:`POST` ed to this endpoint. The JSON is
exactly an :code:`associations` object described in detail above.

For example, using curl, one can associate/disassociate devices to users as follow:

.. code:: bash

	  curl -H "Content-Type: application/json" -X POST -d '{"associations" : { "DE:AD:BE:EE:FF:FF"  : {"group" : "maina" ,  "connectivity" : "pass"}, "AA:BB:CC:DD:EE:FF"  : {"group" : "simon" ,  "connectivity" : "reject"}}}' "http://devel:3000/lua/admin/manage_pool_members.lua"

This time, :code:`connectivity` can take two values:

- :code:`pass` associates a Mac address to the user specified in :code:`group`.
- :code:`reject` disassociates a Mac address from the user specified in :code:`group`.

The endpoint responds with a status for each configured association.
The status can be used to determine if the association/disassociation
has completed successfully.

