Documentation update

- update for DMaaP BC api security configuration
- minor spelling and formating fixes

Change-Id: I6f985517d5ef486d1bbbd238f64eafc438fd6cdc
Issue-ID: DMAAP-1207
Signed-off-by: Tomek Kaminski <tomasz.kaminski@nokia.com>

7 files changed, 170 insertions, 34 deletions

diff --git a/docs/Installation/Installation.rst b/docs/Installation/Installation.rst
index 6484459..3a8e732 100644
--- a/docs/Installation/Installation.rst
+++ b/docs/Installation/Installation.rst
@@ -32,7 +32,7 @@ However, if some customization is desired, there are places to change behavior:
 
 
 Steps for local development and test
-------------------------
+------------------------------------
 On Intel dev machine, in terminal (> indicates prompt) :
 1) Build buscontroller images
     > git clone https://gerrit.onap.org/r/dmaap/buscontroller
@@ -40,12 +40,12 @@ On Intel dev machine, in terminal (> indicates prompt) :
     > cd buscontroller
     > mvn clean install -Pdocker
         - builds dmaap-bc and dbc-client images
-2) Run tests 
+2) Run tests
     > cd dmaap-bc/src/main/resources/
     > cp docker-databus-controller.conf /var/tmp/
         - set docker preferences/file sharing to access /var/tmp
     - edit docker-compose.yml
-        - remove "nexus3.onap.org:10001/" from dmaap-bc:image: and dbc-client:image: to 
+        - remove "nexus3.onap.org:10001/" from dmaap-bc:image: and dbc-client:image: to
             use local images
     > docker-compose up -d
     - create sample.txt file (as above)(content of file not important)
@@ -58,12 +58,12 @@ On Arm:
     > cd buscontroller
     > mvn clean install -Pdocker  -Ddocker.pull.registry=docker.io
         - ensure we pull Arm version of base image
-2) Run tests 
+2) Run tests
     > cd dmaap-bc/src/main/resources/
     > cp docker-databus-controller.conf /var/tmp/
         - set docker preferences/file sharing to access /var/tmp
     - edit docker-compose.yml
-        - remove "nexus3.onap.org:10001/" from dmaap-bc:image: and dbc-client:image: to 
+        - remove "nexus3.onap.org:10001/" from dmaap-bc:image: and dbc-client:image: to
             use local images
         - replace 'crunchydata/crunchy-postgres:centos7-10.4-2.0.0' with
             multi-platform 'postgres:9.6-alpine' normative image
diff --git a/docs/architecture/architecture.rst b/docs/architecture/architecture.rst
index c148af5..7654513 100644
--- a/docs/architecture/architecture.rst
+++ b/docs/architecture/architecture.rst
@@ -2,11 +2,11 @@
 .. http://creativecommons.org/licenses/by/4.0
 
 Architecture
-==============
+============
 
 
 Capabilities
----------
+------------
 Bus Controller is a RESTful web service used to provision DMaaP topics (on Message Router) and feeds (on Data Router), with associated authorization (on AAF).
 
 Usage Scenarios
@@ -44,5 +44,3 @@ Bus Controller endpoints are used to provision:
         AAF;
         }
     }
- 
-
diff --git a/docs/configuration/configuration.rst b/docs/configuration/configuration.rst
index d8ed089..d85b4dc 100644
--- a/docs/configuration/configuration.rst
+++ b/docs/configuration/configuration.rst
@@ -8,5 +8,4 @@ Refer to README file in buscontroller repo for a list of properties.
 https://gerrit.onap.org/r/gitweb?p=dmaap/buscontroller.git;a=blob;f=README.md
 
 These properties can be modified by changing the resource file in the helm chart prior to deployment.
-oom/kubernetes/dmaap/charts/dmaap-bus-controller/resources/config/dmaapbc.properties  
-
+oom/kubernetes/dmaap/charts/dmaap-bus-controller/resources/config/dmaapbc.properties
diff --git a/docs/index.rst b/docs/index.rst
index 121f062..0fc55d4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,8 +1,8 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0ONAP Component: DMaaP Bus Controller 
+.. http://creativecommons.org/licenses/by/4.0ONAP Component: DMaaP Bus Controller
 
 dmaap/buscontroller
-====================================
+===================
 
 .. toctree::
    :maxdepth: 3
diff --git a/docs/logging/logging.rst b/docs/logging/logging.rst
index e335356..aa6ae57 100644
--- a/docs/logging/logging.rst
+++ b/docs/logging/logging.rst
@@ -1,19 +1,19 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
    .. http://creativecommons.org/licenses/by/4.0
-   
+
 Logging
 =======
-   
+
 .. note::
-   * This section is used to describe the informational or diagnostic messages emitted from 
+   * This section is used to describe the informational or diagnostic messages emitted from
      a software component and the methods or collecting them.
