From 7782f9bbff5a50bbae180c4ad27338bbbf321565 Mon Sep 17 00:00:00 2001 From: Tomek Kaminski Date: Wed, 7 Nov 2018 15:12:44 +0100 Subject: 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 --- docs/sections/apis/PRH.rst | 4 +- docs/sections/services/prh/architecture.rst | 4 +- docs/sections/services/prh/authorization.rst | 60 +++++++++++++++++++ docs/sections/services/prh/configuration.rst | 87 ++++++++++++++------------- docs/sections/services/prh/index.rst | 17 +++--- docs/sections/services/prh/installation.rst | 88 +++++++++++++++------------- 6 files changed, 169 insertions(+), 91 deletions(-) create mode 100644 docs/sections/services/prh/authorization.rst diff --git a/docs/sections/apis/PRH.rst b/docs/sections/apis/PRH.rst index f693ef76..2a7d0eae 100644 --- a/docs/sections/apis/PRH.rst +++ b/docs/sections/apis/PRH.rst @@ -1,3 +1,5 @@ +.. _prh_api: + ============================== PRH (PNF Registration Handler) ============================== @@ -28,7 +30,7 @@ Paths ===== GET /events/unauthenticated.VES_PNFREG_OUTPUT ------------------------------------------------ +--------------------------------------------- Description ~~~~~~~~~~~ diff --git a/docs/sections/services/prh/architecture.rst b/docs/sections/services/prh/architecture.rst index c47772a3..090c405e 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 00000000..fe5ed40b --- /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` : + +.. 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` : + +.. 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` 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 a36ad953..0e4109cf 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 @@ PRH expects to be able to fetch configuration directly from consul service in fo .. 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 d8a22e21..e3ba5bd9 100644 --- a/docs/sections/services/prh/index.rst +++ b/docs/sections/services/prh/index.rst @@ -14,13 +14,16 @@ the PNF Registration event. PRH overview and functions -------------------------- - .. toctree:: - :maxdepth: 1 - ./architecture.rst - ./configuration.rst - ./delivery.rst - ./installation.rst + :maxdepth: 1 + + ./architecture + ./configuration + ./delivery + ./installation + ./authorization +API reference +^^^^^^^^^^^^^ -.. _`Offered APIs`: ../../apis/prh.rst \ No newline at end of file +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 aa65dadf..22dab33e 100644 --- a/docs/sections/services/prh/installation.rst +++ b/docs/sections/services/prh/installation.rst @@ -8,50 +8,56 @@ Following docker-compose-yaml file shows default configuration and can be run us .. 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://:8100/heartbeat or https://:8443/heartbeat -- cgit 1.2.3-korg