docs/security/security.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 Security
   5 ========
   6
   7 .. contents:: Table of Contents
   8
   9 Roles and Permissions
  10 ---------------------
  11
  12 | Roles and permissions for DMaaP BC API are configured in connected AAF instance if ``UseAAF`` flag is set.
  13 | The roles and permissions are being provisioned to AAF instance during DMaaP BC instance initialization phase only when AAF is in use.
  14 | The default namespace in AAF for storing Bus Controller API roles and permissions is ``org.onap.dmaap-bc.api``.
  15 | Separate permission is created for every HTTP method on each DMaaP BC REST api endpoint.
  16 | Refer to :doc:`DMaaP Bus Controller REST API<../../../../dmaap/dbcapi.git/docs/api>` for comprehensive api information.
  17 | Default name for DMaaP instance in ONAP is ``mr`` which is reflected in instance part of every created permission under DMaaP BC API.
  18 | Exception of above rule is for ``/dmaap`` endpoint where additionally set of permissions for ``boot`` instance is defined:
  19
  20 .. code-block:: bash
  21
  22     org.onap.dmaap-bc.api.dmaap|boot|DELETE
  23     org.onap.dmaap-bc.api.dmaap|boot|GET
  24     org.onap.dmaap-bc.api.dmaap|boot|POST
  25     org.onap.dmaap-bc.api.dmaap|boot|PUT
  26
  27 | 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.
  28
  29 | DMaaP BC api permissions are distributed between several predefined roles:
  30
  31 .. code-block:: bash
  32
  33     org.onap.dmaap-bc.api.Controller
  34     org.onap.dmaap-bc.api.Inventory
  35     org.onap.dmaap-bc.api.Metrics
  36     org.onap.dmaap-bc.api.Orchestrator
  37     org.onap.dmaap-bc.api.PortalUser
  38
  39 **Predefined roles brief description:**
  40     - **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.
  41     - **Inventory** - role defined for functions which require ReadOnly access to the resources provided on DMaaP BC api.
  42     - **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.
  43     - **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.
  44     - **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.
  45
  46 Bus Controller API security options
  47 -----------------------------------
  48
  49 | There are three main properties in ``dmaapbc.properties`` responsible for configuring DMaaP BC API security option.
  50 | These are ``enableCADI, useAAF, ApiPermission.Class``. Below table describes purpose of each property:
  51
  52 +---------------------+------------------------------------------------------+---------------------------------------------------+
  53 | Property            | Values                                               | Description                                       |
  54 +=====================+======================================================+===================================================+
  55 |enableCADI           | true/false                                           | If set to true CADI filter is enabled on          |
  56 |                     |                                                      | BC REST api and authorization is performed        |
  57 |                     |                                                      | through connected AAF instance.                   |
  58 |                     |                                                      | Otherwise legacy authorization mechanism is       |
  59 |                     |                                                      | used, which depends on api policy defined         |
  60 |                     |                                                      | with ApiPermission.Class property setting.        |
  61 +---------------------+------------------------------------------------------+---------------------------------------------------+
  62 |useAAF               | true/false                                           | The purpose of this flag is to configure if       |
  63 |                     |                                                      | specific namespaces, roles, and permissions       |
  64 |                     |                                                      | should be created in AAF instance when            |
  65 |                     |                                                      | calling some of DMaaP BC api endpoints.           |
  66 |                     |                                                      | Setting it to true will cause automatic           |
  67 |                     |                                                      | operation in AAF:                                 |
  68 |                     |                                                      |                                                   |
  69 |                     |                                                      | - create set of BC API permissions and assign it  |
  70 |                     |                                                      |   to predefined roles during DMaaP instance init  |
  71 |                     |                                                      | - create topic namespace, permissions and roles   |
  72 |                     |                                                      |   when secure topic is created using topics       |
  73 |                     |                                                      |   endpoint                                        |
  74 |                     |                                                      | - assign mr client to specified role in AAF when  |
  75 |                     |                                                      |   adding new client for the topic using           |
  76 |                     |                                                      |   ``mr_clients`` endpoint and clientRole defined  |
  77 |                     |                                                      |   in request                                      |
  78 +---------------------+------------------------------------------------------+---------------------------------------------------+
  79 |ApiPermission.Class  | - org.onap.dmaap.dbcapi.authentication.AllowAll      | when CADI filter is not in use, API security is   |
  80 |                     | - org.onap.dmaap.dbcapi.authentication.AafLurAndFish | fulfilled with policy defined by class given in   |
  81 |                     |                                                      | this property. Currently available options are:   |
  82 |                     |                                                      |                                                   |
  83 |                     |                                                      | - AllowAll - authentication and authorization is  |
  84 |                     |                                                      |   skipped, everyone can invoke any method from BC |
  85 |                     |                                                      |   API                                             |
  86 |                     |                                                      | - AafLurAndFish - authentication and authorization|
  87 |                     |                                                      |   is performed with direct call to AAF instance   |
  88 |                     |                                                      |                                                   |
  89 |                     |                                                      | This property allows to define custom policy,     |
  90 |                     |                                                      | for example to external authorization system      |
  91 |                     |                                                      | by implementing ``ApiAuthorizationCheckInterface``|
  92 |                     |                                                      |                                                   |
  93 +---------------------+------------------------------------------------------+---------------------------------------------------+
  94
  95 .. note::
  96    | When CADI filter is in use it caches internally authorization information for the identities calling BC api by default for 10 minutes.
  97    | It can have negative impact on the functions which needs to call the api several times and use newly created permissions in next call.
  98    | CADI cache time can be changed by setting ``aaf_user_expires`` property (value in ms) in DMaaP BC ``cadi.properties`` file.
  99    | However the lowest achievable cache expiration time is 1 min due to internal CADI framework logic.
 100
 101 **Security properties combination and its implications**
 102
 103 .. note::
 104    | DMaaP-MR references in below table are used only to describe security Use Case between DMaaP internal components.
 105    | To set-up DMaaP-MR security options properly, please refer DMaaP Message Router documentation.
 106    | Each properties combination takes effect only on DMaaP BC API security.
 107
 108 +-------------------------------+----------------------------------------------+--------------------------------+
 109 | Properties combination        | Security result                              | Use Case                       |
 110 +===============================+==============================================+================================+
 111 | | enableCADI = true           | | AAF is in use for DMaaP-BC and DMaaP-MR    | | DMaaP-BC - secured with AAF  |
 112 | | useAAF = true               |   can also rely on AAF.                      | | DMaaP-MR - secured with AAF  |
 113 | | ApiPermission.Class N/A     | | CADI filter is in use, authorization data  |                                |
 114 |                               |   caching is in use, function can authorize  |                                |
 115 |                               |   using x509 certificate or Basic Auth.      |                                |
 116 +-------------------------------+----------------------------------------------+--------------------------------+
 117 | | enableCADI = true           | | AAF is not in use for resources            | | DMaaP-BC - secured with AAF  |
 118 | | useAAF = false              |   configuration.                             | | DMaaP-MR - unsecured         |
 119 | | ApiPermission.Class N/A     | | CADI filter is in use, authorization data  |                                |
 120 |                               |   caching is in use, function can authorize  |                                |
 121 |                               |   using x509 certificate or Basic Auth.      |                                |
 122 +-------------------------------+----------------------------------------------+--------------------------------+
 123 | | enableCADI = false          | | AAF is in use for DMaaP-BC and DMaaP-MR    | | DMaaP-BC - secured with AAF  |
 124 | | useAAF = true               |   can also rely on AAF.                      | | DMaaP-MR - secured with AAF  |
 125 | | ApiPermission.Class =       | | Legacy authorization is in use, no caching |                                |
 126 |   <pckg>.AafLurAndFish        |   for authorization data, function can       |                                |
 127 |                               |   authorize using Basic Auth only.           |                                |
 128 +-------------------------------+----------------------------------------------+--------------------------------+
 129 | | enableCADI = false          | | AAF is not in use for resources            | | DMaaP-BC - secured with AAF  |
 130 | | useAAF = false              |   configuration.                             | | DMaaP-MR - unsecured         |
 131 | | ApiPermission.Class =       | | Legacy authorization is in use, no caching |                                |
 132 |   <pckg>.AafLurAndFish        |   for authorization data, function can       |                                |
 133 |                               |   authorize using Basic Auth only.           |                                |
 134 +-------------------------------+----------------------------------------------+--------------------------------+
 135 | | enableCADI = false          | | AAF is in use for DMaaP-BC resources and   | | DMaaP-BC - unsecured         |
 136 | | useAAF = true               |   DMaaP-MR can also rely on AAF.             | | DMaaP-MR - secured with AAF  |
 137 | | ApiPermission.Class =       | | No authentication and authorization is     |                                |
 138 |   <pckg>.AllowAll             |   performed on DMaaP BC REST api             |                                |
 139 +-------------------------------+----------------------------------------------+--------------------------------+
 140 | | enableCADI = false          | | AAF is not in use for resources            | | DMaaP-BC - unsecured         |
 141 | | useAAF = false              |   configuration.                             | | DMaaP-MR - unsecured         |
 142 | | ApiPermission.Class =       | | No authentication and authorization is     |                                |
 143 |   <pckg>.AllowAll             |   performed on DMaaP BC REST api             |                                |
 144 +-------------------------------+----------------------------------------------+--------------------------------+
 145
 146 SSL DMaaP Certificates and Configuration
 147 ----------------------------------------
 148
 149 Configuration related to ssl can be found in the ``dmaapbc.properties``.
 150 File is located in the ``/opt/app/dmaapbc/etc`` on the dmaap-bc pod. Directory contains also truststore and keystore files used in the ssl setup.
 151 Each change in the configuration file requires restart of the application container
 152
 153 .. code-block:: bash
 154
 155     #
 156     #   Allow http access to API
 157     #
 158     HttpAllowed:        true
 159     #
 160     #   The port number for http as seen within the server
 161     #
 162     IntHttpPort:        8080
 163     #
 164     #   The port number for https as seen within the server
 165     #   Set to 0 if no certificate is available yet...
 166     #
 167     IntHttpsPort:       8443
 168     #
 169     #   The external port number for https taking port mapping into account
 170     #
 171     ExtHttpsPort:       443
 172     #
 173     #   The type of keystore for https
 174     #
 175     KeyStoreType:       jks
 176     #
 177     #   The path to the keystore for https
 178     #
 179     KeyStoreFile:       etc/keystore
 180     #
 181     #   The password for the https keystore
 182     #
 183     KeyStorePassword:   <keystore_password>
 184     #
 185     #   The password for the private key in the https keystore
 186     #
 187     KeyPassword:        <key_password>
 188     #
 189     #   The type of truststore for https
 190     #
 191     TrustStoreType:     jks
 192     #
 193     #   The path to the truststore for https
 194     #
 195     TrustStoreFile:     etc/org.onap.dmaap-bc.trust.jks
 196     #
 197     #   The password for the https truststore
 198     #
 199     TrustStorePassword: <truststore_password>
 200
 201
 202 AAF configuration
 203 -----------------
 204
 205 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.
 206 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).
 207 This file is one of the AAF configuration files enabling authentication and authorization for DMaaP BC REST API.
 208
 209 .. code-block:: bash
 210
 211     #################
 212     # AAF Properties:
 213     UseAAF: true
 214
 215     #################
 216     #
 217     # path to cadi.properties
 218     #
 219     cadi.properties: /opt/app/osaaf/local/org.onap.dmaap-bc.props
 220
 221
 222 Complete AAF configuration consist of following files:
 223     - org.onap.dmaap-bc.props - main configuration file
 224     - org.onap.dmaap-bc.location.props - geographic coordinates of the application
 225     - org.onap.dmaap-bc.cred.props - properties related to credentials, keystore and truststore
 226     - org.onap.dmaap-bc.keyfile - keyfile
 227     - org.onap.dmaap-bc.p12 - keystore
 228     - org.onap.dmaap-bc.trust.jks - truststore
 229
 230
 231 | All listed files are located in the ``/opt/app/dmaapbc/etc`` directory.
 232 | File ``org.onap.dmaap-bc.props`` links together all property files by defining them in the ``cadi_prop_files`` property.
 233 | By default all paths to other AAF related configuration points to ``/opt/app/osaaf/local/`` directory.
 234 | This directory is default location that can be changed during generation of configuration files in the AAF application.
 235 | In order to not duplicate mentioned files on the dmaap-bc pod following symbolic link is created in the filesystem:
 236
 237 .. code-block:: bash
 238
 239     ln -s /opt/app/dmaapbc/etc /opt/app/osaaf/local
 240
 241
 242 User configured and used in DMaaP BC
 243 ------------------------------------
 244
 245 dmaap-bc@dmaap-bc.onap.org
 246 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 247
 248 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
 249 perform an action.
 250
 251
 252 AAF Permissions
 253 +++++++++++++++
 254
 255 .. code-block:: bash
 256
 257     List Permissions by User[dmaap-bc@dmaap-bc.onap.org]
 258     --------------------------------------------------------------------------------
 259     PERM Type                      Instance                       Action
 260     --------------------------------------------------------------------------------
 261     org.onap.dmaap-bc.api.access   *                              read
 262     org.onap.dmaap-bc.certman      local                          request,ignoreIPs,showpass
 263     org.onap.dmaap-dr.feed         *                              *
 264     org.onap.dmaap-dr.sub          *                              *
 265     org.onap.dmaap.mr.access       *                              *
 266     org.onap.dmaap.mr.topic        *                              *
 267     org.onap.dmaap.mr.topic        *                              view
 268     org.onap.dmaap.mr.topicFactory :org.onap.dmaap.mr.topic:org.onap.dmaap.mr create,destroy
 269
 270
 271 dmaap-bc-topic-mgr@dmaap-bc-topic-mgr.onap.org
 272 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 273
 274 When ``UseAAF`` is set to true then creating topic also will create required perms in AAF. The perms will be created in ``org.onap.dmaap.mr`` namespace.
 275 User ``dmaap-bc-topic-mgr`` is used in the process of creating such permissions.
 276
 277 **Example:**
 278     Topic name:
 279         aSimpleTopic
 280
 281     Permissions
 282         | org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|pub
 283         | org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|sub
 284         | org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|view
 285
 286
 287 AAF Permissions
 288 +++++++++++++++
 289
 290 .. code-block:: bash
 291
 292     List Permissions by User[dmaap-bc-topic-mgr@dmaap-bc-topic-mgr.onap.org]
 293     ---------------------------------------------------------------------------------------
 294     PERM Type                                  Instance                       Action
 295     ---------------------------------------------------------------------------------------
 296     org.onap.dmaap-dr.feed                     *                              *
 297     org.onap.dmaap-dr.sub                      *                              *
 298     org.onap.dmaap.mr.PNF_READY.access         *                              *
 299     org.onap.dmaap.mr.PNF_REGISTRATION.access  *                              *
 300     org.onap.dmaap.mr.access                   *                              *
 301     org.onap.dmaap.mr.dgl_ready.access         *                              *
 302     org.onap.dmaap.mr.mirrormaker              *                              admin
 303     org.onap.dmaap.mr.mirrormaker              *                              user
 304     org.onap.dmaap.mr.topic                    *                              view
 305     org.onap.dmaap.mr.topic        :topic.org.onap.dmaap.mr.mirrormakeragent pub
 306     org.onap.dmaap.mr.topic        :topic.org.onap.dmaap.mr.mirrormakeragent sub
 307     org.onap.dmaap.mr.topicFactory :org.onap.dmaap.mr.topic:org.onap.dmaap.mr create
 308     org.onap.dmaap.mr.topicFactory :org.onap.dmaap.mr.topic:org.onap.dmaap.mr destroy
 309
 310
 311 aaf_admin@people.osaaf.org
 312 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 313
 314 This user is used in the process of the post-installation during which appropriate namespaces and permissions are created in AAF.
 315
 316
 317