Merge pull request #88 from jembi/TB-79-update-documentation

TB - 79 Update documentation for kafka and authentication changes

docs/api/audits/create.md

@@ -25,6 +25,8 @@ Payload: JSON object of the audit record
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 <Tabs
   defaultValue="lang"
   values={[

docs/api/audits/read.md

@@ -31,6 +31,8 @@ Endpoint: {openhim_url}:8080/audits/:auditId
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.
 
 <Tabs

docs/api/certificates/create.md

@@ -26,6 +26,10 @@ Endpoint: {openhim_url}:8080/keystore/key
 Payload: JSON object with the key
 ```
 
+## Examples
+
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 ### Key Example
 
 <Tabs

docs/api/certificates/delete.md

@@ -25,6 +25,8 @@ Endpoint: {openhim_url}:8080/keystore/ca/:certificateId
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.
 
 <Tabs

docs/api/certificates/read.md

@@ -45,6 +45,8 @@ Endpoint: {openhim_url}:8080/keystore/validity
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.
 
 <Tabs

docs/api/channels/create.md

@@ -26,6 +26,8 @@ Payload: JSON object of the channel record
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 <Tabs
   defaultValue="lang"
   values={[
@@ -161,4 +163,4 @@ Payload: JSON object of the channel record
   ```
 
 </TabItem>
-</Tabs>
+</Tabs>

docs/api/channels/delete.md

@@ -24,6 +24,8 @@ Endpoint: {openhim_url}:8080/channels/:channelId
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API. 
 
 <Tabs

docs/api/channels/polling-trigger.md

@@ -28,6 +28,8 @@ Endpoint: {openhim_url}:8080/channels/:channelId/trigger
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API. 
 
 <Tabs

docs/api/channels/read.md

@@ -31,6 +31,8 @@ Endpoint: {openhim_url}:8080/channels/:channelId
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API. 
 
 <Tabs

docs/api/channels/update.md

@@ -24,6 +24,8 @@ Payload: JSON object of the channel record
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 <Tabs
   defaultValue="lang"
   values={[

docs/api/clients/create.md

@@ -26,6 +26,8 @@ Payload: JSON object of the client record
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 <Tabs
   defaultValue="lang"
   values={[

docs/api/clients/delete.md

@@ -24,6 +24,8 @@ Endpoint: {openhim_url}:8080/clients/:clientId
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.
 
 <Tabs

docs/api/clients/read.md

@@ -40,6 +40,8 @@ Endpoint: {openhim_url}:8080/clients/domain/:clientDomain
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.
 
 <Tabs

docs/api/clients/update.md

@@ -26,6 +26,8 @@ Payload: JSON object of the client record
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 <Tabs
   defaultValue="lang"
   values={[

docs/api/contacts-group/create.md

@@ -25,6 +25,8 @@ Payload: JSON object of the contact group record
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 <Tabs
   defaultValue="lang"
   values={[

docs/api/contacts-group/delete.md

@@ -24,6 +24,8 @@ Endpoint: {openhim_url}:8080/groups/:groupId
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.
 
 <Tabs

docs/api/contacts-group/read.md

@@ -31,6 +31,8 @@ Endpoint: {openhim_url}:8080/groups/:groupId
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.
 
 <Tabs

docs/api/contacts-group/update.md

@@ -25,6 +25,8 @@ Payload: JSON object of the contact group record
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 <Tabs
   defaultValue="lang"
   values={[

docs/api/import-export/create.md

@@ -27,6 +27,8 @@ Payload: JSON object of the metadata record
 
 ### Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 <Tabs
   defaultValue="lang"
   values={[

docs/api/import-export/read.md

@@ -25,6 +25,8 @@ Endpoint: {openhim_url}:8080/metadata
 
 ### Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.
 
 <Tabs

docs/api/introduction/authentication.md

@@ -11,14 +11,142 @@ description: Authentication for the OpenHIM API calls
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import useBaseUrl from '@docusaurus/useBaseUrl';
 
-## Construct authentication headers
+We have four types of user authentication in Openhim: Local, Basic, Openid and Token *(deprecated)*, described below.
+
+All of these types will create a session for each authenticated user and will send a response header "Set-Cookie" to authenticate the other incoming requests.
+
+The session will be saved in the "Session" Mongo collection.
+
+The password related fields will be saved in the "Passport" Mongo collection.
+
+Some configurations can be updated according to the use case:
+
+```json
+"api": {
+    // The session secret key used for the hashing of signed cookie (used to detect if the client modified the cookie)
+    // Signed cookie is another cookie of the same name with the .sig suffix appended
+    "sessionKey": "r8q,+&1LM3)CD*zAGpx1xm{NeQhc;#",
+    // The session max age is the session cookie expiration time (in milliseconds)
+    "maxAge": 7200000,
+    // The number of characters that will be used to generate a random salt for the encryption of passwords
+    "salt": 10,
+    // The types of authentication to use for the API
+    // Supported types are "token" and "basic" and "local"
+    // * "local" means through the UI with hitting "/authentication/local" endpoint with username and password, 
+    // this will create a session for the user and set cookies in the browser.
+    // * "basic" means with basic auth either through browser or postman by giving also username and password.
+    // * "openid" means with a third party authentication provider (e.g. keycloak).
+    // * [Deprecated] "token" means that a request should provide in the header an 'auth-token', 'auth-salt' and 'auth-ts' to be authenticated.
+    "authenicationTypes": ["token"],
+    // Openid connect provider configuration needed for the authentication
+    "openid": {
+      // OpenID configuration
+    }
+  }
+```
+
+## Local authentication
+
+This type of authentication uses the local authentication protocol (Local passport module). It is the most widely used way for websites to authenticate users via username
+and/or email as well as a password.
+
+For more information on local authentication in Passport.js, check out: http://passportjs.org/guide/username-password/
+
+### Authentication endpoint
+
+To be authenticated using the local protocol, you can hit this route: 
+
+`POST https://<server>:8080/authenticate/local`
+
+With a body that contains the following user details: 
+```json
+{
+    "username": "<email>",
+    "password": "<password>"
+}
+```
+
+## Basic authentication
+
+This is very similar to the Local authentication, except that it uses the Basic passport module and every request to any endpoint should be authenticated.
+
+For more information on basic authentication in Passport.js, check out: https://www.passportjs.org/packages/passport-http/
+
+If this type of authentication is enabled then you can add this header to your request: 
+
+```json
+"headers": { 
+  "Authorization": "Basic Buffer.from(`${<email>}:${<password>}`).toString('base64');"
+}
+```
+
+## OpenID authentication
+
+This authentication uses OpenID Connect Authentication Protocol, this will require enabling this auth type in the Openhim Core and also providing the necessary configurations.
+
+For more information on OpenID connect Protocol in Passport.js, check out: http://www.passportjs.org/packages/passport-openidconnect/
+
+The image below illustrates the openid authentication flow with Keycloak as an example of identity access manager. 
+
+<img alt="Openid Authentication Flow" src={useBaseUrl('img/auth_openid_flow.png')} />
+
+### OpenID configuration
+
+This configuration should be adapted according to your use case.
+
+```json
+"api": {
+    // The types of authentication to use for the API
+    // Supported types are "token" and "basic" and "local"
+    // * "local" means through the UI with hitting "/authentication/local" endpoint with username and password, 
+    // this will create a session for the user and set cookies in the browser.
+    // * "basic" means with basic auth either through browser or postman by giving also username and password.
+    // * "openid" means with a third party authentication provider (e.g. keycloak).
+    // * [Deprecated] "token" means that a request should provide in the header an 'auth-token', 'auth-salt' and 'auth-ts' to be authenticated.
+    "authenicationTypes": ["openid"],
+    // Openid connect provider configuration needed for the authentication
+    "openid": {
+      // Openid connect provider realm url link
+      "url": "http://localhost:9088/realms/platform-realm",
+      // Callback URL used by openid connect provider (should be the same callback URL specified in realm)
+      "callbackUrl": "http://localhost:9000",
+      // CLient ID specified in the realm
+      "clientId": "openhim-oauth",
+      // Client secret specified in the realm
+      "clientSecret": "tZKfEbWf0Ka5HBNZwFrdSyQH2xT1sNMR",
+      // Scopes to be requested from Openid connect provider
+      "scope": "openid email profile offline_access roles"
+    }
+  }
+```
+
+### Authentication endpoint
+
+To be authenticated using OpenID, you can hit this route: 
+
+`POST https://<server>:8080/authenticate/openid`
+
+With a body that contains:
+
+```json
+{ 
+  "code": "<code>", 
+  "sessionState": "<session_state>", 
+  "state":" <state>"
+}
+```
+
+## Token authentication [DEPRECATED]
+
+### Construct authentication headers
 
 Each and every API call that is made to the OpenHIM has to be authenticated. The authentication mechanism that is used can be fairly complex to work with however it provides decent security.
 
 The authentication mechanism is based on <http://stackoverflow.com/a/9387289/588776>.
 
-## Initial authentication notification
+### Initial authentication notification
 
 The user notifies the API that it wants to use its authenticated service:
 
@@ -40,7 +168,7 @@ The server will respond with the salt that was used to calculate the clients pas
 
 You must calculate a passwordhash using the received salt and the supplied user password. `passwordhash = (sha512(salt + password))`
 
-## For subsequent requests to the API
+### For subsequent requests to the API
 
 For every request you must add the following additional HTTP headers to the request:
 
@@ -60,6 +188,8 @@ If these 2 conditions true the request is allowed.
 
 ## Examples
 
+### Token authentication
+
 Below are a few examples of how to achieve the correct request headers to authenticate to the OpenHIM API
 
 <Tabs

docs/api/logs/read.md

@@ -34,6 +34,8 @@ The following filters are available:
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.
 
 <Tabs

docs/api/mediators/create.md

@@ -23,6 +23,10 @@ Endpoint: {openhim_url}:8080/mediators
 Payload: JSON object of the mediator
 ```
 
+## Examples 
+
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 ## Adding Mediator Example
 
 <Tabs

docs/api/mediators/delete.md

@@ -24,6 +24,8 @@ Endpoint: {openhim_url}:8080/mediators/:urn
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.
 
 <Tabs

docs/api/mediators/read.md

@@ -31,6 +31,8 @@ Endpoint: {openhim_url}:8080/mediators/:urn
 
 ## Example
 
+***Note:*** *In the examples below, we are using the token authentication type to authenticate requests*
+
 Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.
 
 <Tabs