Security for Historian for Linux container Ecosystem

This section describes the security mechanism for the Historian for Linux container ecosystem. The main objective here is to protect the Historian database, which is the custodian of data. The security is implemented in two tiers:
  • Tier 1- Docker private network

    Docker private network is a technology that enables a group of Docker containers to perform network communication with one another. The ports on which applications of this groups are listening is available for view-only to member applications of this Docker private network. If any Docker container wants to expose its port outside of the Docker private network, that port must be exposed.

    The following diagram shows the network ports on which various Historian containers are listening.

    As shown in the diagram, the ports 9443, 9090, 9000 and 8989 are exposed to outside of docker private network. So, the clients of web admin, tuner, REST query, and public REST APIs can interact with these applications either from outside of the machine or from Docker private network.

    The port 14000 is not exposed if you are using Predix Edge. If, however, you are using a generic Linux distribution, the port 14000 is exposed. This port (TCP/IP port) is secured via Docker private network. The members of this network like tuner, web admin, REST query service, public REST APIs, and collectors (MQTT and OPCUA) can only connect to port 14000 of the Historian database.

  • Tier 2 (OAUTH2 mechanism)

    In tier 1, the ports 9443, 9090, 9000, and 8989 are not protected. If, however, you want to protect these ports, the REST query, tuner, web admin, and the public REST APIs can use the OAUTH2 authentication and authorization mechanism.

    The following diagram shows the network ports that use the OAUTH2 authentication and authorization mechanism.

    As shown in the diagram, the Historian database does not use any OAUTH2 authentication and authorization mechanism directly. You interact with the Historian database using the web admin, tuner, public REST APIs, and the REST query applications.

    The Historian database is the ultimate resource we want to protect (the analogy here can be to that of a vault in a bank), while web admin, tuner, public REST APIs, and the REST query act as resource owners and are guards of the Historian database (analogy with the guard of the vault in a bank).

    To provision the tier 2 security mechanism, you must set up an OAUTH2 server or you can use Predix UAA (OAUTH2 server on Predix Cloud).
    Note: The public REST APIs perform authentication and authorization with Historian UAA or Operations Hub UAA.

    Web admin, tuner, public REST APIs, and REST query offer Docker environment variables by which the users can provide OAUTH2 credentials to these Docker containers, so that these applications can validate the token from the specified OAUTH2 server.

    The following code sample provides the environment variables to set for each application to leverage OAUTH2 authentication and authorization:
    For Tuner 
    OAUTH2_CLIENT_SECRET= my-uaa-secret 
    For REST Query Service 
    - ZAC_UAA_CLIENTID=my-uaa-client 
    - ZAC_UAA_CLIENT_SECRET=my-uaa-secret 
    - USE_PROXY=true 
    - PROXYURL= 
    For Web-admin 
    For Historian Public REST API
For information on how to set these environment variables, refer to:You can also refer to the docker-compose.yml file provided with the Historian Docker application bundles for the aforementioned environment variables.