Pub Sub Security Service User Guide

Repository : https://gitlab.fit.fraunhofer.de/efpf-pilots/efpf-security-components/efpf-pub-sub-security/pub-sub-frontend.git –branch pub_sub_security

Pub Sub Security Service User Guide

The Pub Sub Security Service is mainly a web client application which provides interface components and navigation to interact with the repository of resources that require access to the Message Bus in EFPF. It also provides the visualization of the location of these resources through the Google Maps API. The service also provides topic management functionality, allowing users to create topics in the EFPF Message Bus for their resources to publish to. The tool then provides; a means to discover public, consumable topics, to which they can request permission to consume; functionality to view and manage permission requests to managed resources; and to request credentials / connection details to permitted topics.

When entering the Pub Sub Security Front end, if the user does not already have a RabbitMQ account, a RabbitMQ user account will be created for the logged in EFPF user and linked by email id. A vhost within the Message Bus will then be created for the users company, if one does not already exist, with appropriate vhost permissions also applied.

To use the EFPF Message Bus, each resource (Tool, Service, Factory Connector, IFE Flow) requiring publish or subscribe access to the Message Bus must be registered with the Pub Sub Security Service. To understand the steps required to register and manage resource, please refer to the Resource Management section.#

Once a User’s resource has been registered with the Pub Sub Security Service, a user may then create topics for this resource to publish to. In this process, as a user creates a topic, a RabbitMQ queue is created and bound to the ‘amq.topic’ exchange with the user defined topic name. Alongside this, the user is granted publish permissions for this topic. From this point, the user is then able to request and download the credentials/configuration parameters needed to publish to this topic.

Once a topic has been created, if the associated resource is marked a public, other EFPF users may then discover and request permission to consume this topic. At this point, the topic owner will recieve notification of this request and have the ability to approve or reject the permission request.

In the event a permission request to consume a topic is approved, a new queue will be created for the approved user and bound to the topic owners vhost’s ‘amq.topic’ exchange with the defined topic name. The approved user will then be assigned the correct topic permissions and vhost permissions if neccessary. Similar to a previous step, the permitted user may then request and download the credentials/configuration parameters required to consume this topic.

At any point, a topic owner may revoke permissions for a given user to consume a given topic without and warning or notification.

It should also be noted that all topics created in the EFPF Message bus will be defined in line with the Sparkplug topic naming convention, which is enforced with the ‘Create Topic’ Page. For reference the Sparkplug topic naming convention can be seen below:

Sparkplug Topic Naming Convention Figure 1: Sparkplug Topic Naming Convention for EFPF

Services used

  • EFPF API Security Gateway
  • EFPF Pub Sub API
  • EFPF Message Bus
  • EFPF Security (EFS)

Benefits

  • Comprehensive representation of information about resources
  • Easy location of elements through Google Maps API
  • Agile management of resources and topics
  • Management of permission requests
  • Download credentials to produce or consume topics
  • Discover public, consumable topics
  • Monitor resources and topics

Resource Management

Short overview

The Resource Management functionality is designed to consume information about the resources, such as:

  • Name of the resource
  • Description of the resource
  • Type of resource: Service, Tool, Factory Connector or Data Stream (IEEFlow)
  • Location (Latitude and Longitude coordinates)
  • Company that provides the resource

The information is retrieved through the Pub Sub API which provides a secure user access via authorization.

The Resource Management features enables the management of the repository of resources through functionalities for creating, reading, updating and deleting resources.

Resource Management Tool UI Figure 2: User Interface of the Resource Management Tool frontend

As a short disclaimer, the design of the UI is open to improvements and new additions based on particular needs during the experimentation in the EFPF context.

List of resources

The list of resources is the main screen of the Resource Management Tool. In the left hand, a table lists all the items available in the repository. In the right hand, a map displays the location of the different resources. When passing the mouse over the markers, a tooltip with information for resource identification is displayed. Details of a particular item can be inspected by both clicking on the corresponding row in the table or by clicking on the corresponding marker in the map.

Map of resources

The map of resources is the same component that the one on the right hand of the list of resources section, but displayed in wide screen. As commented earlier, the map displays the location of the resources and further information to identify the resource is displayed in a tooltip when passing the mouse pointer over every marker. Users can also click on a marker to navigate to the details of resource section.

Register new resource

The users can register new resources by filling the registration form. Besides the aforementioned attributes, the registration includes a checkbox to indicate the privacy of the resource, in order to make the topics produced by this resource available. The field ‘Company’ is not editable and it is automatically obtained from the user who is logged in the platform.

The location of the resource can be introduced by both, the latitude and longitude fields of the form or by dragging and dropping the marker of the map on the right hand. When coordinates are introduced manually, the user can select the button for ‘Go to location in map’ and the marker is placed on the introduced coordinates, so the user can check if the input coordinates are correct. If the marker in the map of the right hand side is dragged and dropped, the coordinates fields of the form are automatically updated according to the marker position. If some error in several fields are detected by the user, this can clear the whole form by clicking on the ‘Clear’ button.

Once the data of the resource has been filled, this can be registered in the repository by clicking the ‘Save’ button, and the tool then redirects to the list of resources. It should be noted that the title, type and description fields of the form are mandatory to register a new resource.

