Merge stage for release 1.2.0

GufCab · GufCab · commit 78788e35d6b9 · 2022-06-13T10:50:06.000+02:00
diff --git a/source/external-interface-design/external-interface-design.rst b/source/external-interface-design/external-interface-design.rst
@@ -443,6 +443,21 @@ exponential back-off. Or an API exposing all messages which have not
 been acknowledged by the receiver, for a short period of time (for
 instance 3 days like SigFox).
 
+FIWARE
+^^^^^^
+
+FIWARE data target allows users to integrate OS2IoT with any "Powered by FIWARE" platform by enabling the connection to the Context Broker Generic Enabler.
+
+Data are send to the context broker via the :code:`/ngsi-ld/v1/entityOperations/upsert/` operation. 
+
+The output of the payload decoder function needs to comply with the NGSI-LD format as it is sent as a body of the request without any alteration. It should represent an array of objects to be updated.
+
+The context (part of the NGSI-LD standard) can be provided in the request body or can be defined in the data target configuration. In the latter case, it will be included within the headers of the request.
+
+The Fiware data target supports the multitenancy of the Context Broker (but not every context broker supports multitenancy). The name of the tenant can be specified in the configuration. If no value is provided, the default tenant will be used. To specify the tenant OS2IoT is using :code:`NGSILD-Tenant` header.
+
+
+
 Opendata.dk
 ^^^^^^^^^^^
 
diff --git a/source/installation-guide/installation-guide.rst b/source/installation-guide/installation-guide.rst
@@ -219,6 +219,18 @@ OS2IoT-backend takes several environment variables as configuration, if these ar
 +-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
 | BACKEND_BASEURL               | URL for external services to connect to the backend (THIS SHOULD BE CHANGED!)                        | :code:`https://test-os2iot-backend.os2iot.dk`                                           |
 +-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| FRONTEND_BASEURL              | URL for the frontend, used when building email links (THIS SHOULD BE CHANGED!)                       | :code:`http://localhost:8081`                                                           |
++-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| EMAIL_HOST                    | URL for the SMTP server, used when sending emails (THIS SHOULD BE CHANGED!)                          | :code:`"smtp.ethereal.email"`                                                           |
++-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| EMAIL_PORT                    | Port for the email server, used when sending emails (THIS SHOULD BE CHANGED!)                        | :code:`587`                                                                             |
++-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| EMAIL_USER                    | Username for email server authentification, used when sending emails (THIS SHOULD BE CHANGED!)       | :code:`"ara.kertzmann8@ethereal.email"`                                                 |
++-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| EMAIL_PASS                    | Password for email server authentification, used when sending emails (THIS SHOULD BE CHANGED!)       | :code:`"KzRSyYReEygpFPPZdd"`                                                            |
++-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| EMAIL_FROM                    | Email sender address. Either a plain address or a display name and the address (CHANGE IT!)          | :code:`"OS2iot ara.kertzmann8@ethereal.email"`                                          |
++-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
 | KOMBIT_ENTRYPOINT             | The context broker URL for KOMBIT adgangsstyring                                                     | :code:`https://adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/saml2/issue.idp` |
 +-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
 | KOMBIT_CERTIFICATEPRIVATEKEY  | The certificate  private key for KOMBIT adgangsstyring                                               | :code:`null`                                                                            |
@@ -231,6 +243,8 @@ OS2IoT-backend takes several environment variables as configuration, if these ar
 +-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
 | METADATA_SAVED_COUNT          | Maximum number of message metadata to store from an IoT device                                       | :code:`20`                                                                              |
 +-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