-  
+
    * This section is typically: provided for a platform-component and sdk; and
      referenced in developer and user guides
-  
+
    * This note must be removed after content has been added.
-  
-  
+
+
 Where to Access Information
 ---------------------------
 Bus Controller uses logback framework to generate logs found under logs/ONAP.
diff --git a/docs/release-notes/release-notes.rst b/docs/release-notes/release-notes.rst
index 1ab7d8b..a6859dd 100644
--- a/docs/release-notes/release-notes.rst
+++ b/docs/release-notes/release-notes.rst
@@ -2,7 +2,7 @@
 .. http://creativecommons.org/licenses/by/4.0
 
 Release Notes
-==============
+=============
 
 Version: 1.0.23
 
@@ -21,7 +21,7 @@ Version: 1.0.23
 
 **Security Notes**
 DMAAP code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, items that remain open have been assessed for risk and determined to be false positive. The DMAAP open Critical security vulnerabilities and their risk assessment have been documented as part of the `project <https://wiki.onap.org/pages/viewpage.action?pageId=28379799>`_.
-  
+
 Quick Links:
 - `DMAAP project page <https://wiki.onap.org/display/DW/DMaaP+Planning>`_
 - `Passing Badge information for DMAAP <https://bestpractices.coreinfrastructure.org/en/projects/1751>`_
diff --git a/docs/security/security.rst b/docs/security/security.rst
index 1c11fce..47a1736 100644
--- a/docs/security/security.rst
+++ b/docs/security/security.rst
@@ -2,11 +2,148 @@
 .. http://creativecommons.org/licenses/by/4.0
 
 Security
-=========
+========
 
 .. contents:: Table of Contents
 
