Copyright

Copyright © 2019 Balasys IT Ltd.. All rights reserved. This document is protected by copyright and is distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this document may be reproduced in any form by any means without prior written authorization of Balasys.

This documentation and the product it describes are considered protected by copyright according to the applicable laws.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)

Linux™ is a registered trademark of Linus Torvalds.

Windows™ 10 is registered trademarks of Microsoft Corporation.

The Balasys™ name and the Balasys™ logo are registered trademarks of Balasys IT Ltd.

The Zorp™ name and the Zorp™ logo are registered trademarks of Balasys IT Ltd.

The Proxedo™ name and the Proxedo™ logo are registered trademarks of Balasys IT Ltd.

AMD Ryzen™ and AMD EPYC™ are registered trademarks of Advanced Micro Devices, Inc.

Intel® Core™ and Intel® Xeon™ are trademarks of Intel Corporation or its subsidiaries in the U.S. and/or other countries.

All other product names mentioned herein are the trademarks of their respective owners.

DISCLAIMER

Balasys is not responsible for any third-party websites mentioned in this document. Balasys does not endorse and is not responsible or liable for any content, advertising, products, or other material on or available from such sites or resources. Balasys will not be responsible or liable for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through any such sites or resources.

2021-10-22 .Copyright

Preface

Typographical conventions

Before you start using this guide, it is important to understand the terms and typographical conventions used in the documentation. For more information on specialized terms and abbreviations used in the documentation, see the Glossary at the end of this document.

The following text formatting principles and icons identify special information in the document.

Tips provide best practices and recommendations.
Notes provide additional information on a topic, and emphasize important facts and considerations.
Warnings mark situations where loss of data or misconfiguration of the device is possible if the instructions are not obeyed.
Command

Commands you have to execute.

Emphasis

Reference items, additional readings.

/path/to/file

File names.

Parameters

Parameter and attribute names.

In the parameter listing tables the required parameters are also emphasized with bold text:

Key Description

param1

This is a required parameter.

param2

This is an optional parameter.

Additional marks used specifically in the Web User Interface (UI):

Key Description

*

The elements marked with * in the configuration reference tables are mandatory to be configured.

(Default)

For some of the configuration elements there are recommended default values, marked as (Default). In case the value is not defined during the configuration, the default value will be considered for the actual element.

+

By clicking this sign you can add the actual element to the list of configuration elements.

Contact and support information

This product is developed and maintained by Balasys IT Ltd..

Contact:

Balasys IT Ltd.
4 Alíz Street
H-1117 Budapest, Hungary
Tel: +36 1 646 4740
E-mail: <info@balasys.hu>
Web: http://balasys.hu/

Sales contact

You can directly contact us with sales-related topics at the e-mail address <sales@balasys.hu>, or leave us your contact information and we call you back.

Support contact

To access the Balasys Support System, sign up for an account at the Balasys Support System page. Online support is available 24 hours a day.

Balasys Support System is available only for registered users with a valid support package.

Support e-mail address: <support@balasys.hu>.

Training

Balasys IT Ltd. holds courses on using its products for new and experienced users. For dates, details, and application forms, visit the https://www.balasys.hu/en/services#training webpage.

1. Scope of this document

This document describes the Web User Interface for the Proxedo API Security. The purpose of this document is to present the designed approach and the usage for the configuration of Proxedo API Security via Web User Interface (UI). The Web UI allows easy configuration for Proxedo API Security. All the functionalities are grouped visually and logically into thematic units which follow the logical built up of Proxedo API Security’s configuration. The primary intended audience of this document are system engineers and system designers for configuring Proxedo API Security systems.

2. Introduction to Proxedo API Security

2.1. What is Proxedo API Security

The Proxedo API Security (PAS) is a security solution that protects API serving endpoints. It is positioned in the network flow between consumers of the APIs (clients) and backend solutions serving the API (servers) as a transparent HTTP proxy.

Proxedo API Security can:

  • handle incoming Transport Layer Security v1 (TLS) connections from clients & outgoing TLS connections to servers separately and selectively

  • verify that the communication conforms to HTTP specifications

  • verify that the content of the messages conform to their specified content type

  • verify that the content of messages conform to API specification(s) as described in schemas

  • extract parts of the content of the messages and relay them to external data stores such as log servers, SIEM systems or other data warehouses

2.2. Where to start

Depending on what you need to do the following starting points are suggested:

3. Overview of Proxedo API Security

3.1. Main features

3.1.1. TLS

Transport Layer Security v1 (TLS) (successor of the now obsoleted Secure Socket Layer v3 (SSL)) is a widely used crypto protocol, guaranteeing data integrity and confidentiality in many PKI and e-commerce systems.

The TLS framework inspects TLS connections, and also any other connections embedded into the encrypted TLS channel. TLS connections initiated from the client are terminated on the Proxedo API Security, and two separate TLS connections are built: one between the client and the firewall, and one between the firewall and the server. If both connections match the configuration settings of PAS (for example, the certificates are valid, and only the allowed encryption algorithms are used), PAS inspects the protocol embedded into the secure channel as well. Note that the configuration settings can be different for the two connections, for example, it is possible to permit different protocol versions and encryption settings.

3.1.2. Enforcement

Proxedo API Security acts as an HTTP proxy and verifies that the traffic passing through conforms to HTTP’s specifications. By using OpenAPI schemas, as defined in OpenAPI specifications (also known as Swagger), it also verifies that the traffic passing through conforms to the API enpoint’s specification and can log or deny non-conforming traffic.

PAS also provides its own versatile filtering system to control passing traffic.

3.1.3. Insights

With Proxedo API Security it is possible to extract business-relevant information with extremely high resolution from the traffic and relay it to external data stores where further analysis can be implemented.

Thus, it is possible to feed Log Management solutions, Monitoring and SIEM systems, Data visualization tools with data extracted from the traffic, even to the level of specific fields deep inside API calls or URI parameters.

3.1.4. Security flow

The security flow binds most of PAS’s features together. It allows flexible configuration for handling the traffic. Multiple Enforcement, Filter and Insight plugins can be mix-and-matched with control over error policies.

3.1.5. High Availability

