Background

The primary integration point of AAF with DMaaP is to support use cases that use authenticated topics.   An AAF authenticated topic refers to the following items checked by Message Router when a client makes a request on the events API (to publish or subscribe):

• the client identity and credential is valid.  i.e. the client is authenticated to be valid in AAF

• the client identity is allowed to perform the required action.  i.e. the client is authorized to perform a publish or subscriber on a specific topic as determined by AAF permissions.

(Note that Message Router also supports APIKEY authenticated topics, which does not use AAF, and which is being deprecated.)

Within ONAP, coordinated provisioning of Message Router and AAF  for authenticated topics is managed by the DMaaP Buscontroller, which provides the following function:

• generates a Fully Qualified Topic Name (FQTN) that is compliant with the project's topic naming standards and namespace.

• creation of the AAF permissions for each topic

• granting of AAF permissions to AAF Role(s) specified by client applications 

• creation of the FQTN on the Message Router

Server Setup

A test environment has been established in the WindRiver POD-ONAP-01 instance, under the AAF Project.  These components were deployed in separate kubernetes instances so they are not communicating via kubernetes service names yet.  Likewise, a client attempting to communicate with these components needs to know the node port for proper mapping to the container.

AAF Pre-requisites

A client of an AAF Authenticated Topic must have an Application Identity  (see AAF Environment - Beijing).  This identity is used when attempting to publish or subscribe to an authenticated topic.

The Application Identity must be assigned to an AAF Role.  The following steps are done by a human developer once in this AAF instance, and the changes will be saved as part of the AAF bootstrap provisioning process to be applied to other AAF deployments in the future:

1. Login to the AAF GUI using a People Identity that has Administration privilege for the Application Namespace.

2. Create a Role that makes sense for the client.  e.g. A publisher client that has an identity within namespace org.onap.anapp might define a Role of org.onap.anapp.mrclient.
   The AAF Command Line syntax would be:  
                           role create org.onap.anapp.mrclient

3. Assign the Application Identity to the Role.  Be careful about the ordering of the parts of the namespace.
   The AAF Command Line syntax would be:  
                           role user add anapp@anapp.onap.org org.onap.anapp.mrclient

Repeat steps 2 and 3 as needed for different clients.  Note that many Identities can be added to a Role, and an Identity can be added to different Roles.  This allows us to design topic access granularity as needed.

AAF CLI Example:

> role create org.onap.dcae.pnfPublisher

^{Created Role}

> role user add org.onap.dcae.pnfPublisher dcae@dcae.onap.org

^{Added User [dcae@dcae.onap.org] to Role [org.onap.dcae.pnfPublisher]}

> role create org.onap.dcae.pnfSubscriber

^{Created Role}

> role user add org.onap.dcae.pnfSubscriber dcae@dcae.onap.org

^{Added User [dcae@dcae.onap.org] to Role [org.onap.dcae.pnfSubscriber]}

> perm list user dcae@dcae.onap.org

^{List Permissions by User[dcae@dcae.onap.org]}

^{--------------------------------------------------------------------------------}

^{PERM Type                      Instance                       Action}   

^{--------------------------------------------------------------------------------}

^{org.onap.aai.resources         *                              delete}   

^{org.onap.aai.resources         *                              get}      

^{org.onap.aai.resources         *                              patch}    

^{org.onap.aai.resources         *                              post}     

^{org.onap.aai.resources         *                              put}      

^{org.onap.aai.traversal         *                              advanced} 

^{org.onap.dcae.certman          local                          request,ignoreIPs,showpass}

Topic Provisioning

The Buscontroller API often refers to an attribute "dcaeLocation".   This is used to identity which Message Router instance is to be used by a particular client.  In ONAP Casablanca, there is only one Message Router instance, and in the AAF integration environment  it has the value "san-francisco".   This field and value is included in any topic provisioning request.

Use an http client (e.g. curl or postman) to make a provisioning request of Buscontroller

