Merge pull request #23 from OS2iot/feature/1240_api-key-access

AramAlsabti · web-flow · commit de1fd8d35e43 · 2022-01-31T10:00:50.000+01:00
Update API key documentation
diff --git a/source/contents.rst b/source/contents.rst
@@ -17,7 +17,6 @@
    iot-data-handling/iot-data-handling.rst
    downlink-helpers/downlink-helpers.rst
    kombit-adgangsstyring/kombit-adgangsstyring.rst
-   api-key-access/api-key-access.rst
    audit-log/audit-log.rst
    testing/testing.rst
    exit-strategy/exit-strategy.rst
diff --git a/source/internal-interface-design/api-key-access.rst b/source/internal-interface-design/api-key-access.rst
@@ -1,17 +1,17 @@
 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.
 
@@ -31,7 +31,7 @@ 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
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/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'