Proxedo API Security offers the high availability (HA) feature optionally. With the help of this feature, two identical PAS servers provide redundancy so that the network traffic is not disturbed in case any of the nodes fails. Support for synchronizing configuration and setting remote services' state is also implemented.

3.1.6. Monitoring

The Monitoring system of Proxedo API Security core leverages the widely accepted Simple Network Management Protocol (SNMP) to monitor its network components and to collect data on the components systematically. The monitoring capability of PAS core relies on the SNMP daemon. The collected data, organized into an information database and shared between the SNMP daemon and the Monitoring Manager is called Management Information Base (MIB). For the analysis of the collected data, the BALASYS-SNMP-MIB and the PAS-SNMP-MIB Management Information Base (MIB) documents can be downloaded from Balasys customer documentation. Further recommended MIB files are, SNMPv2-MIB, IF-MIB and UCD-SNMP-MIB.

3.2. Main Concepts in Proxedo API Security

This chapter provides an overview of the Proxedo API Security solution, introduces its main concepts, and explains the relationship of the various components.

API Endpoint

Proxedo API Security protects API endpoints. An API endpoint is the serving part of the communication channel and is the collection of all functions of a service. It resides at a list of well-known top URIs under which all the functions are accessible. APIs have well-defined HTTP Endpoints for all exposed calls, resources etc., usually through providing a schema that describes all parameters of these URI paths, including possible HTTP response codes, the format and fields of the data structure in the request’s and response’s body.

Client

It is a consumer of API endpoints. It is the source of the requests.

Backend

The backend constitutes of one or more servers that serve the API endpoint. It receives the requests of the client and sends the responses.

HTTP message

It can be an HTTP request coming from the client or an HTTP response coming from the backend.

Call

An HTTP conversation constitutes of a request — response interchange of HTTP messages between the client and the backend. Whenever the direction is irrelevant in the context — it applies to both requests and responses — the message is named Call.

Listener

It is the part of PAS that listens to incoming traffic for given API Endpoints. It is bound to a network port. Clients address this port when accessing API Endpoints through the gateway.

TLS

Transport Layer Security is the cryptographic protocol that secures HTTPS communications. PAS can apply TLS encryption both when communicating with Clients and Backends.

Security flow

It provides a collection of security rules that PAS applies to a Call. It is two series of Plugins: one for requests and one for responses.

Plugin

It is an element of the security flow that applies a specific security function. It has different types based on the role they do.

Decompressor

It is a Plugin responsible for decompressing compressed content in the HTTP message’s body. This ensures that the original content of the message is available for processing.

Compressor

It is a Plugin responsible for compressing the result of a flow and forwarding the compressed content.

Deserializer

It is a Plugin responsible for parsing the HTTP message’s body to structured data. This ensures that a message is well-formed. The structured data will also be consumed by other Plugins that operate on the body of the message.

Serializer

It is a Plugin responsible for serializing the structured data to the format of the HTTP message’s body.

Filter

It is a Plugin that rejects calls when they match defined rules.

Enforcer

It is a Plugin that validates calls against externally defined schemas.

Insight

It is a Plugin that extracts various data from the call and sends it to external systems (log servers, SIEMs, and other data analysis tools).

Brick

They are reusable components of Plugins. They can be defined on their own and then shared by multiple Plugins.

Error policy

It is a brick that defines what happens if the Plugin has found an error. It decides if calls are rejected or merely logged, and defines the details of the HTTP error response sent to the client if a call is rejected.

Matcher

It is a brick that decides if the Plugin should be executed for a given call by checking various data in the HTTP message.

Selector

Selector is a brick that can extract a piece of information from a call. It is used by Insight plugins.

Target

It is a brick that defines an external system to send extracted data to. It is used by Insight plugins.

High Availability

This feature enables two nodes serving as redundant PAS endpoints. It helps ensure service continuity in case of a node failure while being transparent to clients.

3.3. Architecture for Proxedo API Security

Proxedo API Security is based on a micro-services architecture.

The components of the architecture are each responsible for well-defined subset of handling traffic between the client and the backend. Proxedo API Security is built up of three components:

Transport Director

It manages the transport layer of API connections:

  • handles network connections from the client

  • handles network connections towards the backends

  • handles TLS on these connections

  • load-balances between multiple backend servers

  • load-balances between multiple Flow Directors

  • enforces HTTP protocol validity in calls

Flow Director

It is responsible for the execution of the Plugins in the Endpoint’s flow and for applying Error Policies as necessary.

Insight Director

It manages the connections to Targets. It is responsible for sending the data collected by Insight plugins to Target systems.

The handling of a connection with the help of components is shown in this figure:

PAS Architecture
Figure 1. PAS Architecture
  1. Incoming connections are accepted by the Transport Director.

    • It handles TLS with the client if necessary.

  2. It hands over the connection to the Flow Director.

    • The Flow Director chooses the Endpoint based on the URL.

    • The Flow Director applies the Endpoint specific Request Security Flow.

  3. If an Insight plugin needs to send data to an external Target it sends the collected data to the Insight Director.

  4. The Insight Director sends the data further to the Target with the appropriate protocol.

  5. The Flow Director hands the connection back to the Transport Director.

  6. The Transport Director then sends the data to the Backend.

    • It handles TLS with the backends if necessary.

    • It performs load balancing among Backend servers if necessary.

The same procedure is executed with the response coming from the Backend.

3.3.1. Understanding processing flow

The figure on Proxedo API Security architecture and the steps following that describe how client connection is handled. The following figure explains how calls are processed in more details:

PAS processing flow
Figure 2. PAS processing flow
  1. As shown in the figure above, the incoming connection from the client is handled by the Transport Director, applying TLS if needed.

  2. The Transport Director hands over the connection to the Flow Director, indicating which Listener the connection belongs to.

  3. The Flow Director then chooses the Endpoint based on the URL in the request. First endpoint has matching URL is chosen.

  4. The Flow Director then starts applying the request part of the Security Flow definition.

  5. For each Plugin the Flow Director:

    • Checks if the Plugin's matcher matches the request.

    • If so, it executes the Plugin, if not, it executes the next Plugin.

    • If the Plugin indicates success it executes the next Plugin.

    • If the Plugin indicates an error it applies the Plugin's error policy. If the policy dictates to abort the connection:

      • It fills error details and hands back the connection to the Transport Director, aborting the execution of the flow.

      • The Transport Director closes the connection, sending error details to the client if allowed by the policy.

  6. Once, the last Plugin has been executed the connection is handed back to the Transport Director.

  7. The Transport Director initiates the connection towards the Backend:

    • It handles load balancing if necessary.

    • It handles TLS if necessary.

    • It sends the request itself to the Backend server.

  8. The Backend server sends its response to the Transport Director.

  9. Once, the response has been received the Transport Director again hands over the connection to the Flow Director.

  10. The Flow Director then starts applying the response part of the Security Flow definition, executing the Plugins as above.

  11. Once, the last Plugin has been executed the connection is handed back to the Transport Director.

  12. Finally, the Transport Director sends the response to the client.

Usually, Plugins are organized in the following manner:

  • A Decompressor Plugin extracts the compressed body.

  • A Deserializer Plugin processes the decompressed request to understand the details in the body.

  • Filters are applied to filter unnecessary traffic.

  • Enforcers are applied for detailed validation of calls.

  • Insights are applied to collect data from the call.

  • Serializer Plugin serializes the body

  • Compressor Plugin compresses the serialized body

Though the order of the plugins can be changed based on the needs, note the followings:

  • When a Plugin needs access to the request body it requires Deserialized data. It is therefore strongly recommended that the first plugin is a Decompressor followed by a Deserializer.

  • At the end of the flow it is strongly recommended to place a Serializer plugin followed by a Compressor.

  • Generally Insights are applied after Filters and Enforcers so that they are not executed on possibly invalid calls.

  • Anything that operates on the HTTP headers or the body of the message will be aware of the call direction: The same Plugin in the request and response flow will act on the request or response data.

  • However, the Flow Director handles a request-response exchange together, so you can still use details from the request in Plugins of the response flow. The most notable example of this is using URI or method matchers in the response flow.

  • Plugins in the request flow, however, cannot access details of the response flow (since they are not available yet.)

It is also worth noting that Insight Plugins instantly hand over data to the Insight Director, and let the execution continue.

3.3.2. Architecture with High Availability

In case of HA operation, the core component is configured on both nodes participating in the HA operation. The architecture and the process are identical on both nodes, but they are set up to work redundantly. Only one node (the master) of the cluster is receiving traffic actively.

This operation uses the following additional resources:

  • two nodes with PAS core installed

    At the moment, only clusters of two are supported. It also means, that you will need to have a node with both management and core components installed, and a node with only core installed.
  • a virtual IP address through which the service is supposed to be accessible

The technical foundation of our HA solution is the Virtual Router Redundancy Protocol (VRRP). Once the requirements are properly set up, it operates as follows:

  • At startup, the nodes send keepalive messages to each other to see if the other node is available. Both of them consider themselves to be in BACKUP state until they make sure the other node is not in MASTER state. If both nodes are newly connected to the cluster, they participate in an election and the one with the higher priority becomes the MASTER.

  • After one of the nodes has become the MASTER, both of them keep sending keepalive messages so that they notice when the other node disappears.

  • A node (re)connecting to the cluster does not result in the reelection of the MASTER.

4. Installation of Proxedo API Security

PAS is mainly distributed as Docker images, and is also completed with a .deb package that sets up the operational environment.

You can install the management and the core components either on one single node in Standalone setup or on two separate ones in Multi-node setup. The synchronization of the core configuration is provided by the storage component.

The specific sections on the installation of the different components provide details on how to install them on a node. The installation order of the components is described in section Installation scenarios.

For the multi-node setup, we provide a core deployment tool along with the management component. Using that, you can deploy and configure the core and the storage components on the remote node. The main starting points of its usage are described in section Multi-node setup using the automated deployment tool.

4.1. Prerequisites

The followings are needed prior to the installation of Proxedo API Security:

  • the licence for PAS

  • a technical user for accessing Balasys' download site and docker registry

  • the PAS core and management .deb packages

    You can download the .deb packages from the Balasys Download website.
  • one or two servers with Ubuntu 18.04 Operating System installed. See Installation scenarios.

4.2. Installation scenarios

4.2.1. Standalone setup

In a standalone setup all of the components must be installed manually on the same node in the following order.

4.2.2. Multi-node setup

In a multi-node setup there will be a management node and another node with the core component. The storage component must be installed and configured on both nodes. The installation must be done in the following order.

  1. Management node

  2. Core node

    The core node can be set up with the automation tool or manually installing the components in the following order.

4.2.3. Multi-node HA setup

Multi-node HA setup is similar to the standard multi-node setup, but in this scenario the management node will run the core component, as well. The installation order is the following.

  1. Management node

  2. Core node

    Core node can be set up with the automation tool or manually installing the components in the following order.

The HA component is included in the core component, and it must be configured after the installation. See High availability configuration.

