Merge pull request #24 from OS2iot/stage

GufCab · web-flow · commit b0b025b16adb · 2022-02-22T12:15:27.000+01:00
Merge stage prior to release v.1.1.0
diff --git a/requirements.txt b/requirements.txt
@@ -1,3 +1,3 @@
-Sphinx==3.3.1
-sphinx-rtd-theme==0.5.0
-sphinx-autobuild==2020.9.1
+Sphinx==4.3.2
+sphinx-rtd-theme==1.0.0
+sphinx-autobuild==2021.3.14
diff --git a/source/contents.rst b/source/contents.rst
@@ -13,6 +13,7 @@
    external-interface-design/external-interface-design.rst
    software-architecture/software-architecture.rst
    payload-decoders/payload-decoders.rst
+   multicast/multicast.rst
    iot-data-handling/iot-data-handling.rst
    downlink-helpers/downlink-helpers.rst
    kombit-adgangsstyring/kombit-adgangsstyring.rst
diff --git a/source/internal-interface-design/api-key-access.rst b/source/internal-interface-design/api-key-access.rst
@@ -0,0 +1,43 @@
+API key access
+----------------
+
+OS2IoT supports API key authentification. This allows external clients to use the system without the need of a browser or a user.
+
+Configuration
+^^^^^^^^^^^^^
+
+In order to use this type of authentication, an administrator must create an API key with one or more user groups.
+This can be done on the portal through the API key management pages. It can be accessed through the menu.
+
+
+Usage
+^^^^^
+With an API key, you can fetch and manage data in your OS2IoT system just as well as if you were a user on the browser.
+What you can access and manage is limited by the user group (-s) tied to the API key.
+
+With that in mind, let's dive into using an API key. Let's make a few assumptions:
+
+- We have an API key with the value :code:`00000000-abcd-ef00-0000-012345678901`
+- This API key is tied to a user group with Read priviliges to an organization and all its applications
+- There exists a :code:`GET` endpoint for fetching applications. The route ends with :code:`/application`
+
+There's a broad variety of applications, terminals etc. which can perform HTTP requests. To authenticate this request
+with the API key, you must provide it as the header "x-api-key". Below, a screenshot is shown of how this is done in Postman.
+
+|api-key-usage|
+
+The bottom half of the screenshot is the response. The request was limited to 2 applications using the :code:`limit` query parameter.
+As seen, the backend responded with 2 (collapsed) applications.
+
+
+Limitations
+^^^^^^^^^^^
+While most of the system is accessible using API key authentication, there are some security limitations, however:
+
+- You cannot manage your API key or someone else's
+- You cannot manage users nor user groups
+- You cannot manage organizations
+
+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
@@ -76,3 +76,5 @@ There is four levels of permissions in OS2IoT:
 
 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.
+
+.. include:: api-key-access.rst
diff --git a/source/internal-interface-design/media/api-key-usage.jpg b/source/internal-interface-design/media/api-key-usage.jpg
diff --git a/source/kombit-adgangsstyring/kombit-adgangsstyring.rst b/source/kombit-adgangsstyring/kombit-adgangsstyring.rst
@@ -31,7 +31,8 @@ Steps:
     a. Edit the file with a suiteable text editor, such as: VSCode, SublimeText or notepad++.
     b. Replace all instances of :code:`{YOUR_BASE_URL}` with your actual base url, i.e. :code:`test.os2iot.dk`.
     c. Replace all instances of :code:`{YOUR_PUBLIC_KEY_AS_BASE64}` with the base64 encoded part of the certificate (without newlines), i.e. :code:`<X509Certificate>MIIGJDCCBQygAwIBAgIEXd/ZTjANBgkqhkiG9w0BAQsFADBAMQswCQYDVQQGEwJESzESMBAGA1UECgwJVFJVU1QyNDA...=</X509Certificate>`
-    (Tip: `{YOUR_PUBLIC_KEY_AS_BASE64}` is the extracted certificate)
+       
+       (Tip: `{YOUR_PUBLIC_KEY_AS_BASE64}` is the extracted certificate)
     
 
 3. Create an IT-system in KOMBIT adgangsstrying:
diff --git a/source/maintenance-guide/maintenance-guide.rst b/source/maintenance-guide/maintenance-guide.rst
@@ -178,6 +178,37 @@ More information can be found at https://www.chirpstack.io/application-server/in
 
 For installation configuration of Chirpstack see: https://www.chirpstack.io/application-server/install/config/
 
+Migrations
+-----------
+
+This project is using TypeORM migrations when changes are applied to the database. This is recommended by TypeORM when the project is used for production.
+
+Generate migrations
+~~~~~~~~~~~~~~~~~~~
+
+If you modify or adds an entity (or more than one entity) and/or relationships you then need to generate a migration. In the console you write: :code:`npm run generate-migration <your name of the migration>`. Then a migration file 
+will be created in a migration folder. The folder path is specified in :code:`ormconfig.json`. A timestamp will be added to the name to indicate when the migration has been generated. If no changes have been made to the entity classes, no migrations are generated.
+
+Run migrations
+~~~~~~~~~~~~~~~~
+When the project is starting, a new command will be called automatically. This happens every time you run the program because of a prestart script.
+The command is :code:`run-migrations` which runs all the pending generated migrations in the Migrations folder, starting from the oldest migration. 
+In the pending migrations, the :code:`up` block will be executed.
+If there are no pending migrations then no migrations will be run.
+
+It will happen in both debug and prod mode.
+
+Revert migration
+~~~~~~~~~~~~~~~~~~
+If you want to revert a migration later, you can write :code:`npm run typeorm migration:revert`. Then the latest executed migration will be reverted. What happens is that the :code:`down` block in the latest executed migration will be run. 
+You can continue to do this until you reach the desired migration.
+The generated migrations will not be deleted when you are reverting so when you run the project again, the migrations will be run with the :code:`up` block unless you manually deletes them.
+
+Show migration
+~~~~~~~~~~~~~~~~
+If you are in doubt which migrations has been run, then you have the possibility to write :code:`npm run typeorm migration:show` in the console. Then the migrations will be shown in the console,
+and if [X] is marked at a migration it means that it has been run. Otherwise it will be an empty [] which means that is has NOT been run. 
+
 Maintaining the docs
 --------------------
 
diff --git a/source/multicast/media/image1.png b/source/multicast/media/image1.png
diff --git a/source/multicast/multicast.rst b/source/multicast/multicast.rst
@@ -0,0 +1,49 @@
+Multicast
+======================
+
+This chapter describes the multicast-groups.
+
+What can multicast-groups do?
+---------------------------------------------
+Multicast-groups make it possible to send a single downlink payload to a group of devices.
+
+A multicast-group consist of some different properties like multicast-address, session-keys and frame counter. All these properties makes it possible to send only one downlink payload to a group
+of devices instead of sending many downlink payloads to devices one by one.
+
+Multicast-groups does not support Class-A devices, and at this moment, multicast-groups only supports LoRaWAN devices.
+
+Creation in OS2IoT
+-------------------
+If you want to make a multicast-group in OS2IoT you have to go into a specific application and then create the multicast-group from there.
+
+You have to fill out all the required forms, and in the end you can add some devices. It's required that the devices share the same service profile, which is set when you create a LoRaWAN device.
+The multicast-address has to be an 8-character hexadecimal (hex) value, and the network and application session key has to be a 32-character hex value. 
+
+If these requirements are not met, then the multicast-group will not be created.
+
+When you have added the devices that have the same service profile, and have filled out the other forms, then a multicast-group will be created in the database and in Chirpstack.
+
+This sequence diagram describes the flow from the user to the Chirpstack Application Server:
+|image1|
+
+Sending downlink payload
+-------------------------
+
+When the multicast-group is created it's possible to send a downlink payload to the group of devices. This is done by navigating to the details page of the multicast-group, and from here you have to choose a specific port and a payload that you wish to send to the devices in the Multicast-group.
+
+The downlink payload is sent using Chirpstack which also has the multicast-group with the devices from OS2IoT.  
+
+Explanation of properties
+--------------------------
+
+A very short explanation of some of the properties that needs to be fulfilled when creating a multicast-group:
+
+**Multicast address:** An address that defines the multicast-group. Has to be an 8-character hex value.
+
+**Application Session Key:** An application session key used to encrypt the payloads that are send to the multicast-group. Has to be a 32-character hex value.
+
+**Network Session Key:** A network session key is used to compute the message integrity check field of the packets sent to the group. Has to be a 32-character hex value.
+
+----------
+
+.. |image1| image:: ./media/image1.png
diff --git a/source/software-architecture/software-architecture.rst b/source/software-architecture/software-architecture.rst
@@ -51,7 +51,9 @@ Process perspective
 Receive IoT device data
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-See the seperate page: `IoT Data management <../iot-data-handling/iot-data-handling.html`_.
+See the separate page: `IoT Data management`_.
+
+.. _`IoT Data management`: ../iot-data-handling/iot-data-handling.html
 
 Implementation perspective
 --------------------------