+| DEVICE_STATS_INTERVAL_IN_DAYS | How many days back to fetch IoT device statistics                                                    | :code:`29`                                                                              |
++-------------------------------+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
 
 Logs levels
 """""""""""""""
@@ -250,5 +264,5 @@ Defaults are set in :code:`OS2IoT-frontend/src/environments/environment.ts`
 +-------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
 | BASE_URL                      | The Url which users will connect to the backend from. This must be changed for the system to work externally | :code:`http://localhost:3000/api/v1/`                                                   |
 +-------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
-| TABLE_PAGE_SIZE               | Default page size of tables                                                                                  | :code:`20`                                                                              |
+| TABLE_PAGE_SIZE               | Default page size of tables                                                                                  | :code:`25`                                                                              |
 +-------------------------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
diff --git a/source/internal-interface-design/api-key-access.rst b/source/internal-interface-design/api-key-access.rst
@@ -38,6 +38,9 @@ While most of the system is accessible using API key authentication, there are s
 - You cannot manage users nor user groups
 - You cannot manage organizations
 
+You can use an API key to request information necessary for using OS2IoT by using endpoints starting with :code:`/api-key-info`. They require API key authentication.
+For instance, to fetch the organization tied to your API key, you can make a :code:`GET` request to the route which ends with :code:`/api-key-info/organization`.
+
 Currently, there's no expiration date on an API key. It will not expire unless an administrator revokes it on the key management page.
 
 .. |api-key-usage| image:: ./media/api-key-usage.jpg
diff --git a/source/internal-interface-design/internal-interface-design.rst b/source/internal-interface-design/internal-interface-design.rst
@@ -50,31 +50,38 @@ which is explained below.
 
 Authorization (Permissions)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Permissions are given on specific applications to users and API keys through UserGroups. A UserGroup can have multiple permissions. 
 
-There is four levels of permissions in OS2IoT:
-
+There are five levels of permissions in OS2IoT:
 
 - Global Admin
 
- - Can do anything
+ - Can do everything for all organizations and applications
+
+- Application Admin
+
+ - Is scoped to a single organization and zero or more applications
+ - Can access and modify applications and Sigfox devices within the user group in that organization
 
-- Organization Admin 
+- Gateway Admin 
 
  - Is scoped to a single organization
- - Can do anything to that organization
- - Can add new users
+ - Can access and modify gateways within that organization
 
-- Write 
+- User Admin 
 
- - Is scoped to a single organization and zero or more applications
- - Can write/create/delete entities within an organization on certain applications
+ - Is scoped to a single organization
+ - Can access and modify users and permissions within that organization
 
 - Read
 
  - Is scoped to a single organization and zero or more applications
  - Can read (view) entities within certain applications within an organization
 
-The permissions are hieratical, meaning that you implicitly have all lesser permissions than the ones you have explicitly.
-For instance, if a user is an Organization Admin for an Organization, then that user also have the Write and Read permissions.
+Each of the admin permissions is part of a hierarchy with the read permission. If you have an Admin permission within an organization, with zero or more applications, you have an
+implicit read permission within that scope.
+For instance, if a user has Application Admin within an Organization, then that user also has Read permission within it.
+
+Global Admin is at the top of the hierarchy and can thus do what any of the other permissions provide access to.
 
 .. include:: api-key-access.rst
diff --git a/source/iot-data-handling/iot-data-handling.rst b/source/iot-data-handling/iot-data-handling.rst
@@ -70,11 +70,37 @@ Sending to data-targets
 -----------------------
 
 Once the data is transformed/decoded, it can be sent to the intended data-targets.
-OS2iot currently only supports HTTP push as a data-target. But is built to be extended for other kinds of data-targets, e.g. MQTT, PostgreSQL, etc. 
+OS2iot currently supports HTTP push, FIWARE and MQTT as data-targets. It can be extended with other kinds of data-targets, e.g. PostgreSQL, etc. 
 
 The data-targets are configured as part of an application, and therefore can only include data from the IoT-Devices in said application. 
 For each IoT-Device, it is up to the user to select an appropriate payload decoder, to translate the raw payload to JSON.
 
-At the time of writing there is no retry mechanism in OS2iot, rather it uses "fire-and-forget" / "at most once delivery", over HTTP(S).
+At the time of writing, there is no retry mechanism in OS2iot over HTTP(s). It uses a "fire-and-forget" / "at most once delivery" pattern.
+
+MQTT data-target
+^^^^^^^^^^^^^^^^
+
+OS2iot supports publishing data to a broker when it's received using MQTT. MQTT is a standard, lightweight messaging protocol based on the publish/subscribe pattern.
+
+When configuring such a data-target, there's a few terms and keywords to be aware of:
+
+- **QoS**: The QoS (Quality of Service) level determines the guarantee of delivery for a specific message. Different network environments may require different QoS levels.
+  Ideally, the level should be set to match the network reliability and application logic. This is the main point of MQTT.
+  
+  There are 3 QoS levels:
+
+  - 0 (at most once)
+  - 1 (at least once)
+  - 2 (exactly once)
+
+  There are a number of well written articles regarding QoS. One such example is
+  `this blog entry <https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/>`_.
+- **Topic**: The MQTT data-target must be provided a topic with which it can label the data. This is used by the MQTT broker to filter messages from
+  MQTT clients. Here, OS2iot is a client.
+- **Connection authentication**: The most common methods of authentication are username and password and/or client certificates. At the time of writing, username and password
+  authentication is supported, but it can be extended to implement other methods. 
+
+You can read more on MQTT `here <https://mqtt.org/>`_
 
 .. |image2| image:: ./media/image8.png
+   
diff --git a/source/logical-data-model/logical-datamodel.rst b/source/logical-data-model/logical-datamodel.rst
@@ -60,9 +60,10 @@ PermissionLevel
 ~~~~~~~~~~~~~~~
 
 1. Read
-2. Write
-3. OrgAdmin
-4. GlobalAdministrator
+2. OrganizationUserAdmin
+3. OrganizationGatewayAdmin
+4. OrganizationApplicationAdmin
+5. GlobalAdmin
 
 ActionType
 ~~~~~~~~~~~~~~~
@@ -156,11 +157,10 @@ PermissionType
 ~~~~~~~~~~~~~~~~~
 
 1. GlobalAdmin
-2. OrganizationAdmin
-3. Write
-4. Read
-5. OrganizationPermission
-6. OrganizationApplicationPermissions
+2. OrganizationApplicationAdmin
+3. OrganizationGatewayAdmin
+4. OrganizationUserAdmin
+5. Read
 
 SendStatus
 ~~~~~~~~~~~~~~~~~
diff --git a/source/logical-data-model/media/image4.png b/source/logical-data-model/media/image4.png
diff --git a/source/software-architecture/media/image9.png b/source/software-architecture/media/image9.png
diff --git a/source/software-architecture/software-architecture.rst b/source/software-architecture/software-architecture.rst
@@ -200,24 +200,31 @@ Security perspective
 --------------------
 
 This figure shows the classes which make up the permission model for OS2IoT.
-A User has zero or more permission, these permissions are each one of four concrete types:
+A user is part of zero or more permissions (user groups). Each permission has one or more permission types
+which determine what's accessible within the organization. The concrete types are as follows:
 
 1. GlobalAdmin
+   a. Each domain instance of OS2IoT has at least 1 user with this type, which is created on the first startup of the backend.
+   b. Users with the GlobalAdmin role can assign other users to also have the GlobalAdmin role
 
-2. OrganizationAdmin
+2. OrganizationApplicationAdmin
    
    a. This relates to a single organization
+   b. This relates to a list of users within that organization. Access is granted to parts of the system requiring this type
 
-3. Write
+3. OrganizationGatewayAdmin
    
    a. This relates to a single organization
+   b. This relates to a list of users within that organization. Access is granted to parts of the system requiring this type
+
+4. OrganizationUserAdmin
    
-   b. This relates to a list of applications within that organization
+   a. This relates to a single organization
+   b. This relates to a list of users within that organization. Access is granted to parts of the system requiring this type
 
-4. Read
+5. Read
 
    a. This relates to a single organization
-
    b. This relates to a list of applications within that organization
 
 
@@ -254,20 +261,21 @@ Authorization
 ^^^^^^^^^^^^^
 
 By default, a user does not have access to data in OS2iot. A global
-admin or Organization admin must manually give the user permissions to
+admin or User admin must manually give the user permissions to
 organizations or applications.
 
 User permissions
 ^^^^^^^^^^^^^^^^
 
-================== ==================== =======================================================
-User role          System name          Permissions
-================== ==================== =======================================================
-Global admin       Globaladmin          Super user, CRUD everything within the domain
-Organization admin Orgadmin             Manage permissions for an organization and its applications
-Write access       Write                Create, modify and delete objects within an application
-Read access        Read                 Read all data within an application.
-================== ==================== =======================================================
+=================== ============================= ========================================================================
+User role           System name                   Permissions
+=================== ============================= ========================================================================
+Global admin        GlobalAdmin                   Super user, CRUD everything within the domain
+Application admin   OrganizationApplicationAdmin  Access and modify applications, DeviceModels and IoT devices within an organization
+Gateway admin       OrganizationGatewayAdmin      CRUD gateways within an organization
+User admin          OrganizationUserAdmin         CRUD users and permissions within an organization
+Read access         Read                          Read all data within an application.
+=================== ============================= ========================================================================
 
 Web application security
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -344,6 +352,10 @@ Data target security
 
 It is the responsibility of the users of OS2iot and administrators of the data targets to ensure data is encrypted during transmission using e.g. TLS. This section describes the available authentication options in OS2iot.
 
-HTTP PUSH
+HTTP PUSH 
+^^^^^^^^^^^^
+OS2iot supports using a HTTP "Authorization" header or HTTP basic authentication
+
+FIWARE 
 ^^^^^^^^^^^^
 OS2iot supports using a HTTP "Authorization" header or HTTP basic authentication
diff --git a/source/user-interface-design/ui-design.rst b/source/user-interface-design/ui-design.rst