4.3. Installation steps for the storage component

  1. Log in as root.

  2. Update the OS' package list: apt update.

  3. Install the PAS storage .deb package: apt install <path/to/deb>/proxedo-api-security-storage_<version>.deb.

    This will:

    • Create a user named pas for running and configuring PAS.

      pas user must not be created manually beforehand.
    • Install the necessary configuration files and helper scripts under /opt/balasys.

    • Create systemd services for managing the PAS storage component.

      You need to use apt to install the .deb package locally as it installs its dependencies as well. dpkg will not resolve dependencies, and apt-get cannot install from a local file. Also note that to install PAS from the current directory, you must use the path ./ before the .deb package, or apt will try to download the package from a repository.
  1. Change to the PAS user: su - pas.

  2. Set up parameters in /opt/balasys/etc/infrastructure/storage/docker-compose.conf. For details, see docker-compose.conf.

  3. Run pas-storage-registry-login to set up authentication with the docker registry. Provide login credentials on the prompt. Contact support if you need assistance with your credentials.

    Docker will, by default, save your credentials unencrypted in the home directory of the pas user. Using a password-management tool like pass is not enforced, but it is recommended.
  4. Run pas-storage-update to download the docker images.

  5. Run pas-storage-consul-gossip-keygen to generate gossip encryption key, and note it down. This key will be needed for the startup configuration. See Configuration options for the storage component.

    This must be run only once, and the generated key must be used in the configuration of all storage components.
  6. Run pas-storage-consul-bootstrap-ca to generate CA certificate for storage-storage communication.

    This must be run only once on the management node. Do not execute it during the manual installation of the core node.
  7. Copy the generated CA certificate and key to the directory /opt/balasys/etc/storage.

  8. Run pas-storage-consul-gen-server-cert with --dns-name FQDN or with --ip-address IP parameter to generate the TLS certificate for storage-storage communication.

    FQDN is the domain name, IP is the IP address of the managament or the core node.

    There is no difference between using DNS or IP in the certificate, choose the one you prefer. Note, that in multi-node setup the same DNS or IP address must be used in join_hosts parameter of the storage component’s configuration, according to your choice.
    This must be run on the management node, even in the case of installing the core node in a multi-node setup.
  9. Copy the generated server certificate and key to the directory /opt/balasys/etc/storage.

  10. Set up startup configuration in /opt/balasys/etc/storage/config.yml.

  11. Run pas-storage-checkconfig to validate the configuration.

  12. Start PAS storage: systemctl start proxedo-api-security-storage.

    This service is enabled by default, so the service starts on system restart.

4.4. Installation steps for the management component

  1. Log in as root.

  2. Update the OS' package list: apt update.

  3. Install the PAS management .deb package: apt install <path/to/deb>/proxedo-api-security-mgmt_<version>.deb.

    This will:

    • Create a user named pas for running and configuring PAS.

      pas user must not be created manually beforehand.
    • Install the necessary configuration files and helper scripts under /opt/balasys.

    • Create systemd services for managing the PAS management component.

      You need to use apt to locally install the .deb package as it installs its dependencies as well. dpkg will not resolve dependencies, and apt-get cannot install from a local file. Also note that to install PAS from the current directory, you must use the path ./ before the .deb package, or apt will try to download the package from a repository.
  1. Change to the PAS user: su - pas.

  2. Set up MINIO_* parameters in /opt/balasys/etc/infrastructure/mgmt/docker-compose.conf. You can also modify other parameters if necessary, including port numbers and the version. For details, see docker-compose.conf.

    MINIO_* parameters must be the same as defined in the config.yml of the storage component.
  3. Run pas-mgmt-registry-login to set up authentication with the docker registry. Provide login credentials on the prompt. Contact support if you need assistance with your credentials.

    Docker will, by default, save your credentials unencrypted in the home directory of the pas user. Using a password-management tool like pass is not enforced, but it is recommended.
  4. Run pas-mgmt-update to download the docker images.

  5. Set up startup configuration in /opt/balasys/etc/mgmt/config.yml.

  6. Run pas-mgmt-checkconfig to validate the configuration.

  7. Start PAS management: systemctl start proxedo-api-security-mgmt.

    This service is enabled by default, so the service starts on system restart.

4.5. Installation steps for the core component

  1. Log in as root.

  2. Update the OS' package list: apt update.

  3. Install the PAS .deb package: apt install <path/to/deb>/proxedo-api-security_<version>.deb.

    This will:

    • create a user named pas for running and configuring PAS.

      pas user must not be created manually beforehand.
    • Install the necessary configuration files and helper scripts under /opt/balasys.

    • Create systemd services for managing PAS.

      You need to use apt to locally install the .deb package as it installs its dependencies as well. dpkg will not resolve dependencies, and apt-get cannot install from a local file. Also note that to install PAS from the current directory, you must use the path ./ before the .deb package, or apt will try to download the package from a repository.
  1. Change to the PAS user: su - pas.

  2. Set up MINIO_* parameters and the number of Flow Director instances to run in /opt/balasys/etc/infrastructure/pas/docker-compose.conf. If necessary, also change the version you want to follow. For details, see docker-compose.conf.

  3. Copy license.txt to /opt/balasys/etc/pas.

  4. Run pas-registry-login to set up authentication with the docker registry. Provide login credentials on the prompt. Contact support if you need assistance with your credentials.

    Docker will, by default, save your credentials unencrypted in the home directory of the pas user. Using a password-management tool like pass is not enforced, but it is recommended.
  5. Run pas-update to download the docker images.

  6. Start PAS: systemctl start proxedo-api-security.

    The core component will not start until a running configuration is set up through the management interface. To do it, please refer to Configuration of Proxedo API Security on the Web User Interface.
    This service is enabled by default, so the service starts on system restart.
  7. If you configured Certificate Revocation List (CRL) verification in any of your Backends or Listeners you need to enable CRL updates:

    sytemctl enable proxedo-api-security-crl-update.service
    sytemctl enable proxedo-api-security-crl-update.timer
    sytemctl start proxedo-api-security-crl-update.timer

4.6. Multi-node setup using the automated deployment tool

For a multi-node setup, you first need to have a functional management component installed on a node. Its storage needs to be set up to work in cluster with the node the core component is going to be deployed to. Along with the management component, you get the automated deployment tool that helps you manage your remote node and the core component on it.

4.6.1. Configuration

To deploy a core component on a remote node, the following prerequisites need to be met:

  • the core and the storage .deb packages on the management node

  • the license file on the management node

  • the ansible package installed on the management node (run apt install ansible)

  • a node with an Ubuntu installed

  • the python package installed on the remote node (run apt install python)

  • a generated TLS certificate for the storage-storage communication, see step 10 of Installation steps for the storage component

  • a user on the remote node which can run sudo without providing password

    As running sudo without a password grants virtually limitless privileges over the machine, it is strongly advised that SSH is only allowed using SSH keys.

To configure the automation and the remote nodes, you need to fill out three types of configuration files.

  • /opt/balasys/etc/automation/inventory.yml: The details of the nodes to deploy the core component to.

  • /opt/balasys/etc/automation/common_vars.yml: Variables that are common among all nodes.

  • /opt/balasys/etc/automation/host_vars: The directory holding variables for host-specific values. For each entry in inventory.yml, there must be a file in this directory. For example, if you have an entry named pas-node-1 in your inventory, you need to have a file named pas-node-1.yml in the host_vars directory.