@@ -280,9 +282,15 @@ OS2iot REST API security
 
 In order to use the REST API exposed by OS2iot, the user must be authenticated.
 
-Authentication is done using the JWT gained from the :code:`/api/v1/auth/login` endpoint.
+There are two methods of authentication. The first method is done by using the JWT gained from the :code:`/api/v1/auth/login` endpoint.
 The JWT is inserted as a Bearer token in the :code:`Authorization` header of the type :code:`Bearer` as described in RFC 6750, section 2.1.
 
+The second method of authentication involves using an API key generated on the :code:`/api/v1/api-key` endpoint.
+An API key is tied to one or more user groups so the access level reflects what each user group is permitted.
+It can be created by users with an organization administrator role or higher.
+
+The API key is inserted as text in the :code:`X-API-KEY` header. Note that if a valid JWT token is provided, then API key authentication is skipped.
+
 Device security
 ~~~~~~~~~~~~~~~
 
diff --git a/source/user-interface-design/ui-design.rst b/source/user-interface-design/ui-design.rst
@@ -52,7 +52,7 @@ and the content is only boxed in with at .container-fluid class from Bootstrap,
   </div>
 
 Boxed Feature width Layout
-^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 |image2-1|
 
@@ -219,9 +219,10 @@ Global search is used to search across entities in OS2IoT, this is done via free
 When searching in global search, the result is not displayed as in other searches, since in global search, several entities can be searched at the same time. 
 The result is displayed instead on a single page where both the data type and selected data for this data type are displayed. 
 The following entities are searchable via global search:
-    - Applications
-    - IoT-devices
-    - Gateways
+
+-   Applications
+-   IoT-devices
+-   Gateways
 
 |image4-1|
 
@@ -233,11 +234,12 @@ For example, it will i.a. be possible to seek a application on the basis of the
 but not on e.g. the creation date, as searches on dates would otherwise yield too many irrelevant results.
 The picture below shows how the search result is presented.
 |image4-2|
-    1) showing which icon the search has broad, separated into applications, units, and gateways, 
-    2) which type divided into Applications, Generic Http, Lorawan, Sigfox, and Gateways,
-    3) showing the name,
-    4) showing the id,
-    5) showing which organization the item belongs to. 
+
+1)  showing which icon the search has broad, separated into applications, units, and gateways, 
+2)  which type divided into Applications, Generic Http, Lorawan, Sigfox, and Gateways,
+3)  showing the name,
+4)  showing the id,
+5)  showing which organization the item belongs to. 
 
 Help
 ~~~~~~~~~~~~~
diff --git a/source/users-notes/users-notes.rst b/source/users-notes/users-notes.rst
@@ -23,7 +23,7 @@ How to change chirpstacks admin password
 ----------------------------------------
 
 Step-by-step:
-############
+#############
 
 1. Log in to the ChirpStack Application Server web interface using the default credentials
 2. Change the password of the admin user under: 'All users' -> 'admin' -> 'Change Password'