1. the message body contains JSON.  A simple example to add a topic with 1 publisher (action:pub), and 1 subscriber (action:sub).  However, note that the Role of the publisher and subscriber are different in this example to show that it is normal for Message Router clients to have different heritage and function.:

   ^{{
   "topicName": "aPnfTopic-1540492548",}

   <sup>"topicDescription": "A simple topic to demonstrate provisioning",
   "owner": "OnapDev",
   "txenabled": false,
   "clients": [{
   "dcaeLocationName": "san-francisco",
   "clientRole": "org.onap.dcae.pnfPublisher",
   "action": [
   "pub",
   "view"
   ]
   
   },</sup>

   ^{{
   "dcaeLocationName": "san-francisco",
   "clientRole": "org.onap.dcae.pnfSubscriber",
   "action": [
   "sub",
   "view"
   ]
   }]
   }}

2. POST to <Buscontroller HTTP Node Port>/webapi/topics

   1. Headers:
      Content-Type: application/json

Upon success, the Buscontroller response includes a few items of interest:

1. the FQTN to be referenced on Message Router.  Note that this value incorporates the topic namespace used in this deployment. 
   example: 
                 "fqtn": "org.onap.dmaap.mr.aPnfTopic-1540492548"

2. the topicURL to be used by each client.  Again, except for the FQTN portion of the URL, these will look identical in this test environment, but would not necessarily be the same in an environment with multiple MR instances.
   example: 
                 "topicURL": "http://10.12.7.22:30227/events/org.onap.dmaap.mr.aPnfTopic-1540492548"

Confirm that Buscontroller provisioning was actually successful:

1. Verify that the FQTN exists on Message Router.  Retrieve the list of topics on Message Router and confirm your topic is there.
   curl http://10.12.7.22:30227/topics  

2. Use the AAF GUI to confirm that the Application Identity to be used by your client has the proper permissions.
   perm list user anapp@anapp.onap.org
   
   AAF CLI example:
   
   

   > perm list user dcae@dcae.onap.org

   ^{List Permissions by User[dcae@dcae.onap.org]}

   ^{--------------------------------------------------------------------------------}

   ^{PERM Type                      Instance                       Action}   

   ^{--------------------------------------------------------------------------------}

   ^{org.onap.aai.resources         *                              delete}   

   ^{org.onap.aai.resources         *                              get}      

   ^{org.onap.aai.resources         *                              patch}    

   ^{org.onap.aai.resources         *                              post}     

   ^{org.onap.aai.resources         *                              put}      

   ^{org.onap.aai.traversal         *                              advanced} 

   ^{org.onap.dcae.certman          local                          request,ignoreIPs,showpass}

   ^{org.onap.dmaap.mr.topic        :topic.org.onap.dmaap.mr.aPnfTopic-1540492548 pub}      

   ^{org.onap.dmaap.mr.topic        :topic.org.onap.dmaap.mr.aPnfTopic-1540492548 sub}      

   ^{org.onap.dmaap.mr.topic        :topic.org.onap.dmaap.mr.aPnfTopic-1540492548 view}     

Once the Topic is properly provisioned, Buscontroller is no longer needed - it is not part of the message delivery flow.

Topic Publication Using the MR API

An http client can be a publisher of an authenticated topic if it passes the authorized Application Identity using Basic Authentication.  If a local file, fileContainingMsg, exists, then an example of a curl publisher might be:

^{curl -X POST -u 'anapp@anapp.onap.org:demo123456!' @fileContainingMsg -H 'Content-Type: application/json'  http://10.12.7.22:30227/events/org.onap.dmaap.mr.aSimpleTopic}

The client communicates directly with Message Router.

NOTE: if the Basic Authentication credentials were not passed, the publish attempt should fail with a 401.  If some other credentials that hadn't been granted the publish permission were passed, the publish attempt should fail with 403. 

Topic Subscription Using the MR API

An http client can be a subscriber of an authenticated topic if it passes the authorized Application Identity using Basic Authentication.   The subscriber must further qualify their request with a Consumer Group identifier/Consumer Id.  For example, the first subscriber of group 'example' might poll Message Router like this:

curl -X GET -u 'app2@app2.onap.org:demo123456!'  -H 'Content-Type: application/json'  http://10.12.7.22:30227/events/org.onap.dmaap.mr.aSimpleTopic/example/01

NOTE: if the Basic Authentication credentials were not passed, the subscribe attempt should fail with a 401.  If some other credentials that hadn't been granted the subscribe permission were passed, the subscribeattempt should fail with 403.

Note: If an application uses Kafka API, instead of the Message Router to interact with Kafka, add the following additional properties while creating a Producer or Consumer.