The last step to do before you can deploy the core component on a remote node is to implement login. To do that

  1. Generate an SSH key.

    pas@pas-node-mgmt:~$ ssh-keygen -t rsa -b 4096 -C "pas-node-1"
  2. Add the SSH key to the user on the remote node which can run sudo without password.

    deployment@pas-node-1:~$ mkdir -p ~/.ssh
    deployment@pas-node-1:~$ cat <<generated_public_key_here>> >> ~/.ssh/authorized_keys
    deployment@pas-node-1:~$ chmod 700 ~/.ssh/
    deployment@pas-node-1:~$ chmod 600 ~/.ssh/authorized_keys

4.6.2. Deployment and remote management commands

To deploy core and manage it on the remote node, you need to run the pas-mgmt-deploy-core command. Running this command with different command line flags, you can execute different operations. See the list and explanation of possible operations as follows, or run pas-mgmt-deploy-core --help.

--deploy-core     Deploy the core component to all nodes. It will also be
                  started if not already running.
--restart-core    Restart the core component on all nodes. It will restart
                  ha-director as well.
--stop-core       Stop the core component on all nodes. It will stop
                  ha-director as well.
--deploy-ha       Deploy the HA component to all nodes. It will also be
                  started if not already running.
--restart-ha      Restart ha-director on all nodes.
--stop-ha         Stop ha-director on all nodes.
--sync-ntp        Copy NTP configuration to all nodes and restart the ntp
                  service.

5. Base system configuration

This chapter explains configuration details for setting up a working PAS. Configuration settings are detailed here, provided by the .deb packages installed on an Ubuntu 18.04 LTS server.

The .deb packages carry convenience tools for managing the Proxedo API Security core and the management component, the actual installation and execution is done by Docker and docker-compose.

5.1. Overview of configuration directories

PAS consists of multiple components and each may have multiple configuration files for both infrastructure definition and bootstrapping. In this section, a general overview is provided about how the corresponding configuration directories are structured.

As a rule of thumb, every configuration file for PAS is available under /opt/balasys/etc, and right after installation of all the components, the directory tree looks like the following.

Tree of initial configuration files
/opt/balasys/etc/
├── automation
│   ├── common_vars.yml -> ../../usr/share/automation/roles/deploy-core/vars/main.yml
│   ├── host_vars -> ../../usr/share/automation/host_vars
│   └── inventory.yml -> ../../usr/share/automation/inventory.yml
├── ha
│   └── config.yml
├── infrastructure
│   ├── ha
│   │   └── docker-compose.yml
│   ├── mgmt
│   │   ├── docker-compose.conf
│   │   └── docker-compose.yml
│   ├── pas
│   │   ├── docker-compose.conf
│   │   └── docker-compose.yml
│   └── storage
│       ├── docker-compose.conf
│       └── docker-compose.yml
├── mgmt
│   └── config.yml
├── pas
└── storage
    └── config.yml

In general, the following rules apply:

  • /opt/balasys/etc/infrastructure holds the files to describe the infrastructure, the component will run in. Exposed ports and used images are the two most important parameters set up in the files in this directory.

  • /opt/balasys/etc/{ha,mgmt,pas,storage} hold the bootstrap configuration of the respective components. By default, only configuration files are created, but certificates, the license file, etc. also reside in these directories. They will be mounted to the containers so that the processes can use these files as well.

  • /opt/balasys/etc/automation makes necessary configuration available for remote core deployment. As seen in the directory tree, files in this directory are symbolic links to ease access to the actual files. During debugging, or after installation, their original directories may also be useful to look at.

As there are more directories and subdirectories linked to each package, the following table defines the corresponding directories for each package.

Table 1. Directories grouped by package ownership
Package Directories

proxedo-api-security

  • /opt/balasys/etc/ha

  • /opt/balasys/etc/pas

  • /opt/balasys/etc/infrastructure/ha

  • /opt/balasys/etc/infrastructure/pas

proxedo-api-security-mgmt

  • /opt/balasys/etc/mgmt

  • /opt/balasys/etc/automation

  • /opt/balasys/etc/infrastructure/mgmt

proxedo-api-security-storage

  • /opt/balasys/etc/storage

  • /opt/balasys/etc/infrastructure/storage

5.2. config.yml

The main configuration of the storage, management and HA components is defined in the /opt/balasys/etc/storage/config.yml, /opt/balasys/etc/mgmt/config.yml and /opt/balasys/etc/ha/config.yml files.

The format of the files must adhere to the YAML 1.1 specification.

There are different sections in these configuration files, some of which, as for example, the 'common' section, might not need specific configuration. However, the default values of these sections must be set by {}. If any of the parameters in these configuration files must be set, it is indicated by the FILL instruction.

See configuration examples in Appendix B.

5.2.1. Configuration options for the storage component

The file /opt/balasys/etc/storage/config.yml controls:

  • Standalone or Multi-node setup

  • Storage intercommunication

  • Node name visible on Dashboard

  • MinIO keys

The configuration file has three main sections, namely common, consul and blob-store.

The 'common' section has no required parameters, the defaults can be set by {}.

Table 2. Storage configuration common options
Key Default Description

standalone_mode

false

This parameter denotes whether the storage is run in standalone or in cluster mode. If it is set to true, the cluster-related parameters are ignored. The required parameters still need to be provided.

Table 3. Storage configuration consul options
Key Default Description

bind_cluster_addr

It denotes the address to bind on as a cluster member. This will be used to communicate with other members. This is a required paramater.

gossip_encryption_key

This parameter denotes the encryption key to use for the gossip protocol. It is a 32-byte shared key encoded into base64 format. Use pas-storage-consul-gossip-keygen to generate it. The same value must be used on different nodes in a multi-node setup. This is a required paramater.

node_name

It denotes the name of the consul node. It must be unique in the cluster. This parameter sets the visible node name on the Status Dashboard. This is a recommended parameter.

log_level

INFO

It denotes the log level of consul. The possible values are: TRACE, DEBUG, INFO, WARN, ERR

server_tls

N/A