-SSL DmaaP Certificates and Configuration
+Roles and Permissions
+---------------------
+
+| Roles and permissions for DMaaP BC API are configured in connected AAF instance if ``UseAAF`` flag is set.
+| The roles and permissions are being provisioned to AAF instance during DMaaP BC instance initialization phase only when AAF is in use.
+| The default namespace in AAF for storing Bus Controller API roles and permissions is ``org.onap.dmaap-bc.api``.
+| Separate permission is created for every HTTP method on each DMaaP BC REST api endpoint.
+| Refer to :doc:`DMaaP Bus Controller REST API<../../../../dmaap/dbcapi.git/docs/api>` for comprehensive api information.
+| Default name for DMaaP instance in ONAP is ``mr`` which is reflected in instance part of every created permission under DMaaP BC API.
+| Exception of above rule is for ``/dmaap`` endpoint where additionally set of permissions for ``boot`` instance is defined:
+
+.. code-block:: bash
+
+    org.onap.dmaap-bc.api.dmaap|boot|DELETE
+    org.onap.dmaap-bc.api.dmaap|boot|GET
+    org.onap.dmaap-bc.api.dmaap|boot|POST
+    org.onap.dmaap-bc.api.dmaap|boot|PUT
+
+| These permissions are needed during DMaaP initialization phase, until real instance is configured. This set of permissions is also provided in AAF instance by default.
+
+| DMaaP BC api permissions are distributed between several predefined roles:
+
+.. code-block:: bash
+
+    org.onap.dmaap-bc.api.Controller
+    org.onap.dmaap-bc.api.Inventory
+    org.onap.dmaap-bc.api.Metrics
+    org.onap.dmaap-bc.api.Orchestrator
+    org.onap.dmaap-bc.api.PortalUser
+
+**Predefined roles brief description:**
+    - **Controller** - contains all permissions to DMaaP BC REST api, and should be assigned to identities which requires full admin rights to DMaaP BC, like ``dmaap-bc`` service identity itself.
+    - **Inventory** - role defined for functions which require ReadOnly access to the resources provided on DMaaP BC api.
+    - **Metrics** - role designed to be used by external function which examines the counts of topics that were replicating between different MR instances. Main permission of this role is to read from DMaaP BC bridge endpoint.
+    - **Orchestrator** - main role containing all permissions, which client micro-service might need. One of the example functions is ``dmaap plugin`` which is part of DCAE. The difference between this and Controller role is that Orchestrator is not responsible for deploying new k8s cluster or a message-router into that cluster, so it has limited, RO access to dmaap and dcaeLocations endpoints.
+    - **PortalUser** - role designed to be used in DMaaP Bus Controller Web App, which is based on the ONAP Portal SDK. If the UI app is deployed and available in ONAP Portal, portal users which will use DMaaP BC Web App shall be assigned to this role.
+
+Bus Controller API security options
+-----------------------------------
+
+| There are three main properties in ``dmaapbc.properties`` responsible for configuring DMaaP BC API security option.
+| These are ``enableCADI, useAAF, ApiPermission.Class``. Below table describes purpose of each property:
+
++---------------------+------------------------------------------------------+---------------------------------------------------+
+| Property            | Values                                               | Description                                       |
++=====================+======================================================+===================================================+
+|enableCADI           | true/false                                           | If set to true CADI filter is enabled on          |
+|                     |                                                      | BC REST api and authorization is performed        |
+|                     |                                                      | through connected AAF instance.                   |
+|                     |                                                      | Otherwise legacy authorization mechanism is       |
+|                     |                                                      | used, which depends on api policy defined         |
+|                     |                                                      | with ApiPermission.Class property setting.        |
++---------------------+------------------------------------------------------+---------------------------------------------------+
+|useAAF               | true/false                                           | The purpose of this flag is to configure if       |
+|                     |                                                      | specific namespaces, roles, and permissions       |
+|                     |                                                      | should be created in AAF instance when            |
+|                     |                                                      | calling some of DMaaP BC api endpoints.           |
+|                     |                                                      | Setting it to true will cause automatic           |
+|                     |                                                      | operation in AAF:                                 |
+|                     |                                                      |                                                   |
+|                     |                                                      | - create set of BC API permissions and assign it  |
+|                     |                                                      |   to predefined roles during DMaaP instance init  |
+|                     |                                                      | - create topic namespace, permissions and roles   |
+|                     |                                                      |   when secure topic is created using topics       |
+|                     |                                                      |   endpoint                                        |
+|                     |                                                      | - assign mr client to specified role in AAF when  |
+|                     |                                                      |   adding new client for the topic using           |
+|                     |                                                      |   ``mr_clients`` endpoint and clientRole defined  |
+|                     |                                                      |   in request                                      |
++---------------------+------------------------------------------------------+---------------------------------------------------+
+|ApiPermission.Class  | - org.onap.dmaap.dbcapi.authentication.AllowAll      | when CADI filter is not in use, API security is   |
+|                     | - org.onap.dmaap.dbcapi.authentication.AafLurAndFish | fulfilled with policy defined by class given in   |
+|                     |                                                      | this property. Currently available options are:   |
+|                     |                                                      |                                                   |
+|                     |                                                      | - AllowAll - authentication and authorization is  |
+|                     |                                                      |   skipped, everyone can invoke any method from BC |
+|                     |                                                      |   API                                             |
+|                     |                                                      | - AafLurAndFish - authentication and authorization|
+|                     |                                                      |   is performed with direct call to AAF instance   |
+|                     |                                                      |                                                   |
+|                     |                                                      | This property allows to define custom policy,     |
+|                     |                                                      | for example to external authorization system      |
+|                     |                                                      | by implementing ``ApiAuthorizationCheckInterface``|
+|                     |                                                      |                                                   |
++---------------------+------------------------------------------------------+---------------------------------------------------+
+
+.. note::
+   | When CADI filter is in use it caches internally authorization information for the identities calling BC api by default for 10 minutes.
+   | It can have negative impact on the functions which needs to call the api several times and use newly created permissions in next call.
+   | CADI cache time can be changed by setting ``aaf_user_expires`` property (value in ms) in DMaaP BC ``cadi.properties`` file.
+   | However the lowest achievable cache expiration time is 1 min due to internal CADI framework logic.
+
+**Security properties combination and its implications**
+
+.. note::
+   | DMaaP-MR references in below table are used only to describe security Use Case between DMaaP internal components.
+   | To set-up DMaaP-MR security options properly, please refer DMaaP Message Router documentation.
+   | Each properties combination takes effect only on DMaaP BC API security.
+
++-------------------------------+----------------------------------------------+--------------------------------+
+| Properties combination        | Security result                              | Use Case                       |
++===============================+==============================================+================================+
+| | enableCADI = true           | | AAF is in use for DMaaP-BC and DMaaP-MR    | | DMaaP-BC - secured with AAF  |
+| | useAAF = true               |   can also rely on AAF.                      | | DMaaP-MR - secured with AAF  |
+| | ApiPermission.Class N/A     | | CADI filter is in use, authorization data  |                                |
+|                               |   caching is in use, function can authorize  |                                |
+|                               |   using x509 certificate or Basic Auth.      |                                |
++-------------------------------+----------------------------------------------+--------------------------------+
+| | enableCADI = true           | | AAF is not in use for resources            | | DMaaP-BC - secured with AAF  |
+| | useAAF = false              |   configuration.                             | | DMaaP-MR - unsecured         |
+| | ApiPermission.Class N/A     | | CADI filter is in use, authorization data  |                                |
+|                               |   caching is in use, function can authorize  |                                |
+|                               |   using x509 certificate or Basic Auth.      |                                |
++-------------------------------+----------------------------------------------+--------------------------------+
+| | enableCADI = false          | | AAF is in use for DMaaP-BC and DMaaP-MR    | | DMaaP-BC - secured with AAF  |
+| | useAAF = true               |   can also rely on AAF.                      | | DMaaP-MR - secured with AAF  |
+| | ApiPermission.Class =       | | Legacy authorization is in use, no caching |                                |
+|   <pckg>.AafLurAndFish        |   for authorization data, function can       |                                |
+|                               |   authorize using Basic Auth only.           |                                |
++-------------------------------+----------------------------------------------+--------------------------------+
+| | enableCADI = false          | | AAF is not in use for resources            | | DMaaP-BC - secured with AAF  |
+| | useAAF = false              |   configuration.                             | | DMaaP-MR - unsecured         |
+| | ApiPermission.Class =       | | Legacy authorization is in use, no caching |                                |
+|   <pckg>.AafLurAndFish        |   for authorization data, function can       |                                |
+|                               |   authorize using Basic Auth only.           |                                |
++-------------------------------+----------------------------------------------+--------------------------------+
+| | enableCADI = false          | | AAF is in use for DMaaP-BC resources and   | | DMaaP-BC - unsecured         |
+| | useAAF = true               |   DMaaP-MR can also rely on AAF.             | | DMaaP-MR - secured with AAF  |
+| | ApiPermission.Class =       | | No authentication and authorization is     |                                |
+|   <pckg>.AllowAll             |   performed on DMaaP BC REST api             |                                |
++-------------------------------+----------------------------------------------+--------------------------------+
+| | enableCADI = false          | | AAF is not in use for resources            | | DMaaP-BC - unsecured         |
+| | useAAF = false              |   configuration.                             | | DMaaP-MR - unsecured         |
+| | ApiPermission.Class =       | | No authentication and authorization is     |                                |
+|   <pckg>.AllowAll             |   performed on DMaaP BC REST api             |                                |
++-------------------------------+----------------------------------------------+--------------------------------+
+
+SSL DMaaP Certificates and Configuration
 ----------------------------------------
 
 Configuration related to ssl can be found in the ``dmaapbc.properties``.