Details of resource

In this section the main details of the resource can be inspected. Besides these fields, the ‘Created by’ attribute is shown to identify the user who registered the service. From this section, a resource can be edited or deleted from the registry. In case of editing a resource, the tool redirects to the Registration section so the user could perform any updated on the resource properties. When changes are saved, the information is automatically updated. The deletion button removes the selected resource from the registry so this should be used cautiously. A confirmation dialog is shown to the user before executing the deletion.

Topic Management

Short overview

The Topic Management functionality provides a means to:

  • Discover and request permission to consume public and owned topics in the Message Bus
  • Create topics for owned resources to publish to
  • Download the credentials / configuration details needed to publish or subscribe to permitted topics
  • Manage permission request to owned topics

The information retrieved and actions performed are done so through the Pub Sub API which provides a secure user access through authorization.

As a short disclaimer, the design of the UI is open to improvements and new additions based on particular needs during the experimentation in the EFPF context.

View Topics

The View Topics page is the entry point for the topic management based functionality provided by the Pub Sub Security Service. Through this page a user can:

  • View owned topics
  • Discover and request permission to consume public and owned topics in the message bus
  • Download the credentials / configuration details needed to publish or subscribe to permitted topics

At the top of the page, a search bar is provided to enable to the discovery of topics by keyword. In the center of the page, a table is displayed which lists all created topics that are either owned or marked public in the EFPF Message Bus. As shown below, there are three distinct section within the table. The first of which is marked “Topic”, and this displays the topic name (broken down by the Sparkplug naming convention attributes) alongside a description if one was provided. The next section is marked “Resource”, and this displays information about the topics associated resource including the name, type of resource, owner of resource (company) and description if one was provided. The final section is marked “Credentials”, and this provides buttons to view the credentials / configuration details required to publish or subscribe to the given topic, if valid permissions are held. Otherwise, a button is provided that allows a user to request permission to consume the given topic from the topic’s owner.

View Topics Page Figure 3: View Topics Page

Credentials Pop Up

Once publish or subscribe permissions have been obtained for a topic, a user may then request the credentials / configuration details needed to publish or subscribe to the topic. To access the Credentials Pop Up, select the |↗️| button on the desired topic that is displayed in the view topics page. A Credentials Pop Up will then be displayed similar to the one show below in Figure 4. A JSON stucture is then displayed that provides the needed details to connect to the topic in the DS Message Bus.

Credentials Pop Up Figure 4: Credentials Pop Up

A range of fields have been provided that can simply be copy and pasted into your configuration files depending on the clients and libraries used.

NOTE: The “routingKey” provided on the Credentials Pop Up and highlighted in Red, should be used as the Topic Name directly.

Create Topic

The Create Topic page allows users to create topics for their owned resources to publish to. For this, a form is provided to collect the required information. Within this form a dropdown box is provided to allow the user to select which resource the topic should be created for. A second dropdown is then provided to allow the selection of the topic’s message type attribute. A series of text boxes are then provided to collect the remaining Sparkplug attributes that form the topic name; Group ID, Edge Node ID & Device ID (Optional). A final text box is then shown allowing the user to add a description (optional). Further information around the Sparkplug Topic Naming Convention enforced can be found in the Overview of this document.

Create Topic Page Figure 5: Create Topic Page

Credentials Admin

The Credentials Admin page provide users with two distinct areas. This first of which “New Requests”, provides a table listing any new permission requests to owned topics. Information about the requested topic, associated resource and requesting user is displayed within the table alongisde buttons which allow the approval or rejection of each permission request. The second area “Approved” provides a table listing all topic permissions that have previously been granted on owned topics. Information about the approved topic permission, associated resource and connected user account is displayed within the table alongside a button that allows a topic owner to revoke the topic permission.

Credentials Admin Page Figure 6: Credentials Admin Page

Monitoring

Short overview

The Monitoring functionality in the pub-sub-security service is designed to give user an overview of the resources and topics that are available in the system, including:

  • Number of resources (available to the user vs. owned by the user)
  • Number of topics (available to the user, published by the user, consumed by the user)
  • Distribution of the resources
  • Distribution of the topics

Monitoring

The Monitoring UI can be reached from the main page of Pub Sub Security Service from the top navigation bar. Once you clicked on “Monitoring”, the monitoring UI main page will be displayed as shown in Figure 1.1 below.

The monitoring UI is devided in two sections:

  • The top area of the UI is showing the statistics for resources and topics, available to the user or owned/published/consumed by the user.
  • The bottom area of the UI shows the resource and topic distribution in doughnut chart which gives user an intuitive view of types of resources, and topics consumption status. Note: user can move the mouse over the corresponding section of the doughnut chart to see the exact number of the corresponding type of resource or topic.

Monitoring UI main page Figure 7: Monitoring UI

The resource distribution chart on the bottom-left corner of the monitoring UI provides additional option for you to switch to see the distribution specific to resources you own. As shown in the screenshot below, you can click on the View Option drop-down list to select “My Resources” and then click “Apply”, the chart will be updated to show your resource distribution instead of the default view of resource distribution for all resources.

Resource Distribution Options Figure 8: Resource Distribution Options

Previous