It denotes TLS settings for storage-storage communication. The certificates must be created using the pas-storage-consul-bootstrap-ca and pas-storage-consul-gen-server-cert scripts.

ca_path

consul-agent-ca.pem

This parameter denotes the path of the CA file relative to /opt/balasys/etc/storage/.

cert_path

dc1-server-consul-0.pem

This parameter denotes the path of the server cert file relative to /opt/balasys/etc/storage/.

key_path

dc1-server-consul-0-key.pem

This parameter denotes the path of the server key file relative to /opt/balasys/etc/storage/.

join_hosts

N/A

This parameter denotes the list of hosts to try, for joining the cluster. Either the hostname or the IP address can be specified, and a port number is also necessary. Do not specify on the first node of the cluster.

hostname

This parameter denotes the hostname of the storage node to join.

ip_address

This parameter denotes the IP address of the storage node to join.

port

8301

This parameter denotes the port used for the storage cluster. Do not modify it unless the port is changed in /opt/balasys/etc/infrastructure/storage/docker-compose.yml.

The options with ’N/A’ default value are such sections that cannot have exact values, only the values described afterwards in the table.
Table 4. Storage configuration blob-store options
Key Default Description

access_key

It denotes the access key used for connecting to MinIO. A preferably random generated string must be provided. Min length: 3 This is a required parameter.

secret_key

It denotes the secret key used for connecting to MinIO. A preferably random generated string must be provided. Min length: 8. This is a required parameter.

join_hosts

N/A

This is a list of hosts to try, for joining the cluster. Either of the hostname or the ip_address can be specified, and a port number is also necessary.

hostname

It denotes the hostname of the storage node to join.

ip_address

It denotes the IP address of storage nodes to join.

port

9000

This parameter denotes the port used for the storage cluster. Do not modify unless the port is changed in /opt/balasys/etc/infrastructure/storage/docker-compose.yml.

The options with ’N/A’ default value are such sections that cannot have exact values, only the values described afterwards in the table.

5.2.2. Configuration options for the management component

The file /opt/balasys/etc/mgmt/config.yml controls:

  • Web service parameters

  • Authentication

  • TLS settings

The configuration file has two main sections, namely frontend and configapi.

None of the sections has required parameters, defaults for whole sections can be set by {}.

Table 5. Management configuration frontend options
Key Default Description

server_name

_

It is the hostname the web server should serve the requests on. The default means that the management interface will be served regardless of the provided hostname.

tls

N/A

This section configures TLS settings.

certificate_path

/tmp/tls/default.crt

This parameter denotes the path to the server certificate. It most likely resides somewhere under /opt/balasys/etc/mgmt. The default path refers to an automatically generated certificate. It must not be trusted.

key_path

/tmp/tls/default.key

This parameter denotes the path to the server private key. It most likely resides somewhere under /opt/balasys/etc/mgmt. The default path refers to an automatically generated key. It must not be trusted.

hsts_max_age

63072000

This parameter denotes the maximum age attribute of the strict transport security header.

cors_api

N/A

This section configures cross origin request sharing options for API access.

allow_origin

It denotes the value of the Access-Control-Allow-Origin header. This is a required parameter in case of enabled CORS API.

The options with ’N/A’ default value are such sections that cannot have exact values, only the values described afterwards in the table.
Table 6. Management configuration configapi options
Key Default Description

ldap

N/A

This section configures the options for LDAP authentication. LDAP authentication is disabled by default.

ldap_url

It is the URL of the ldap server. It must start with ldap[s]://. This is a required parameter in case of LDAP authentication.

bind_user

It denotes the service user to use for searching the LDAP server. If use_ntlm parameter is off, this must be the whole DN. If it is on, it must be the username as expected by the service. This is a required parameter in case of LDAP authentication.

bind_password

It denotes the password of the service user. This is a required parameter in case of LDAP authentication.

use_ntlm

off

Set this parameter to 'on' to use NTLM authentication.

tls_version

TLSv1_2

TLS version for the ldaps connection. Must be one of: SSLv23, TLS, TLS_CLIENT, TLS_SERVER, TLSv1, TLSv1_1, TLSv1_2

validate_cert

no

Set yes to validate certificates.

server_cert

It is the server’s certificate to trust.

user_base_dn

It is the base DN under which users reside. This is a required parameter in case of LDAP authentication.

username_attribute

sAMAccountName

It is the attribute that contains the name of the user.

user_object_type

It is the attribute type for users.

memberof_attribute

memberof

It is the attribute that contains membership information (groups) on user objects.

group_base_dn

It is the base DN under which groups reside. This is a required parameter in case of LDAP authentication.

groupname_attribute

name

It is the attribute that contains the name of the group.

member_attribute

It is the attribute that contains membership information (users) on group objects.

group_object_type

group

It is the attribute type for groups.

allowed_groups

It is a list of group names (as contained by 'groupname_attribute') allowed to log in. This is a required parameter in case of LDAP authentication.

session

N/A

This section configures the options for session lifetimes.

session_validity

7200

It denotes the allowed lifetime of a login session token in seconds. It determines the time period between group membership and user existence checks. This DOES NOT control the length of a user session.

renew_validity

36000

It denotes the validity of the renew token. It determines how long session tokens can be renewed. Therefore the maximum length of a user session is the sum of the two parameters.

htpasswd

N/A

This section configures the htpass authentication.

htpasswd_file

/opt/balasys/etc/mgmt/users.htpass

It denotes the path of the htpass file inside the config-api container.

The options with ’N/A’ default value are such sections that cannot have exact values, only the values described afterwards in the table.

5.2.3. Configuration options for the HA component

The file /opt/balasys/etc/ha/config.yml controls:

  • HA settings

The configuration file has a single section called ha, which does not have default values.

Table 7. HA configuration ha options
Key Default Description

interface

The network interface to use for VRRP communication.

virtual_router_id

1

The router ID to use in VRRP messages. Min: 1; Max: 255

priority

The VRRP priority of the node in the virtual router instance. Min: 1; Max: 254. One node needs to have a priority higher by 50 compared to all other nodes. For example: If the highest priority node has a priority of 150, all other nodes must have a priority of 100 or lower.

auth_pass

