Documentation update
- document prh authN/authZ feature
- broken linkage corrections
- wrong formatting corrections
Change-Id: Ie9bb86445712185ac4b9aebdbca75c629327d6fa
Issue-ID: DCAEGEN2-960
Signed-off-by: Tomek Kaminski <tomasz.kaminski@nokia.com>
diff --git a/docs/sections/services/prh/architecture.rst b/docs/sections/services/prh/architecture.rst
index c47772a..090c405 100644
--- a/docs/sections/services/prh/architecture.rst
+++ b/docs/sections/services/prh/architecture.rst
@@ -2,13 +2,13 @@
.. http://creativecommons.org/licenses/by/4.0
PRH Architecture
-===================
+================
**PRH** is a new DCAE micro-service which participates in the Physical Network Function Plug and Play (PNF PnP)
procedure. PNF PnP is used to register PNF when it comes online.
PRH Processing Flow
-===================
+-------------------
.. image:: ../../images/prhAlgo.png
diff --git a/docs/sections/services/prh/authorization.rst b/docs/sections/services/prh/authorization.rst
new file mode 100644
index 0000000..fe5ed40
--- /dev/null
+++ b/docs/sections/services/prh/authorization.rst
@@ -0,0 +1,60 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _authorization:
+
+SSL/TLS Authentication & Authorization
+======================================
+
+| PRH does not perform any authorization in AAF, as the only endpoint which is provided by the service is the healthcheck, which is unsecured.
+| For authentication settings there is a possibility to change from default behavior to certificate-based solution independently for DMaaP and AAI communication.
+
+AAI authentication
+^^^^^^^^^^^^^^^^^^
+
+Default
+"""""""
+| By default basic authentication is being used with following credentials:
+| user=AAI
+| password=AAI
+
+Certificate-based
+"""""""""""""""""
+| There is an option to enable certificate-based authentication for PRH towards AAI service calls.
+| To achieve this secure flag needs to be turned on in PRH :ref:`configuration<prh_configuration>` :
+
+.. code-block:: json
+ security.enableAaiCertAuth=true
+
+DMaaP BC authentication
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Default
+"""""""
+| By default basic authentication is being used with following credentials (for both DMaaP consumer and DMaaP publisher endpoints):
+| user=admin
+| password=admin
+
+Certificate-based
+""""""""""""""""""
+| There is an option to enable certificate-based authentication for PRH towards DMaaP Bus Controller service calls.
+| To achieve this secure flag needs to be turned on in PRH :ref:`configuration<prh_configuration>` :
+
+.. code-block:: json
+ --security.enableDmaapCertAuth=true
+
+PRH identity and certificate data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+| PRH is using ``dcae`` identity when certificate-based authentication is turned on.
+| It's the DCAEGEN2 responsibility to generate certificate for dcae identity and provide it to the collector.
+|
+| PRH by default expects that the volume ``tls-info`` is being mounted under path ``/opt/app/prh/etc/cert``.
+| It's the component/collector responsibility to provide necessary inputs in Cloudify blueprint to get the volume mounted.
+| See :doc:`../../tls_enablement` for detailed information.
+|
+| PRH is using four files from ``tls-info`` DCAE volume (``cert.jks, jks.pass, trust.jks, trust.pass``).
+| Refer :ref:`configuration<prh_configuration>` for proper security attributes settings.
+|
+| **IMPORTANT** Even when certificate-based authentication security features are disabled,
+| still all security settings needs to be provided in configuration to make PRH service start smoothly.
+| Security attributes values are not validated in this case, and can point to non-existent data.
diff --git a/docs/sections/services/prh/configuration.rst b/docs/sections/services/prh/configuration.rst
index a36ad95..0e4109c 100644
--- a/docs/sections/services/prh/configuration.rst
+++ b/docs/sections/services/prh/configuration.rst
@@ -1,6 +1,8 @@
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
+.. _prh_configuration:
+
Configuration
=============
@@ -8,46 +10,51 @@
.. code-block:: json
- {
- "dmaap.dmaapProducerConfiguration.dmaapTopicName":"/events/unauthenticated.PNF_READY",
- "dmaap.dmaapConsumerConfiguration.dmaapHostName":"message-router.onap.svc.cluster.local",
- "aai.aaiClientConfiguration.aaiPnfPath":"/network/pnfs/pnf",
- "aai.aaiClientConfiguration.aaiUserPassword":"AAI",
- "dmaap.dmaapConsumerConfiguration.dmaapUserName":"admin",
- "aai.aaiClientConfiguration.aaiBasePath":"/aai/v12",
- "dmaap.dmaapConsumerConfiguration.timeoutMs":-1,
- "dmaap.dmaapProducerConfiguration.dmaapPortNumber":3904,
- "aai.aaiClientConfiguration.aaiHost":"aai.onap.svc.cluster.local",
- "dmaap.dmaapConsumerConfiguration.dmaapUserPassword":"admin",
- "dmaap.dmaapProducerConfiguration.dmaapProtocol":"http",
- "aai.aaiClientConfiguration.aaiIgnoreSslCertificateErrors":true,
- "dmaap.dmaapProducerConfiguration.dmaapContentType":"application/json",
- "dmaap.dmaapConsumerConfiguration.dmaapTopicName":"/events/unauthenticated.VES_PNFREG_OUTPUT",
- "dmaap.dmaapConsumerConfiguration.dmaapPortNumber":3904,
- "dmaap.dmaapConsumerConfiguration.dmaapContentType":"application/json",
- "dmaap.dmaapConsumerConfiguration.messageLimit":-1,
- "dmaap.dmaapConsumerConfiguration.dmaapProtocol":"http",
- "aai.aaiClientConfiguration.aaiUserName":"AAI",
- "dmaap.dmaapConsumerConfiguration.consumerId":"c12",
- "dmaap.dmaapProducerConfiguration.dmaapHostName":"message-router.onap.svc.cluster.local",
- "aai.aaiClientConfiguration.aaiHostPortNumber":8443,
- "dmaap.dmaapConsumerConfiguration.consumerGroup":"OpenDCAE-c12",
- "aai.aaiClientConfiguration.aaiProtocol":"https",
- "dmaap.dmaapProducerConfiguration.dmaapUserName":"admin",
- "dmaap.dmaapProducerConfiguration.dmaapUserPassword":"admin"
- }
-
-
-There are also optional configuration parameters:
-
-.. code-block:: json
-
- "security": {
- "keyFile": "/opt/app/prh/local/org.onap.prh.keyfile",
- "trustStore": "/opt/app/prh/local/org.onap.prh.trust.jks",
- "trustStorePassword": "change it",
- "keyStore": "/opt/app/prh/local/org.onap.prh.p12",
- "keyStorePassword": "change it",
+ {
+ "aai": {
+ "aaiClientConfiguration": {
+ "aaiHost": "aai.onap.svc.cluster.local",
+ "aaiHostPortNumber": 8443,
+ "aaiIgnoreSslCertificateErrors": true,
+ "aaiProtocol": "https",
+ "aaiUserName": "AAI",
+ "aaiUserPassword": "AAI",
+ "aaiBasePath": "/aai/v12",
+ "aaiPnfPath": "/network/pnfs/pnf",
+ }
+ },
+ "dmaap": {
+ "dmaapConsumerConfiguration": {
+ "consumerGroup": "OpenDCAE-c12",
+ "consumerId": "c12",
+ "dmaapContentType": "application/json",
+ "dmaapHostName": "message-router.onap.svc.cluster.local",
+ "dmaapPortNumber": 3904,
+ "dmaapProtocol": "http",
+ "dmaapTopicName": "/events/unauthenticated.VES_PNFREG_OUTPUT",
+ "dmaapUserName": "admin",
+ "dmaapUserPassword": "admin",
+ "messageLimit": -1,
+ "timeoutMs": -1
+ },
+ "dmaapProducerConfiguration": {
+ "dmaapContentType": "application/json",
+ "dmaapHostName": "message-router.onap.svc.cluster.local",
+ "dmaapPortNumber": 3904,
+ "dmaapProtocol": "http",
+ "dmaapTopicName": "/events/unauthenticated.PNF_READY",
+ "dmaapUserName": "admin",
+ "dmaapUserPassword": "admin"
+ }
+ },
+ "security": {
+ "trustStorePath": "/opt/app/prh/etc/cert/trust.jks",
+ "trustStorePasswordPath": "/opt/app/prh/etc/cert/trust.pass",
+ "keyStorePath": "/opt/app/prh/etc/cert/cert.jks",
+ "keyStorePasswordPath": "/opt/app/prh/etc/cert/jks.pass",
"enableAaiCertAuth": "false",
"enableDmaapCertAuth": "false"
}
+ }
+
+The configuration is created from PRH Cloudify blueprint by specifying **application_config** node during ONAP OOM/Kubernetes deployment.
diff --git a/docs/sections/services/prh/index.rst b/docs/sections/services/prh/index.rst
index d8a22e2..e3ba5bd 100644
--- a/docs/sections/services/prh/index.rst
+++ b/docs/sections/services/prh/index.rst
@@ -14,13 +14,16 @@
PRH overview and functions
--------------------------
-
.. toctree::
- :maxdepth: 1
- ./architecture.rst
- ./configuration.rst
- ./delivery.rst
- ./installation.rst
+ :maxdepth: 1
+ ./architecture
+ ./configuration
+ ./delivery
+ ./installation
+ ./authorization
-.. _`Offered APIs`: ../../apis/prh.rst
\ No newline at end of file
+API reference
+^^^^^^^^^^^^^
+
+Refer to :doc:`PRH offered APIs<../../apis/PRH>` for detailed PRH api information.
diff --git a/docs/sections/services/prh/installation.rst b/docs/sections/services/prh/installation.rst
index aa65dad..22dab33 100644
--- a/docs/sections/services/prh/installation.rst
+++ b/docs/sections/services/prh/installation.rst
@@ -8,50 +8,56 @@
.. code-block:: yaml
-version: '2'
-services:
- prh:
- image: nexus3.onap.org:10003/onap/org.onap.dcaegen2.services.prh.prh-app-server
- command: >
- --dmaap.dmaapConsumerConfiguration.dmaapHostName=10.42.111.36
- --dmaap.dmaapConsumerConfiguration.dmaapPortNumber=8904
- --dmaap.dmaapConsumerConfiguration.dmaapTopicName=/events/unauthenticated.SEC_OTHER_OUTPUT
- --dmaap.dmaapConsumerConfiguration.dmaapProtocol=http
- --dmaap.dmaapConsumerConfiguration.dmaapUserName=admin
- --dmaap.dmaapConsumerConfiguration.dmaapUserPassword=admin
- --dmaap.dmaapConsumerConfiguration.dmaapContentType=application/json
- --dmaap.dmaapConsumerConfiguration.consumerId=c12
- --dmaap.dmaapConsumerConfiguration.consumerGroup=OpenDCAE-c12
- --dmaap.dmaapConsumerConfiguration.timeoutMS=-1
- --dmaap.dmaapConsumerConfiguration.message-limit=-1
- --dmaap.dmaapProducerConfiguration.dmaapHostName=10.42.111.36
- --dmaap.dmaapProducerConfiguration.dmaapPortNumber=8904
- --dmaap.dmaapProducerConfiguration.dmaapTopicName=/events/unauthenticated.PNF_READY
- --dmaap.dmaapProducerConfiguration.dmaapProtocol=http
- --dmaap.dmaapProducerConfiguration.dmaapUserName=admin
- --dmaap.dmaapProducerConfiguration.dmaapUserPassword=admin
- --dmaap.dmaapProducerConfiguration.dmaapContentType=application/json
- --aai.aaiClientConfiguration.aaiHostPortNumber=30233
- --aai.aaiClientConfiguration.aaiHost=10.42.111.45
- --aai.aaiClientConfiguration.aaiProtocol=https
- --aai.aaiClientConfiguration.aaiUserName=admin
- --aai.aaiClientConfiguration.aaiUserPassword=admin
- --aai.aaiClientConfiguration.aaiIgnoreSSLCertificateErrors=true
- --aai.aaiClientConfiguration.aaiBasePath=/aai/v11
- --aai.aaiClientConfiguration.aaiPnfPath=/network/pnfs/pnf
- entrypoint:
- - java
- - -Dspring.profiles.active=dev
- - -jar
- - /opt/prh-app-server.jar
- ports:
- - "8100:8100"
- - "8433:8433"
- restart: always
+ version: '3'
+ services:
+ prh:
+ image: nexus3.onap.org:10003/onap/org.onap.dcaegen2.services.prh.prh-app-server
+ command: >
+ --dmaap.dmaapConsumerConfiguration.dmaapHostName=10.42.111.36
+ --dmaap.dmaapConsumerConfiguration.dmaapPortNumber=8904
+ --dmaap.dmaapConsumerConfiguration.dmaapTopicName=/events/unauthenticated.SEC_OTHER_OUTPUT
+ --dmaap.dmaapConsumerConfiguration.dmaapProtocol=http
+ --dmaap.dmaapConsumerConfiguration.dmaapUserName=admin
+ --dmaap.dmaapConsumerConfiguration.dmaapUserPassword=admin
+ --dmaap.dmaapConsumerConfiguration.dmaapContentType=application/json
+ --dmaap.dmaapConsumerConfiguration.consumerId=c12
+ --dmaap.dmaapConsumerConfiguration.consumerGroup=OpenDCAE-c12
+ --dmaap.dmaapConsumerConfiguration.timeoutMS=-1
+ --dmaap.dmaapConsumerConfiguration.message-limit=-1
+ --dmaap.dmaapProducerConfiguration.dmaapHostName=10.42.111.36
+ --dmaap.dmaapProducerConfiguration.dmaapPortNumber=8904
+ --dmaap.dmaapProducerConfiguration.dmaapTopicName=/events/unauthenticated.PNF_READY
+ --dmaap.dmaapProducerConfiguration.dmaapProtocol=http
+ --dmaap.dmaapProducerConfiguration.dmaapUserName=admin
+ --dmaap.dmaapProducerConfiguration.dmaapUserPassword=admin
+ --dmaap.dmaapProducerConfiguration.dmaapContentType=application/json
+ --aai.aaiClientConfiguration.aaiHostPortNumber=30233
+ --aai.aaiClientConfiguration.aaiHost=10.42.111.45
+ --aai.aaiClientConfiguration.aaiProtocol=https
+ --aai.aaiClientConfiguration.aaiUserName=admin
+ --aai.aaiClientConfiguration.aaiUserPassword=admin
+ --aai.aaiClientConfiguration.aaiIgnoreSSLCertificateErrors=true
+ --aai.aaiClientConfiguration.aaiBasePath=/aai/v11
+ --aai.aaiClientConfiguration.aaiPnfPath=/network/pnfs/pnf
+ --security.enableAaiCertAuth=false
+ --security.enableDmaapCertAuth=false
+ --security.keyStorePath=/opt/app/prh/etc/cert/cert.jks
+ --security.keyStorePasswordPath=/opt/app/prh/etc/cert/jks.pass
+ --security.trustStorePath=/opt/app/prh/etc/cert/trust.jks
+ --security.trustStorePasswordPath=/opt/app/prh/etc/cert/trust.pass
+ entrypoint:
+ - java
+ - -Dspring.profiles.active=dev
+ - -jar
+ - /opt/prh-app-server.jar
+ ports:
+ - "8100:8100"
+ - "8433:8433"
+ restart: always
Running with dev-mode of PRH
-==============================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Heartbeat: http://<container_address>:8100/heartbeat or https://<container_address>:8443/heartbeat