@@ -65,9 +202,9 @@ Each change in the configuration file requires restart of the application contai
 AAF configuration
 -----------------
 
-Usage of AAF can be turned on/off by setting ``UseAAF`` flag to ``true/false`` in the ``dmaapbc.properties`` file. By default AFF usage is turned on.
+Usage of AAF can be turned on/off by setting ``UseAAF`` flag to ``true/false`` in the ``dmaapbc.properties`` file. By default AAF usage is turned on.
 Property ``cadi.properties`` points to absolute path of the property file generated by AAF for the DmaaP BC application (``dmaap-bc@dmaap-bc.onap.org`` user).
-This file is one of the AAF configuration files enabling authentication and authorization for DmaaP BC REST API.
+This file is one of the AAF configuration files enabling authentication and authorization for DMaaP BC REST API.
 
 .. code-block:: bash
 
@@ -91,24 +228,24 @@ Complete AAF configuration consist of following files:
     - org.onap.dmaap-bc.trust.jks - truststore
 
 
-All listed files are located in the ``/opt/app/dmaapbc/etc`` directory.
-File ``org.onap.dmaap-bc.props`` links together all property files by defining them in the ``cadi_prop_files`` property.
-By default all paths to other AAF related configuration points to ``/opt/app/osaaf/local/`` directory.
-This directory is default location that can be changed during generation of configuration files in the AAF application.
-In order to not duplicate mentioned files on the dmaap-bc pod following symbolic link is created in the filesystem:
+| All listed files are located in the ``/opt/app/dmaapbc/etc`` directory.
+| File ``org.onap.dmaap-bc.props`` links together all property files by defining them in the ``cadi_prop_files`` property.
+| By default all paths to other AAF related configuration points to ``/opt/app/osaaf/local/`` directory.
+| This directory is default location that can be changed during generation of configuration files in the AAF application.
+| In order to not duplicate mentioned files on the dmaap-bc pod following symbolic link is created in the filesystem:
 
 .. code-block:: bash
 
     ln -s /opt/app/dmaapbc/etc /opt/app/osaaf/local
 
 
-User configured and used in DmaaP BC
+User configured and used in DMaaP BC
 ------------------------------------
 
 dmaap-bc@dmaap-bc.onap.org
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It is main user for the DmaaP BC application. It has permissions to validate if user accessing DmaaP BC REST api has appropriate permissions to
+It is main user for the DMaaP BC application. It has permissions to validate if user accessing DMaaP BC REST api has appropriate permissions to
 perform an action.
 
 
@@ -142,7 +279,9 @@ User ``dmaap-bc-topic-mgr`` is used in the process of creating such permissions.
         aSimpleTopic
 
     Permissions
-        org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|pub org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|sub org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|view
+        | org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|pub
+        | org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|sub
+        | org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|view
 
 
 AAF Permissions