The authentication password to use in the VRRP protocol. It is an alphanumerical string of up to 8 characters.

virtual_ip

The virtual IP address to use for HA.

5.3. docker-compose.yml

The main configuration of the running environment is defined in the /opt/balasys/etc/infrastructure/storage/docker-compose.yml, /opt/balasys/etc/infrastructure/pas/docker-compose.yml and /opt/balasys/etc/infrastructure/mgmt/docker-compose.yml files. They describe the containers running PAS.

The format of the files must adhere to the YAML 1.1 specification. For a brief overview of the YAML format look at the example here. For an in-depth reference of docker-compose configuration see its documentation.

This file controls:

  • the images to run the container from

  • the persistent data storage (docker volumes) to attach to the containers

  • the ports propagated to the containers

  • the environment variables available inside the containers

  • intra container communication channels (links)

  • log target configuration

Unless inevitable, you should not modify these files. There are two cases when you might need to.

  1. If you need to modify the provided environment to debug your setup.

  2. If you need to change the default behavior of logging into the system’s journal you must change the logging parameters under all the services. See more details in docker-compose’s documentation.

If you modify these files, they will not be overwritten on package upgrade. Only interactive installs will notify you.
Do not use docker-compose directly to manage the installation. Always use systemctl as it handles dependencies and scaling.

5.4. docker-compose.conf

Some aspects of how the services are run by docker-compose are configured through /opt/balasys/etc/infrastructure/storage/docker-compose.conf, /opt/balasys/etc/infrastructure/pas/docker-compose.conf and /opt/balasys/etc/infrastructure/mgmt/docker-compose.conf.

The format of this file is a shell environment file format: a key-value pair in each line, separated by an equal sign ("=").

There must not be spaces around the equal sign.

The configuration files of different components have a common portion along with other parameters that are only valid in one of them. For details, see the following tables.

There are no storage-specific configuration options.
Table 8. docker-compose.conf configuration common options
Key Default Description

PAS_IMAGE_TAG

3.0.latest

The release track of Proxedo API Security to use. See Tracking version.

COMPOSE_FILE

/opt/balasys/etc/infrastructure/pas/docker-compose.yml or /opt/balasys/etc/infrastructure/mgmt/docker-compose.yml

Path to the compose file. You must not modify the default value.

COMPOSE_PROJECT_NAME

pas

Name used for the compose project. They must be kept synchronized over different files.

PAS_DOCKER_REGISTRY

docker.balasys.hu

It is the domain name of the docker registry to download images from.

Table 9. docker-compose.conf configuration management-specific options
Key Default Description

PAS_MGMT_WEBUI_HTTP_PORT

80

It is the port to expose for HTTP access of the management web user interface.

PAS_MGMT_WEBUI_HTTPS_PORT

443

It is the port to expose for HTTPS access of the management web user interface.

MINIO_ACCESS_KEY

It is the access key to be used for MinIO authentication. It must be the same as defined in /opt/balasys/etc/storage/config.yml.

MINIO_SECRET_KEY

It is the secret key to be used for MinIO authentication. It must be the same as defined in /opt/balasys/etc/storage/config.yml.

Table 10. docker-compose.conf configuration core-specific options
Key Default Description

PAS_FLOW_DIRECTOR_SCALE

1

It defines the number of Flow Director instances to run. For details, see Scaling Flow Director.

PAS_TRANSPORT_DIRECTOR_PORT_RANGE1

49000-49100

It is a port range to expose to Transport Director. Listeners will work in this port range.

PAS_TRANSPORT_DIRECTOR_PORT_RANGE2

49101-49200

It is an additional port range to expose to Transport Director. Listeners will work in this port range.

MINIO_ACCESS_KEY

It is the access key to be used for MinIO authentication. It must be the same as defined in /opt/balasys/etc/storage/config.yml.

MINIO_SECRET_KEY

It is the secret key to be used for MinIO authentication. It must be the same as defined in /opt/balasys/etc/storage/config.yml.

Storage example:

PAS_IMAGE_TAG=3.0.latest
COMPOSE_FILE=/opt/balasys/etc/infrastructure/mgmt/docker-compose.yml
COMPOSE_PROJECT_NAME=pas
PAS_DOCKER_REGISTRY=docker.balasys.hu

Management example:

PAS_IMAGE_TAG=3.0.latest
COMPOSE_FILE=/opt/balasys/etc/infrastructure/mgmt/docker-compose.yml
COMPOSE_PROJECT_NAME=pas
PAS_DOCKER_REGISTRY=docker.balasys.hu

PAS_MGMT_WEBUI_HTTP_PORT=80
PAS_MGMT_WEBUI_HTTPS_PORT=443

MINIO_ACCESS_KEY=your_minio_access_key
MINIO_SECRET_KEY=your_minio_secret_key

Core example:

PAS_IMAGE_TAG=3.0.latest
COMPOSE_FILE=/opt/balasys/etc/infrastructure/mgmt/docker-compose.yml
COMPOSE_PROJECT_NAME=pas
PAS_DOCKER_REGISTRY=docker.balasys.hu
PAS_FLOW_DIRECTOR_SCALE=1

PAS_TRANSPORT_DIRECTOR_PORT_RANGE1=49000-49100
PAS_TRANSPORT_DIRECTOR_PORT_RANGE2=49101-49200

MINIO_ACCESS_KEY=your_minio_access_key
MINIO_SECRET_KEY=your_minio_secret_key
Changing any of the values requires the restart of the service.

5.5. PAS restart policy

PAS service lifecycle is managed by systemd and is by default set to restart if any of the components fails at any point. To avoid infinite restarting, the number of restarts within a short period of time is also limited. As a result, if PAS core or management stops with a non-zero exit code 3 times within 100 seconds, the corresponding systemd unit will enter failed state.

The default restart policy and the options are identical for the storage, core and management components.

The relevant part of the service file looks as follows:

[Unit]
StartLimitIntervalSec=100
StartLimitBurst=3

[Service]
Restart=on-failure

Modifying the restart policy is possible by editing the service file in override mode. To do so, run systemctl edit proxedo-api-security-storage, systemctl edit proxedo-api-security or systemctl edit proxedo-api-security-mgmt. This will open a text editor and will let you define the parameters you wish to override. For example, if you want to switch off all default restart settings, enter the following text in the override editing window:

[Unit]
StartLimitIntervalSec=
StartLimitBurst=

[Service]
Restart=no

Possible values for Restart= are documented by systemd. We recommend using no to avoid automatic restarting by systemd or on-failure to make the service restart on non-zero exit codes. If you want a more fine-tuned restart policy, please consult the systemd.service(5) man page and configure the desired options.

To discard your overrides, run systemctl revert proxedo-api-security-storage, systemctl revert proxedo-api-security or systemctl revert proxedo-api-security-mgmt.

You only need to enter the parameters you want to change.
Overriding systemd units is only possible as root user.

5.6. Tracking version

Proxedo API Security has a version number in the form of major.minor.patch. The docker image labels control how the automatic update of the services are handled. Each image has 3 possible tags:

  • MAJOR.latest (for eg. 1.latest): These tags point to the latest release in the major release. That is, for the release of both x.y.z+1 and x.y+1.0, this tag will be updated, and the services will be upgraded at the restarts. There will not be upgrades for x+1.0.0.

  • MAJOR.MINOR.latest (for eg. 1.3.latest): These tags point to the latest release in the minor release. That is, for the release x.y.z+1, this tag will be updated, and the services will be upgraded at restarts, however not for the release x.y+1.0.

  • MAJOR.MINOR.PATCH (for e.g. 1.4.7): These tags point to a specific release and will never be changed once released.

5.7. Scaling Flow Director

A single instance of Flow Director uses a single processor core. It is necessary to adjust the number of instances to use all the available cores. This is controlled by the PAS_FLOW_DIRECTOR_SCALE variable. As the Flow Director handles the most demanding duties among the components, it must be assigned most of the cores. If there are up to four cores available, assign three cores to the Flow Director, and the remaining one core will be suitable for the Transport and Insight Director. If there are more than four cores, assign two cores for the Transport and Insight Director and assign the rest to the Flow Director.

5.8. Configuration of dockerd

The docker daemon is configured through /etc/docker/daemon.json. The full documentation can be found in the official docker documentation.

Balasys recommends the use of the default configuration.

Do not use /etc/default/docker as it is ignored when systemd is used.

5.9. High availability configuration

5.9.1. HA Director

The HA functionality is implemented by the HA Director included in the core component. It uses keepalived in VRRP mode to provide the service.

It can be configured in two ways:

  1. When installed and configured manually on the host running core, the configuration file /opt/balasys/etc/ha/config.yml should be filled out.

  2. When installed using the automation tool, the following configuration files need to be filled in on the management node:

    • /opt/balasys/etc/automation/common_vars.yml: Common HA parameters to be used on remote hosts.

    • /opt/balasys/etc/automation/host_vars: Host-specific HA parameters to be used on remote hosts.

As at the moment, only clusters of two are supported, you can only implement HA by installing core alongside the management component as well. That instance you need to configure and set up manually, while you can use the automated deployment tool to deploy core and HA on the remote node.

5.9.2. HA restart policy

PAS service lifecycle is managed by systemd and is by default set to restart if any of the components fails at any point. To avoid infinite restarting, the number of restarts within a short period of time is also limited. As a result, if PAS core or management stops with a non-zero exit code 3 times within 100 seconds, the corresponding systemd unit will enter failed state.

The default restart policy and the options are identical for the storage, core and management components.

The relevant part of the service file looks as follows:

[Unit]
StartLimitIntervalSec=100
StartLimitBurst=3

[Service]
Restart=on-failure

Modifying the restart policy is possible by editing the service file in override mode. To do so, run systemctl edit proxedo-api-security-storage, systemctl edit proxedo-api-security or systemctl edit proxedo-api-security-mgmt. This will open a text editor and will let you define the parameters you wish to override. For example, if you want to switch off all default restart settings, enter the following text in the override editing window:

[Unit]
StartLimitIntervalSec=
StartLimitBurst=

[Service]
Restart=no

Possible values for Restart= are documented by systemd. We recommend using no to avoid automatic restarting by systemd or on-failure to make the service restart on non-zero exit codes. If you want a more fine-tuned restart policy, please consult the systemd.service(5) man page and configure the desired options.

To discard your overrides, run systemctl revert proxedo-api-security-storage, systemctl revert proxedo-api-security or systemctl revert proxedo-api-security-mgmt.

You only need to enter the parameters you want to change.
Overriding systemd units is only possible as root user.

5.10. Setting up time synchronization

To ensure time synchronization on different nodes you need to configure NTP on them. The ntp package is already installed as a dependency, but it must be configured We recommend adding the following configuration to /etc/ntp.conf.

driftfile /var/lib/ntp/ntp.drift

restrict -4 default kod notrap nomodify nopeer noquery limited
restrict -6 default kod notrap nomodify nopeer noquery limited
restrict 127.0.0.1
restrict ::1

server time.nist.gov prefer
server ip-time-1.cern.ch
Use your own NTP servers in the server directives if you have any, or adjust the given values to ones that are allowed by your policies.

After creating the configuration, run the following commands.

# Disable systemd-timesyncd
timedatectl set-ntp false

# Restart ntp
systemctl restart ntp

# Enable ntp so that it starts on system startup
systemctl enable ntp

6. Configuration of Proxedo API Security on the Web User Interface

This chapter explains configuration details for setting up a working Proxedo API Security (PAS) with the help of the Web User Interface.

The Proxedo API Security Web User Interface (UI) is installed together with the installation of Proxedo API Security. The URL for Proxedo API Security Web UI and the necessary credentials are defined by the administrator during the initial configuration of Proxedo API Security.

6.1. Minimum configuration

It is possible to run PAS with a minimum, basic configuration. For a minimum configuration the following items need to be configured in the Web UI:

This basic configuration can be further improved with the completion of more configuration units later. The minimum configuration can also be used to test the installation settings.

6.2. Login Page

The main component of the Login page is the login form where the user needs to provide the credentials in order to be authorized to use the Web UI of Proxedo API Security.

As part of the initial configuration of Proxedo API Security, the administrator defines the necessary credentials, which can now be used.