Proxedo API Security in Kubernetes: Administration Guide

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 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.

2024-05-13 .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.

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.

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 in Kubernetes. 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
evaluate the level of risk with regards to the API call using the data collected from call data
provide rule-based protection against a variety of web-based application layer attacks
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:

To understand what the product does and how, see Overview of Proxedo API Security.
- If you are familiar with API terminology jump right to Architecture for Proxedo API Security.
See Installation of Proxedo API Security in Kubernetes environment if you need to set up a new PAS.
The Operation of Proxedo API Security in Kubernetes environment chapter is about how to manage a working system on the level of the operating system.
Configuration of Proxedo API Security on the Web User Interface contains in-depth information about everything that can be configured with the help of the Web User Interface.
If you are already familiar with the system and need to find a component that suits your needs consult the Matcher types, Comparators, Extractor types or Insight Target.

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 endpoint’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. Fraud Detection

The Fraud Detection module of Proxedo API Security reduces the number of fraudulent transactions by harnessing device fingerprinting and enriching incoming data with alternate sources to provide the best accuracy and details about transactions.

3.1.4. Rule-based Enforcement

Besides its positive security model approach, Proxedo API Security also has a web application firewall module. The WAF Enforcer protects against a variety of application layer attacks including credential theft, code injection, cross-site scripting (XSS), cookie poisoning, CSRF, SQL injection, DoS, ransomware, and more.

3.1.5. 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.6. 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.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. TLS encryption can also be used with Syslog Insight Target and Elastic Insight Target.

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: 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: A Plugin responsible for compressing the result of a flow and forwarding the compressed content.
Deserializer: 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: A Plugin responsible for serializing the structured data to the format of the HTTP message’s body.
Filter: A Plugin that rejects calls when they match defined rules.
Enforcer: A Plugin that validates calls against externally defined schemas.
Insight: 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.
Insight Target: It is a brick that defines an external system to send extracted data to. It is used by Insight plugins.

3.3. Architecture for Proxedo API Security

Proxedo API Security is based on a micro-services architecture separated into three deployment units: Management, Storage, and Core. These deployment units (or infrastructure components) can be scaled or moved between hosts to accommodate different throughput and reliability requirements.

3.3.1. Management component

Responsible for handling the security component configuration of the Core component, while the data itself resides in the Storage component. Contains the following services:

Config API

Exposes a configuration API that can be used to manage the product:

Editing the security component configuration
Applying the security component configuration

Config WebUI

Provides a browser-based user interface to the configuration API.

3.3.2. Storage component

Stores and distributes different versions of the security component configuration to the Core component. Contains the following services:

Consul: Stores the different versions of the security component configuration, and monitors the status of PAS services.
Blob Store: Stores file resources that are part of the security component configuration.

3.3.3. Core component

The Core services are each responsible for a well-defined subset of handling traffic between the client and the backend. Contains the following services:

Transport Director

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

Responsible for the execution of the Plugins in the Endpoints' flow and for applying Error Policies as necessary.

Insight Director

Manages the connections to Insight Targets. Responsible for sending the data collected by Insight plugins to Insight Target systems.

Content Filtering Director

Provides content filtering capabilities for the WAF Enforcer plugin.

3.3.4. The configuration process

While the configuration most commonly takes place on the Web UI, the process works the same way through the configuration API.

When a user logs in to the Web UI, the currently running configuration is visible.
- When logging in to the Web UI for the first time after a fresh install, the current configuration is empty. Only a few mandatory and default components are added, and some mandatory components must be added to the configuration for the first configuration to become valid.
- The running configuration is always stored in the Storage component.
The user can edit the configuration: add new components, delete existing components, and change fields on existing components.
- The changes the user makes are only visible to the user, other users can only see the running configuration and their own changes.
- The user’s changes are always stored in the Storage component.
Individual components and the configuration as a whole are validated.
- Partially configured components can be saved with missing fields, but they won’t become valid until all mandatory fields are properly filled.
- An invalid configuration is still saved, and can be fixed at a later time. Every user has their own set of changes.
When the configuration is valid, it can be applied to the running system.
- When a user’s configuration is applied, the changes are merged with the running configuration.
- Applying the changes means reloading the Core services with the new configuration.
- The new running configuration becomes visible to every user.

3.3.5. Connection handling example

Figure 1. PAS Architecture

Incoming connections are accepted by the Transport Director.
- It handles TLS with the client if necessary.
- Chooses the Endpoint based on the URL.
It hands over the connection to the Flow Director.
- The Flow Director applies the Endpoint specific Request Security Flow.
If an Insight plugin needs to send data to an external Insight Target it sends the collected data to the Insight Director.
The Insight Director sends the data further to the Insight Target with the appropriate protocol.
If a WAF Enforcer plugin is present in the Request Security Flow it sends data to the Content Filtering Director and receives a verdict.
If a Fraud Detector plugin is present in the Request Security Flow it sends data to the external Fraud API and receives a score.
The Flow Director hands the connection back to the Transport Director.
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.6. 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:

Figure 2. PAS processing flow

As shown in the figure above, the incoming connection from the client is handled by the Transport Director, applying TLS if needed.
The Transport Director then chooses the Endpoint based on the URL in the request. First endpoint that has a matching URL is chosen.
The Transport Director hands over the connection to the Flow Director, indicating which Endpoint the connection belongs to.
The Flow Director then starts applying the request part of the Security Flow definition.
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.
Once the last Plugin has been executed the connection is handed back to the Transport Director.
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.
The Backend server sends its response to the Transport Director.
Once, the response has been received the Transport Director again hands over the connection to the Flow Director.
The Flow Director then starts applying the response part of the Security Flow definition, executing the Plugins as above.
Once, the last Plugin has been executed the connection is handed back to the Transport Director.
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.

4. Installation of Proxedo API Security in Kubernetes environment

The forthcoming sections describe the installation of PAS in Kubernetes.

To manage Kubernetes (K8s) applications, Helm, the package manager for Kubernetes is used. Packages are called charts in the Helm context.

4.1. Prerequisites for installing PAS

The followings are needed prior to the installation of PAS:

the license file for PAS
a technical user for accessing Balasys' download site
the Helm chart

Prior to the installation of the Helm chart, the Helm chart itself must be configured. For minimum configuration of the Helm chart see section Minimum configuration settings for the Helm chart.

4.1.1. Cluster components necessary for PAS

To make use of some of the features, PAS shall be deployed in a cluster, with the following components installed:

metrics server for auto-scaling
Persistent volume for storing configuration in the management component

Persistent Volume Claim parameters can be set up to match a manually managed Persistent volume, so is Storage Class name.

access for the target namespace to deploy PAS in

4.1.2. Tools necessary for the installation

To create the basic configuration for the installation, the following tools are necessary:

openssl for storage certificate generation
the htpasswd tool, which is part of the apache2-utils package on debian distributions, the httpd-tools package on Red Hat based distributions
the helm command line tool to manage the package installation
the kubectl command line tool to communicate with the Kubernetes cluster

4.1.3. Minimum configuration settings for the Helm chart

The Helm chart contains the following:

configuration parameters to bootstrap PAS in K8s
definitions of
- pods
- services
- autoscaling configuration for the core component
- a Persistent Volume Claim for the management

Ingress configuration for any component is not included.

HTTP and HTTPS management access is recommended to be configured using an Ingress (kubernetes object).

In order to be able to install the Helm chart the minimum configuration settings have to be completed. The following sections contain the details only for the necessary minimum configuration, however for checking further possible configuration options, see section Base system configuration for PAS in Kubernetes.

The files detailed in the next sections need to be created and filled in prior to PAS installation.

4.1.3.1. Using values.yml file

Use the values.yml (values file) with the default and necessary values. Run the following command to output the configuration options:

helm show values /path/to/chart/proxedo-api-security-4.10.0.tgz

Create a local values.yml file with the preferred values to overwrite the default values if required. The values file with minimum configuration is as follows (with example values):

config:
  storage:
    consul:
      gossip_encryption_key: MhstT80sqle63WC7knOak+c7GfK7k5OY2n/4Qk/fSXs=
    blob_store:
      access_key: "8i8YJB3JhFmkT5KK6EV5EGw9dK10B4ZllWjEYlvUwKM="
      secret_key: "L/aLsKkoDFDFnMNdp8MFl1/CIkAQC1hrXV+HlbgKyOM="

Generate these necessary secrets with the help of the following command. The values above are examples, they shall not be copied directly.

# config.consul.gossip_encryption_key
$ openssl rand -base64 32
gI97yg2Zcq4XL20ne8NBwH2e0PbzkmXjqMFdp8jQZac=

# config.blob_store.access_key
$ openssl rand -base64 32
+WDpoDV7EcJrgkRgK65M3y8OcLdrZmYBASVTFE1I8pg=

# config.blob_store.secret_key
$ openssl rand -base64 32
ECuGiOwyJtjlB8Bl3yNgIgdk/nlb4HFmxE/4oiq5V+w=

4.1.3.2. Creating certificates for storage

For technical reasons, a TLS certificate is necessary for configuration storage purposes. Create the internal CAs and signed certificates either with a preferred method, or else the necessary files can be created with the following example commands as well.

Generate a CA key pair.

The -days parameter in the example commands define the validity period of the generated certificates in days. Change it, if it is required.

The certificate files generated here and used with the Helm chart are sensitive pieces of information, therefore handle those with attention.

openssl req -nodes -new -x509 -days +3650 -keyout storage-ca-key.pem -out storage-ca.pem -subj "/CN=PAS Storage CA"

Generate a private server key and a Certificate Signing Request (CSR).

openssl req -nodes -new -keyout consul-0-key.pem -out consul-0.csr -days +3650 -subj "/CN=storage.pas"

Sign the CSR using the CA.

openssl x509 -req -days +3650 -in consul-0.csr -CA storage-ca.pem -CAkey storage-ca-key.pem -CAcreateserial  -out consul-0.pem

With the help of the above examples, further files need to be generated. These files will need to be provided for the Helm chart:

consul-0.csr
consul-0-key.pem
consul-0.pem
storage-ca-key.pem
storage-ca.pem

4.1.3.3. Creating management users' file

For logging into the management component, the users.htpass file is required. Run the following command to generate one, and provide the password.

htpasswd -B -c users.htpass username

4.2. Installing PAS in Kubernetes

The following sections and the example commands use the proxedo-api-security kubernetes namespace as an example, but it can be replaced with any other namespace name.

It is recommended to install PAS in a namespace separate from the backend application(s).

To create a new namespace, run the following command:

kubectl create namespace proxedo-api-security

4.2.1. Setting up docker registry connection

Log in to the PAS docker registry to access the docker images of PAS.
Create the proxedo-api-security-registry-credentials secret using the following command to enable kubernetes to access the docker images:

kubectl create --namespace proxedo-api-security \
    secret docker-registry proxedo-api-security-registry-credentials \
    --docker-server=docker.balasys.hu \
    --docker-username=<<your username>> \
    --docker-password="$(read -sp "Docker registry password: " DOCKER_PASSWORD; echo $DOCKER_PASSWORD)"

4.2.2. Providing the necessary files for Helm installation

Provide the created files for the Helm install command, an example of which can be seen below (substitute your values):

helm upgrade --install proxedo-api-security --namespace=proxedo-api-security \
    --values /path/to/config/files/values.yml \
    --set-file license=/path/to/config/files/license.txt \
    --set-file mgmt_users=/path/to/config/files/users.htpass \
    --set-file storage_ca_key=/path/to/config/files/storage-ca-key.pem \
    --set-file storage_ca_cert=/path/to/config/files/storage-ca.pem \
    --set-file storage_server_key=/path/to/config/files/consul-0-key.pem \
    --set-file storage_server_cert=/path/to/config/files/consul-0.pem \
    /path/to/chart/proxedo-api-security-4.10.0.tgz

4.3. Verifying the installation of PAS in Kubernetes

If everything is correct, the Helm command will present the following output:

NAME: proxedo-api-security
LAST DEPLOYED: Mon May  2 13:51:46 2022
NAMESPACE: proxedo-api-security
STATUS: deployed
REVISION: 1
TEST SUITE: None

Run the kubectl get pods --namespace=proxedo-api-security --selector=app=proxedo-api-security command to investigate the running pods. The output shall be similar to the following example:

NAME                                                              READY   STATUS              RESTARTS   AGE
proxedo-api-security-blob-store-86ccc6d864-frc5k                  1/1     Running             0          40s
proxedo-api-security-config-api-76d587d6cd-wpw5d                  1/1     Running             0          40s
proxedo-api-security-consul-68c5c87f75-mvlct                      1/1     Running             0          40s
proxedo-api-security-content-filtering-director-55b859df9-sztwp   1/1     Running             0          40s
proxedo-api-security-flow-director-5cddf58677-qxczd               0/1     ContainerCreating   0          40s
proxedo-api-security-frontend-676bfd8956-qrtm4                    1/1     Running             0          40s
proxedo-api-security-insight-director-585cc5f86-j8rrz             0/1     ContainerCreating   0          40s
proxedo-api-security-transport-director-5bbdf58d7d-whzsq          0/1     ContainerCreating   0          40s

The core pod is missing the core configuration, therefore it will not enter the "Running" state until the first configuration is applied in the management.

Run the following command to access the management component for verification.

kubectl port-forward --namespace=proxedo-api-security service/proxedo-api-security-frontend 8080:80

Open the http://127.0.0.1:8080/ in the browser.

5. Base system configuration for PAS in Kubernetes

This chapter explains configuration details for setting up a working PAS. Configuration settings are detailed here, which are based on the installation of the Helm chart.

The Helm chart carries Kubernetes manifest files for each component, and requires a set of parameters to be configured by the user for the installation.

The values.yml file

The configuration of PAS components is condensed into a values.yml file. The default version of this file can be printed by using the following command:

helm show values /path/to/chart/proxedo-api-security-4.10.0.tgz

To configure the necessary parameters and to overwrite the not suitable default values, save the output to a file, and keep only those parts that has to be overwritten. The modified file can be provided as --values my-values.yml to the Helm installation command.

There are two main sections of this file:

Infrastructure - This section defines the options necessary for kubernetes to deploy the components.
Configuration - This section defines the options for PAS itself. The main configuration of the storage and management components is defined in this file.

The format of this file must adhere to the YAML 1.1 specification.

There are different sections in this configuration file, some of which, as for example, the 'config.mgmt.frontend' section, might not need specific configuration. However, the default values of these sections must be set by {}.

For information on how to provide the custom values.yml file, see section Providing the necessary files for Helm installation. See configuration examples in Appendix B.

5.1. Infrastructure configuration

In this infrastructure part of the configuration, many parameter fields are directly associated with the configuration attributes defined for the Kubernetes objects. For such parameters that have a Kubernetes equivalent, the Kubernetes parameter is referenced in the format that can directly be used with the kubectl explain command. This command provides the most specific documentation of each field. However, for using this command, access to a cluster is required.

In case it is not feasible to use the kubectl explain command, the referenced format can also be used to navigate to the correct object and field at the following site: Kubernetes API.

The following tables describe the infrastructure parameters and their Kubernetes equivalent if that exists.

Table 1. Docker-related parameters
Parameter field	Default value	Description
infrastructure.docker.registry	docker.balasys.hu	The registry to download docker images from.
infrastructure.docker.pull_policy	IfNotPresent	This parameter has a Kubernetes equivalent in all pods: pod.spec.containers.
infrastructure.docker.image_tag		The image tag to use instead of the one corresponding to the current PAS version.

Table 2. Storage-related infrastructure parameters
Parameter field	Default value	Description
infrastructure.storage.volume_claim		This parameter has a Kubernetes equivalent: PersistentVolumeClaim.
infrastructure.storage.storage_class_name		This parameter has a Kubernetes equivalent: PersistentVolumeClaim.spec.storageClassName.
infrastructure.storage.access_modes	ReadWriteOnce	This parameter has a Kubernetes equivalent: PersistentVolumeClaim.spec.accessModes.
infrastructure.storage.requests		This parameter has a Kubernetes equivalent: PersistentVolumeClaim.spec.resources.requests.
infrastructure.storage.requests.storage	100Mi	This parameter has a Kubernetes equivalent: PersistentVolumeClaim.spec.resources.requests.storage.

Table 3. Blob-store infrastructure parameters
Parameter field	Default value	Description
Resources
infrastructure.storage.blob_store.resources		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.
infrastructure.storage.blob_store.resources.autofill_limits	false	When true and limits are not defined, limits will be the same as the requests. When false and limits are not defined, there are no limits. Setting limits overrides this setting.
infrastructure.storage.blob_store.resources.limits		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits. If this is defined, either a CPU limit value, a memory limit value, or both must be provided.
infrastructure.storage.blob_store.resources.limits.cpu		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.cpu.
infrastructure.storage.blob_store.resources.limits.memory		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.memory.
infrastructure.storage.blob_store.resources.limits.ephemeral_storage		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.ephemeral-storage.
infrastructure.storage.blob_store.resources.requests		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.
infrastructure.storage.blob_store.resources.requests.cpu	350 m	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.cpu.
infrastructure.storage.blob_store.resources.requests.memory	450 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.memory.
infrastructure.storage.blob_store.resources.requests.ephemeral_storage	50Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.ephemeral-storage.

Table 4. Consul infrastructure parameters
Parameter field	Default value	Description
Resources
infrastructure.storage.consul.resources		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.
infrastructure.storage.consul.resources.autofill_limits	false	When true and limits are not defined, limits will be the same as the requests. When false and limits are not defined, there are no limits. Setting limits overrides this setting.
infrastructure.storage.consul.resources.limits		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits. If this is defined, either a CPU limit value, a memory limit value, or both must be provided.
infrastructure.storage.consul.resources.limits.cpu		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.cpu.
infrastructure.storage.consul.resources.limits.memory		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.memory.
infrastructure.storage.consul.resources.limits.ephemeral_storage		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.ephemeral-storage.
infrastructure.storage.consul.resources.requests		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.
infrastructure.storage.consul.resources.requests.cpu	350 m	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.cpu.
infrastructure.storage.consul.resources.requests.memory	450 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.memory.
infrastructure.storage.consul.resources.requests.ephemeral_storage	50 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.ephemeral-storage.

Table 5. Transport Director infrastructure parameters
Parameter field	Default value	Description
Service
infrastructure.core.transport_director.service		This parameter has a Kubernetes equivalent: service.
infrastructure.core.transport_director.service.type	ClusterIP	This parameter has a Kubernetes equivalent: service.spec.type.
infrastructure.core.transport_director.service.ports		This parameter has a Kubernetes equivalent: service.spec.ports. A port with a specific target_port value needs to be set up for each listener port in the PAS configuration on the management interface.
infrastructure.core.transport_director.service.ports.name	HTTP	This parameter has a Kubernetes equivalent: service.spec.ports.name.
infrastructure.core.transport_director.service.ports.port	80	This parameter has a Kubernetes equivalent: service.spec.ports.port.
infrastructure.core.transport_director.service.ports.protocol	TCP	This parameter has a Kubernetes equivalent: service.spec.ports.protocol.
infrastructure.core.transport_director.service.ports.target_port	49 000	This parameter has a Kubernetes equivalent: service.spec.ports.targetPort.
infrastructure.core.transport_director.service.ports.node_port		This parameter has a Kubernetes equivalent: service.spec.ports.nodePort.
Resources
infrastructure.core.transport_director.resources		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.
infrastructure.core.transport_director.resources.autofill_limits	false	When true and limits are not defined, limits will be the same as the requests. When false and limits are not defined, there are no limits. Setting limits overrides this setting.
infrastructure.core.transport_director.resources.limits		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits. If this is defined, either a CPU limit value, a memory limit value, or both must be provided.
infrastructure.core.transport_director.resources.limits.cpu		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.cpu.
infrastructure.core.transport_director.resources.limits.memory		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.memory.
infrastructure.core.transport_director.resources.limits.ephemeral_storage		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.ephemeral-storage.
infrastructure.core.transport_director.resources.requests		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.
infrastructure.core.transport_director.resources.requests.cpu	250 m	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.cpu.
infrastructure.core.transport_director.resources.requests.memory	450 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.memory.
infrastructure.core.transport_director.resources.requests.ephemeral_storage	50 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.ephemeral-storage.
Scaling
infrastructure.core.transport_director.scaling		For scaling parameters, see the separate table on scaling, Parameters for Scaling - Transport Director, Flow Director, Insight Director.

Table 6. Flow Director infrastructure parameters
Parameter field	Default value	Description
Resources
infrastructure.core.flow_director.resources		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.
infrastructure.core.flow_director.resources.autofill_limits	false	When true and limits are not defined, limits will be the same as the requests. When false and limits are not defined, there are no limits. Setting limits overrides this setting.
infrastructure.core.flow_director.resources.limits		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits. If this is defined, either a CPU limit value, a memory limit value, or both must be provided.
infrastructure.core.flow_director.resources.limits.cpu		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.cpu.
infrastructure.core.flow_director.resources.limits.memory		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.memory.
infrastructure.core.flow_director.resources.limits.ephemeral_storage		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.ephemeral-storage.
infrastructure.core.flow_director.resources.requests		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.
infrastructure.core.flow_director.resources.requests.cpu	250 m	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.cpu.
infrastructure.core.flow_director.resources.requests.memory	600 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.memory.
infrastructure.core.flow_director.resources.requests.ephemeral_storage	200 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.ephemeral-storage.
Scaling
infrastructure.core.flow_director.scaling		For scaling parameters, see the separate table on scaling, Parameters for Scaling - Transport Director, Flow Director, Insight Director.

Table 7. Insight Director infrastructure parameters
Parameter field	Default value	Description
Resources
infrastructure.core.insight_director.resources		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.
infrastructure.core.insight_director.resources.autofill_limits	false	When true and limits are not defined, limits will be the same as the requests. When false and limits are not defined, there are no limits. Setting limits overrides this setting.
infrastructure.core.insight_director.resources.limits		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits. If this is defined, either a CPU limit value, a memory limit value, or both must be provided.
infrastructure.core.insight_director.resources.limits.cpu		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.cpu.
infrastructure.core.insight_director.resources.limits.memory		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.memory.
infrastructure.core.insight_director.resources.requests		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.
infrastructure.core.insight_director.resources.requests.cpu	120 m	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.cpu.
infrastructure.core.insight_director.resources.requests.memory	350 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.memory.
Scaling
infrastructure.core.insight_director.scaling		For scaling parameters, see the separate table on scaling, Parameters for Scaling - Transport Director, Flow Director, Insight Director.

Table 8. Content Filtering Director infrastructure parameters
Parameter field	Default value	Description
Resources
infrastructure.core.content_filtering_director.resources		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.
infrastructure.core.content_filtering_director.resources.autofill_limits	false	When true and limits are not defined, limits will be the same as the requests. When false and limits are not defined, there are no limits. Setting limits overrides this setting.
infrastructure.core.content_filtering_director.resources.limits		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits. If this is defined, either a CPU limit value, a memory limit value, or both must be provided.
infrastructure.core.content_filtering_director.resources.limits.cpu		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.cpu.
infrastructure.core.content_filtering_director.resources.limits.memory	1 Gi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.memory.
infrastructure.core.content_filtering_director.resources.limits.ephemeral_storage	20 Gi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.ephemeral-storage.
infrastructure.core.content_filtering_director.resources.requests		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.
infrastructure.core.content_filtering_director.resources.requests.cpu	250 m	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.cpu.
infrastructure.core.content_filtering_director.resources.requests.memory	600 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.memory.
infrastructure.core.content_filtering_director.resources.requests.ephemeral_storage	1 Gi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.ephemeral-storage.

Table 9. Parameters for Scaling - Transport Director, Flow Director, Insight Director
Parameter field	Default value	Description
infrastructure.core.<transport/flow/insight>_director. scaling		This parameter has a Kubernetes equivalent: HorizontalPodAutoscaler.
infrastructure.core.<transport/flow/insight>_director. scaling.create_autoscaler	true	This parameter defines whether to create the HoizontalPodAutoscaler object with the forthcoming configuration options. If it is set to false, the HPA object to enable core autoscaling will need to be created manually.
infrastructure.core.<transport/flow/insight>_director. scaling.min_replicas	1	This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.minReplicas.
infrastructure.core.<transport/flow/insight>_director. scaling.max_replicas	10	This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.maxReplicas.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.metrics.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.cpu		This parameter defines the CPU metric configuration.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.cpu.average_utilization	80	This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.metrics.resource. target.averageUtilization.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.memory		This parameter defines the memory metric configuration.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.memory.average_utilization	80	This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.metrics.resource. target.averageUtilization.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior. If it is defined, either scale_down or scale_up parameter must be defined.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_down		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleDown. If it is defined, all included parameters need to be defined.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_down.stabilization_window_seconds		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleDown. stabilizationWindowSeconds.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_down.policies		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleDown. policies.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_down.policies.type		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleDown. policies.type.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_down.policies.value		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleDown. policies.value.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_down.policies.period_seconds		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleDown. policies.periodSeconds.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_down.select_policy		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleDown. selectPolicy.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_up		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleUp. If it is defined, all included parameters need to be defined.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_up.stabilization_window_seconds		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleUp. stabilizationWindowSeconds.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_up.policies		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleUp. policies.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_up.policies.type		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleUp. policies.type.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_up.policies.value		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleUp. policies.value.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_up.policies.period_seconds		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleUp. policies.periodSeconds.
infrastructure.core.<transport/flow/insight>_director. scaling.metrics.behavior.scale_up.select_policy		This parameter has a Kubernetes equivalent: horizontalpodautoscaler.spec.behavior.scaleUp. selectPolicy.

Table 10. Config-api infrastructure parameters
Parameter field	Default value	Description
Resources
infrastructure.mgmt.config_api.resources		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.
infrastructure.mgmt.config_api.resources.autofill_limits	false	When true and limits are not defined, limits will be the same as the requests. When false and limits are not defined, there are no limits. Setting limits overrides this setting.
infrastructure.mgmt.config_api.resources.limits		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits. If this is defined, either a CPU limit value, a memory limit value, or both must be provided.
infrastructure.mgmt.config_api.resources.limits.cpu		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.cpu.
infrastructure.mgmt.config_api.resources.limits.memory		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.memory.
infrastructure.mgmt.config_api.resources.limits.ephemeral_storage		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.ephemeral-storage.
infrastructure.mgmt.config_api.resources.requests		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.
infrastructure.mgmt.config_api.resources.requests.cpu	350 m	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.cpu.
infrastructure.mgmt.config_api.resources.requests.memory	450 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.memory.
infrastructure.mgmt.config_api.resources.requests.ephemeral_storage	100 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.ephemeral-storage.

Table 11. Frontend infrastructure parameters
Parameter field	Default value	Description
Resources
infrastructure.mgmt.frontend.resources		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.
infrastructure.core.mgmt.frontend.resources.autofill_limits	false	When true and limits are not defined, limits will be the same as the requests. When false and limits are not defined, there are no limits. Setting limits overrides this setting.
infrastructure.core.mgmt.frontend.resources.limits		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits. If this is defined, either a CPU limit value, a memory limit value, or both must be provided.
infrastructure.core.mgmt.frontend.resources.limits.cpu		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.cpu.
infrastructure.core.mgmt.frontend.resources.limits.memory		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.memory.
infrastructure.core.mgmt.frontend.resources.limits.ephemeral_storage		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.limits.ephemeral-storage.
infrastructure.core.mgmt.frontend.resources.requests		This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.
infrastructure.core.mgmt.frontend.resources.requests.cpu	350 m	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.cpu.
infrastructure.core.mgmt.frontend.resources.requests.memory	450 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.memory.
infrastructure.core.mgmt.frontend.resources.requests.ephemeral_storage	70 Mi	This parameter has a Kubernetes equivalent: pod.spec.containers.resources.requests.ephemeral-storage.

5.2. PAS configuration in Kubernetes

5.2.1. Configuration options for the storage component

The config.storage section controls keys to be used between the management and storage components.

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 12. Storage configuration **common** options
Key	Default	Description
config.storage.common.standalone_mode	true	This parameter must be set to 'true'. It 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 13. Storage configuration **consul** options
Key	Default	Description
config.storage.consul.bind_cluster_addr	127.0.0.1	The address to bind on as a cluster member. This will be used to communicate with other members. This is a required parameter.
config.storage.consul.gossip_encryption_key		The encryption key to use for the gossip protocol. It is a 32-byte shared key encoded into base64 format. Use `openssl rand -base64 32` to generate it. For more information on the keys produced as part of the configuration, see Using values.yml file. This is a required parameter.
config.storage.consul.log_level	INFO	The log level of consul. The possible values are: TRACE, DEBUG, INFO, WARN, ERR

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

Table 14. Storage configuration **blob-store** options
Key	Default	Description
config.storage.blob_store.access_key		The access key used for connecting to MinIO. A preferably random generated string must be provided. Min length: 3 This is a required parameter.
config.storage.blob_store.secret_key		The secret key used for connecting to MinIO. A preferably random generated string must be provided. Min length: 8. This is a required parameter.

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

For configuration examples, see section Minimal configuration.

5.2.2. Configuration options for the management component

The config.mgmt section controls:

Web service parameters
Authentication

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

The default values for both frontend and configapi sections are automatically effective. If the attributes have to be configured with specific values, other than the default values, the {} curly braces have to be deleted and the new values have to be added.

Table 15. Management configuration **frontend** options
Key	Default	Description
config.mgmt.frontend.server_name	`_`	The hostname the web server should serve the requests on. The default value means that the management interface will be served regardless of the provided hostname.
config.mgmt.frontend.cors_api	N/A	This section configures cross origin request sharing options for API access.
config.mgmt.frontend.allow_origin		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 16. Management configuration log level setting options - **configapi** section
Key	Default	Description
config.mgmt.configapi.log_level	INFO	The log level can be set to DEBUG, INFO, WARNING, ERROR, CRITICAL.

Table 17. Management configuration user session options - **configapi** section
Key	Default	Description
config.mgmt.configapi.session	N/A	This section configures the options for session lifetimes.
config.mgmt.configapi.session.session_validity	600	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.
config.mgmt.configapi.session.renew_validity	36000	The validity of the renew token. It determines for how long session tokens can be renewed. Therefore the maximum length of a user session is the sum of the two parameters.

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

For further details on configapi section parameters related to LDAP authentication, see Management configuration LDAP authentication options - configapi section.

For configuration examples on the management component, see section Minimal configuration and section Management configuration with LDAP authentication.

5.2.2.1. Configuring authentication and local users in PAS

There are two methods available to configure authentication in PAS:

htpasswd authentication
Lightweight Directory Access Protocol (LDAP) authentication

It is required to provide the htpass file already for the Helm chart installation. See section Providing the necessary files for Helm installation.

Using htpasswd for authentication and for the configuration of local users

By using htpasswd authentication, the administrator can define individual user credentials directly in the htpasswd file. This file is created and provided for the Helm installation command. As local users are stored in an htpasswd file, the standard htpasswd tool needs to be used.

It is not possible to configure user groups, or to define different access levels for the users with htpasswd authentication, yet it is possible to define as many user credentials as necessary one by one. The user credentials are encrypted in the configuration file using the bcrypt encryption method. If you want to add new users to the htpasswd file, run the htpasswd users.htpass username command and provide the password.

Example command and output

$ htpasswd -B users.htpass new-user
New password:
Re-type new password:
Adding password for user new-user

Consider the followings related to the command and the example output:

the htpasswd file is created and provided for the Helm installation command
new-user is the name of the new user

As a result, similar content is expected to appear in the referred file:

new-user:$2y$05$jsvtfYMP1HJZlWCNGVk6d.j4yWU5gJ4D97Vr6z8yK9A2wy80g1iD.

LDAP authentication

LDAP authentication is a more elaborate way to configure authentication for PAS. With LDAP authentication it is possible to define user groups and attach different levels of access to these users, however, PAS does not support different levels of authorization based on these attributes yet at the moment.

If LDAP authentication is used, only the administrator user - and no other user - can authenticate with the htpasswd file.

The following configapi parameters, which are part of the configuration file’s configapi section, take part in LDAP authentication:

Table 18. Management configuration LDAP authentication options - **configapi** section
Key	Default	Description
config.mgmt.configapi.ldap	N/A	This section configures the options for LDAP authentication. LDAP authentication is disabled by default.
config.mgmt.configapi.ldap.ldap_url		The URL of the LDAP server. It must start with `ldap[s]://`. This is a required parameter in case of LDAP authentication.
config.mgmt.configapi.ldap.bind_user		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 Active Directory domain and the username concatenated by a backslash (eg. `AD_domain\administrator`). This is a required parameter in case of LDAP authentication.
config.mgmt.configapi.ldap.bind_password		The password of the service user. This is a required parameter in case of LDAP authentication.
config.mgmt.configapi.ldap.use_ntlm	OFF	Set this parameter to ON to use NTLM authentication. This is only available when the LDAP server is Microsoft Active Directory.
config.mgmt.configapi.ldap.tls_version	TLSv1_2	The TLS version for the LDAPS connection. It must be one of the following: SSLv23, TLS, TLS_CLIENT, TLS_SERVER, TLSv1, TLSv1_1, TLSv1_2.
config.mgmt.configapi.ldap.validate_cert	no	Set it to yes to validate certificates.
config.mgmt.configapi.ldap.ca_certs_file	/opt/balasys/etc/ldap_ca_certs.pem	This file contains the certificate files of the certificate authorities. Provide the path and filename for the certificate file. The certificate file must be in PEM format. See a single CA file configuration example in Single CA file example. In case a self-signed certificate is used, the server certificate must also be included in this file. In case a chain of certificates is used, the certificate of each level must be included in this file, beginning with the certificate of the signer of the server certificate, followed by the signer of that certificate up to the root certificate. For example on a Certificate chain with multiple CA, see Example on certificate chain with multiple CAs. In case multiple chains of certificates are used, the chains must be concatenated in the same file. The first matching chain will be used for verification. The above details are based on the Python SSL library documentation, available at https://docs.python.org/3.10/library/ssl.html#certificates. Use the `--set-file mgmt_ldap_ca_certs_file=<path/to/file>` command during helm installation to specify this file. Also uncomment the `ca_certs_file` parameter without changing its value.
config.mgmt.configapi.ldap.user_base_dn		The base DN under which users reside. This is a required parameter in case of LDAP authentication.
config.mgmt.configapi.ldap.username_attribute	sAMAccountName	The attribute that contains the name of the user.
config.mgmt.configapi.ldap.user_object_class	user	The object class of the users.
config.mgmt.configapi.ldap.memberof_attribute	memberof	The attribute that contains membership information (groups) on user objects.
config.mgmt.configapi.ldap.group_base_dn		The base DN under which groups reside. This is a required parameter in case of LDAP authentication.
config.mgmt.configapi.ldap.groupname_attribute	name	The attribute that contains the name of the group.
config.mgmt.configapi.ldap.member_attribute	member	The attribute that contains membership information (users) on group objects.
config.mgmt.configapi.ldap.group_object_class	group	The object class for groups.
config.mgmt.configapi.ldap.allowed_groups		A list of group names (as contained by 'groupname_attribute') allowed to log in. This is a required parameter in case of LDAP authentication.

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 generated when the management component is first started. The password for the administrator can be found in the journal under the pas-config-api identifier.

For information on how to set up more users, see section Configuring authentication and local users in PAS.

By using OpenAPI schemas, as defined in OpenAPI specifications (also known as Swagger), Proxedo API Security verifies that the traffic passing through conforms to the API endpoint’s specification. An OpenAPI Swagger schema detailing the Configuration API is available at: <frontend_url>/api/v1/openapi. <frontend_url> here refers to the URL address of the user’s Proxedo API Security Web User Interface.

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:

Listeners
- Port
- Endpoint
  For more details on the Listener's parameters, see Listeners’ configuration options.
Endpoint
- Name
- Url
  For more details on the Endpoint's parameters, see Endpoint configuration.
Security Flow
- Request
- Response
- Backend

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.

For accessing the Web User Interface:

Enter the valid user credentials.
Click the Log In button.

After a successful login, the user has access to the Proxedo API Security Web UI.

6.3. Proxedo API Security Web User Interface main page

The configuration elements are organized into a logical order for easier usage.

Figure 4. Proxedo API Security Web User Interface main page

The PAS Web UI has the following navigation areas:

The navigation areas are described here in more details:

Left navigation area (1): This navigation area (1) presents the navigation units available for configuration.
When opening up the Proxedo API Security Web UI, three main navigation units are available, that is, BRICKS, PLUGINS, and SERVICES.
These three main navigation units can be opened for further sub-navigation units by clicking on either the navigation item itself or on the arrow icon next to it. Alternatively, when the sub-navigation units are not in use, they can be hidden by clicking the arrow navigation icons next to the main navigation items, or similarly by clicking on the navigation item itself.
Top navigation area (2): This Top navigation area (2) presents the Changes and the Configuration Backup buttons in the top left corner. For more information on these services, see Checking and finalizing changes in Proxedo API Security configuration and Backup and restore running or user configuration for Proxedo API Security. The top right corner presents the Help button and a Profile button that shows the current user’s name. The Logout option is present under the Profile button.

Main configuration area (3): This is the main configuration area of the Web UI. Any navigation unit selected in the Left navigation area (1) presents the configuration details in this Main configuration area (3). The configuration details can be edited in this area.
In case there are already configured parameters, those are displayed in a table in the Main configuration area (3).
In order to add more configuration details, select the New navigation button in the upper right corner.

The Main configuration area (3) provides the following navigation and activity options. Note that some of these activities are also available when the configuration parameters are presented in list view:

Table 19. Navigation and activity options in the Main configuration area (3)
Navigation option	Description
	By selecting the New navigation button on the active window of a component, a new component can be configured.
	By selecting the Pen navigation button next to a component, the Web UI navigates back to the configuration page of the selected element. The so far configured details can be changed or new configuration details can be added.
	By selecting the Copy navigation button next to a component, the Web UI copies all the information of that component into a new instance, which instance can be saved with a new name, inheriting the same, copied parameters.
	By selecting the Bin button next to a component, the configuration element can be deleted. If an element is selected for deletion, a Warning appears, requesting confirmation on the deletion of the element.
	This icon is visible at the right side of every drop-down list during configuration. By selecting this icon it is possible to unselect an item of the drop-down list and to clear the selection field from any data. Clearing the field from data with the help of this icon gains importance when an earlier selected drop-down list item, saved in our configuration, has to be cleared from the configuration data.
	By selecting the Next page button it is possible to navigate to the next page of the parameter keys listed.

6.3.2. Naming Configuration components in the Web UI

When configuring the Proxedo API Security Web UI, name the configuration components with the usage of the English alphabet and numerals. When the name is composed of more than one word, use underscore. It is not allowed to use spacing or any special characters though.

6.4. BRICKS - Configuration units

Bricks are reusable components. They do not provide a complete security function themselves, instead, they are used as building blocks elsewhere (hence the name). They can be used by Plugins (like Selectors), or utilized by other bricks (like Extractors).

Certain bricks are so called default objects, which are in 'read-only' state and cannot be configured or modified. Such default objects are listed in the following table:

Table 20. Default objects - BRICKS
Default object name	Class
Always	Matcher
Never	Matcher
content_type_json	Matcher
content_type_json_pattern	Matcher
json_content	Matcher
content_type_xml_base	Matcher
content_type_xml_dtd	Matcher
content_type_xml_ext_parsed	Matcher
content_type_xml_pattern	Matcher
content_type_xml_text	Matcher
content_type_xml_text_ext_parsed	Matcher
xml_content	Matcher
error_policy	Error policy
enforcer_default	Error policy
insight_default	Error policy
client_address	Selector
client_port	Selector
server_address	Selector
server_port	Selector

These default objects are listed under the actual classes in the Web UI.

The BRICKS main page in the Web UI is as follows:

Figure 6. The BRICKS main page in the Web User Interface

Click on the BRICKS main configuration item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Click on the sub-navigation unit you would like to configure. The details of the sub-navigation menu open up in the Main configuration area.

6.4.1. Error Policy

Error Policies define how to proceed if a Plugin decides to have found an error. For example, when an Enforcer plugin decides that the call is invalid.

It is the error policy that enables the user to act differently in case the error appears in a request or a response.

Every Plugin has a default error policy, namely, the 'error_policy', except for the Enforcer and the Insight Plugins, which have their own default error policies already configured for usage, the enforcer_default and the insight_default error policies.

6.4.1.1. Configuring Error Policies

Click on the BRICKS main navigation item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select Error Policy.

The configuration window that appears presents the default error policies, as listed in Default objects - BRICKS and the configuration values already set by the user:

Figure 7. Error policy’s main page in the Web User Interface

Click on the New navigation button to create an Error Policy.

Error Policies have default values for each of their fields. They form a strict security policy: all errors are fatal, and only errors made by the client are reported in detail.

Configure the necessary parameters for the error policy based on the details provided in the table Error policy configuration options.
Click the Validate button to check if the defined parameters are of the correct type and all required parameters have been filled out for configuring the component. If the configuration is erroneous or incomplete, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing or faulty elements appears at the problematic field. If the configuration of the component is valid, after clicking the Validate button, a 'Component validation successful' notification is shown.
Save the component configuration by clicking the Save button.

The error policies configured here can be used in the Plugin’s configuration, by referencing their name.

The following values can be configured for the Error Policy Brick:

Figure 8. Configuring error policies in the Web User Interface

Table 21. Error policy configuration options
Key	Values	Default value	Description
Name*	Free text. Alphanumeric, may contain underscores, may not start with a number.		The name identifying the error policy. This name of the error policy can be referenced from other parts of the configuration, that is, the error policy is reusable.
Request	The available values are: Abort Log	Abort	It defines what action shall take place if there is an error on the request side: Abort: the request is denied if the Plugin fails. Use the other parameters to control the content of the error sent to the client. Log: the invalid requests are allowed, but are logged.
Request Silent	True or False.	True	When turned on, the Plugins do not report on the denial of the invalid request. When turned off, the Plugins have the ability to report the error in detail in the body of the HTTP error request.
Request Code	The values are available from a drop-down list. If the elements of the drop-down list are selected, it will make the list of the actual request codes visible. The applicable request code can be selected.	422	The HTTP status code to be used when denying invalid requests.
Request Message	The message can be provided in free text.	Request error	The HTTP response line when denying invalid requests.
Response	Response error mode: Abort Log	Abort	It defines what action shall take place if there is an error on the request side: Abort: the request is denied if the Plugin fails. Use the other parameters to control the content of the error sent to the client. Log: the invalid requests are allowed, but are logged.
Response Silent	True or False.	True	When turned on, the Plugins do not report on the denial of the invalid response. When turned off, the Plugins have the ability to report the error in detail in the body of the HTTP error response.
Response Code	The values are available from a drop-down list. Note that the response codes are grouped, so that if the elements of the drop-down list are selected, further groups of response codes will be made visible in a tree structure. The applicable request code can be selected.	502	The HTTP status code to be used when denying invalid requests.
Response Message	The message can be provided in free text.	Response error	The HTTP response line when denying invalid requests.

6.4.2. Matcher

Matchers decide if the Plugin should be executed for a given call by checking various data in the HTTP message. They provide an extremely versatile way of defining the circumstances that must be met for the Plugin to execute.

Matchers need four pieces of information:

Name: The Name field can be defined in free text and it is not related to the extractor that will be used. This Name can be referenced in Plugins.
Type: This parameter defines what part of the call needs to be checked.
Comparator: The Comparator shows by what means the collected value of the call is compared with the provided pattern. (Some comparators also take flags or arguments.)
Expression: A regular expression specifies a set of strings that match it. A complete explanation on how to write expressions is not in the scope of this document.

The matchers can be used in Plugin configurations' match option by referencing their name.

There are some named Matchers available without explicit configuration:

always and never are instances of Always matcher and Never matcher.
json_content that matches requests with the Content-Type headers representing JSON.

Also note that no other matchers can be defined with these names.

Matchers internally utilize Extractors to fetch the information from the call to compare with. The Type of the matcher resembles the name of the extractor that will be used.

All matchers have a default comparator that is applied implicitly.

If you want to use comparator parameters, the comparator name should be given even if the default comparator is used.

6.4.2.1. Configuring Matchers

Click on the BRICKS main navigation item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select Matcher.

The configuration window that appears presents the default matchers, as listed in Default objects - BRICKS and the configuration values already set by the user:

Figure 9. Matchers' main page in the Web User Interface

Click on the New navigation button to create a Matcher.
Provide the name of the matcher.
Choose the type of the matcher from the drop-down list.
Configure the necessary parameters with the help of the below tables.
Click the Validate button to check if the defined parameters are of the correct type and all required parameters have been filled out for configuring the component. If the configuration is erroneous or incomplete, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing or faulty elements appears at the problematic field. If the configuration of the component is valid, after clicking the Validate button, a 'Component validation successful' notification is shown.
Save the component configuration by clicking the Save button.

The following values can be configured for the Matcher Brick:

Figure 10. Configuring matchers in the Web User Interface

Table 22. Matcher configuration options
Key	Values	Default value	Description
Name*	Free text. Alphanumeric, may contain underscores, may not start with a number.	It can be defined in free text.	The Name of the matcher which can be referenced in Plugins.
Type*	For the available values, see Matcher types.		The preferred matcher type has to be selected from the drop-down list.

Matcher types

Depending on the choice of the matcher type, some more required configuration fields might appear on this page. The following tables describe the matcher types in details and provide the necessary information for the additional configuration fields, required for setting the matcher types:

Matcher types and their settings - Simple matchers
Matcher types and their settings - Compound matchers
Matcher types and their settings - URI matchers
Matcher types and their settings - SOAP matchers

Matcher type Description

Always

This matcher always matches.

Never

This matcher never matches. It can be used to turn off a Plugin.

Call Direction

Matches the direction of the message (request or response).

Method

Matches the HTTP method of the request. Note that the method is case insensitive by definition, therefore the case will always be ignored.

When choosing the Method matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

Header

It matches the value of an HTTP header. Some HTTP headers can be present more than once in a call. To accommodate this, matching is completed against the value of each occurrence of the header. Matching occurs if there is any match. For example, if the Accept header was repeated as follows:

Accept: application/json
Accept: application/xml

Consequently, in this example above both header.accept: application/json and header.accept: application/xml would match.

To match against the header named server the key will be header.server, possibly completed with comparator specification, like header.server.regex.ignorecase.

While the values are not, the HTTP header names are case insensitive, so you can write them all lowercase in the configuration key.

The syntax of this matcher differs from the others because the name of the Header must be added.

While the values are not, the HTTP header names are case insensitive, so you can write them all lowercase in the configuration key.

Cookie

Matches the value of a key in the Cookie HTTP header. A Cookie header key can be present more than once in a call. To accommodate this, matching is completed against the value of each occurrence of the key. Matching occurs if there is any match.

Content Type

Matches the content type of the message. It is a more robust solution than using the Header matcher on the Content-Type header because that can contain parameters as well.

When choosing the Content type matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

Status

Matches the status code of the response.

See the default Status class comparator which allows convenient matching on HTTP status classes.

When choosing the Status matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

Raw Content

Matches the raw bytes of the request or response. It requires an expression in the form of a hexadecimal string. For example, for matching a PNG image file, the expression shall be '89504e470d0a1a0a', which is equivalent to '89 50 4e 47 0d 0a 1a 0a', as whitespaces can also be used.

Text Content

Matches the request’s or response’s content as a decoded string.

Client Address

Matches the client’s IP address (both IPv4 and IPv6).

Use the subnet type comparator with that matcher type. The subnet comparator examines if the IP address of the Client is in the specified subnet. The format for the input of the subnet comparator is the CIDR notation for IPv4 (for example, 192.0.2.0/24) and canonical prefix notation for IPv6 (for example, 2001:db8::/32).

Client Port

Matches the client’s port (TCP).

Server Address

Matches the server’s IP address (both IPv4 and IPv6).

Use the subnet type comparator with that matcher type. The subnet comparator examines if the IP address of the Server is in the specified subnet. The format for the input of the subnet comparator is the CIDR notation for IPv4 (for example, 192.0.2.0/24) and canonical prefix notation for IPv6 (for example, 2001:db8::/32).

Server Port

Matches the server’s port (TCP).

XPath

Matches the data from the body of an XML call with the help of the XPath expression.

XPath is a query language for XML. It is a very versatile tool for extracting the needed information from the body of the call, and organizing it according to needs.

A complete explanation on how to write XPath expressions is not in the scope of this document. To learn more about it visit the main website.

For more details on XPath configuration options, see XPath extractor configuration options.

JMESPath

Matches the data from the body of a JSON call with the help of the JMESPath expression. JMESPath is a query language for JSON. It is a very versatile tool for extracting the needed information from the body of the call, and for organizing it according to needs. A complete explanation on how to write JMESPath expressions is not in the scope of this document.

To learn more about it visit the JMESPath website:

There is a tutorial.
There are examples.
There is also a formal specification.

When choosing the JMESPath matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

The result of the JMESPath expression should be a string when using string comparators (Equals, Starts with, etc.), and number when using number comparators (Min, Max, Range). In case of boolean or complex types, convert to string in the JMESPath expression and use the string representation of the result. Example: instead of comparing the boolean result of address != '', use to_string(address != '') with a string comparator.

Fraud Detector Score

Matches the score value provided by the Fraud Detector plugin.

Table 24. Matcher types and their settings - Compound matchers
Any	Any is a Compound matcher that matches if any of its sub-matchers matches. The sub-matcher can also be a compound matcher.
All	All is a Compound matcher that matches if all of its sub-matchers match. The sub-matcher can also be a compound matcher.
None	None is a Compound matcher that matches if none of its sub-matchers match. The sub-matcher can also be a compound matcher.
One	One is a Compound matcher that matches if exactly one of its sub-matchers matches. The sub-matcher can also be a compound matcher.

Matcher type Description

URI matchers

A range of matchers is available to match different parts of the URI.

The structure of an URI looks as follows:

scheme://[username[:password]@]host[:port][/path][?query][#fragment]

That is, for example:

https://john.doe:secret123@example.com:8443/some/resource?foo=bar&baz=qux#some-anchor

The fragment part is used by the client locally, and is never sent in the HTTP requests, therefore PAS cannot do anything with it.

These matchers use the URI extractors. It has an extensive list of examples of what each extractor extracts from the URI.

URI

Matches against the whole request URI as received from the client.

When choosing the URI matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI netloc

Matches the network location in the URI.

It includes:

username and password if present
host
port if present unless scheme default

If the port is the default port for the scheme - that is 80 and 443 for HTTP and HTTPS, respectively - the port will not be included even if explicitly sent by the client. Therefore if the client used http://example.com:80/path then the netloc would be http://example.com, not http://example.com:80.

When choosing the URI netloc matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI origin

Matches the origin part of the URI.

It includes:

scheme
host
port if present, unless the default port for the scheme is used

If the port is the default port for the scheme - that is 80 and 443 for HTTP and HTTPS, respectively - the port will not be included, even if explicitly sent by the client. Therefore if the client used http://example.com:80/path, then the origin would be http://example.com, not http://example.com:80.

When choosing the URI origin matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI scheme

Matches the scheme of request (http or https). Note that the scheme is case insensitive by definition, therefore the case will always be ignored.

When choosing the URI scheme matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI username

Matches the username in the request if present.

When choosing the URI username matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI password

Matches the password in the request if present.

When choosing the URI password matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI host

Matches the host in the request.

When choosing the URI host matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI port

Matches the port of the request. Note that this matches the default port — that is 80 and 443 for HTTP and HTTPS, respectively — even if it is not explicitly in the request.

When choosing the URI port matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI path

Matches the path part of the URI.

The path is normalized to allow more robust matching and cleaner reporting. This means that:

If the path is missing / it is extracted.
Repeating forward-slash (/) characters are replaced with a single one.
dot (.) and double-dot (..) path segments are resolved.

Consequently, if the path present in the URI was //some/./nothere/../resource///./somewhere the path would be /some/resource/somewhere.

If you need to match the path exactly as received, use URI raw path matcher.

When choosing the URI path matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI raw path

Matches the path part of the URI, without the normalization of URI path matcher carried out.

If the path is missing, the match still runs against a single forward slash ("/").

It is recommended to use URI path matcher unless there is an explicit need for matching the raw path. One such example would be logging or filtering out badly formed requests.

When choosing the URI raw path matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI raw query

Matches the query part of the URI as a string. It is recommended to use URI query parameter matcher unless there is an explicit need for matching the raw string. An example on this might be if there is a match on foo=barbar or tofoo=bar as well, even though it was not intended.

When choosing the URI raw query matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI query parameter

Matches the value of a query parameter.

It is also valid for URIs to include a query parameter more than once. That is, it could be foo=bar&qux=quz&foo=baz. To accommodate this, matching is done against the value of each occurrence of the parameter. Matching occurs if any value is matched.

When choosing the URI query parameter matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

Table 26. Matcher types and their settings - SOAP matchers
Matcher type	Description
SOAP Matchers	A range of matchers is available to match different parts of the SOAP message. These matchers extend the XPath matcher with predefined expressions. They use the SOAP extractors. It has an extensive list of examples of what each extractor extracts from the SOAP message. When choosing the SOAP Matchers matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP version	Matches the SOAP message version. It identifies with the SOAP namespace. The possible values are: soapv1_1 - the message version is SOAP v1.1 soapv1_2 - the message version is SOAP v1.2 When choosing the SOAP version matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP envelope	Matches the SOAP envelope. When choosing the SOAP envelope matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP header	Matches the SOAP header. When choosing the SOAP header matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP body	Matches the SOAP body. When choosing the SOAP body matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP fault	Matches the SOAP fault. When choosing the SOAP fault matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP fault code	Matches the SOAP fault 'code'. The expression depends on the SOAP version. faultcode - it is the SOAP v1.1 node tag. Code - it is the SOAP v1.2 node tag. When choosing the SOAP fault code matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP fault detail	Matches the SOAP fault 'detail'. The expression depends on the SOAP version. Detail - it is the SOAP v1.1 node tag. Detail - it is the SOAP v1.2 node tag. When choosing the SOAP fault details matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP 1.1 fault faultstring	Matches the SOAP fault 'faultstring'. This matcher only works with SOAP version 1.1. When choosing the SOAP 1.1 fault faultstring matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP 1.1 fault faultactor	Matches the SOAP fault 'faultactor'. This matcher only works with SOAP version 1.1. When choosing the SOAP 1.1 fault faultactor matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP 1.2 fault reason	Matches the SOAP fault 'Reason'. This matcher only works with SOAP version 1.2. When choosing the SOAP 1.2 fault reason matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP 1.2 fault node	Matches the SOAP fault 'Node'. This matcher only works with SOAP version 1.2. When choosing the SOAP 1.2 fault node matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
SOAP 1.2 fault role	Matches the SOAP fault 'Role'. This matcher only works with SOAP version 1.2. When choosing the SOAP 1.2 fault role matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

For details on comparator types, see Types of comparators.

Depending on the matcher type selected, the administrator might need to fill in further parameters. These parameters are described in the following table.

Table 27. Matcher types' additional configuration options
Key	Values	Default value	Description
Comparator			The matchers need the information on the Comparator, which shows by what means the collected value of the call is compared with the provided pattern.
Type	The available comparator types can be checked from the drop-down list.	Equals	This configuration option has to be defined for the Comparator. For details on the comparator types, see Types of comparators.
Ignorecase	True or False.	False	This configuration option has to be defined for the Comparator. It sets the IGNORECASE flag for the selected comparator type. For matcher types that work with numeric data type or with IP addresses, the 'Equals' and 'Not Equals' comparator types do not have ignorecase field.
Expression*			This configuration option has to be defined for the Comparator. A regular expression specifies a set of strings that match it.
JMESPath Expression*	A valid JMESPath expression in text.		A complete explanation on how to write JMESPath expressions is not in the scope of this document. To learn more about it visit the JMESPath website: There is a tutorial. There are examples. There is also a formal specification.
Query Parameter			It is also valid for URIs to include a query parameter more than once. That is, it could be foo=bar&qux=quz&foo=baz. To accommodate this, matching is done against the value of each occurrence of the parameter. Matching occurs if any value is matched.
Header			Extracts the value of an HTTP header. It is valid for some HTTP headers to be present more than once in a call. In this case, all the values are extracted as a list. It provides the name of the header in the configuration.
Namespaces	A list of key and expression pairs, in text.		The namespaces to use during extraction.
XPath Expression	A valid XPath expression in text.		A complete explanation on how to write XPath expressions is not in the scope of this document. There is a tutorial. There are examples. There is also a formal specification.
Multiline			Sets the Multiline flag for the Regex comparator.
Minimum*			Matches if the pattern is larger or equal to the value.
Maximum*			Matches if the pattern is smaller or equal to the value.
Source Plugin	Reference to a Fraud Detector Plugin or "Last".	Last: In case there are more Fraud Detector plugins defined in the Security Flow, by using this default value, the selector will use the score value provided for the last run Fraud Detector plugin.	The Fraud Detector plugin to be used in case there are more than one defined.

6.4.3. Selector

Selectors are responsible for collecting information from the call. They utilize Extractor bricks for this purpose.

Most extractors return simple string values. However, some (might) return dictionaries. For example, you can get all the HTTP headers, or all the URI query parameters.

They are used by Insight.

6.4.3.1. Configuring Selectors

Click on the BRICKS main navigation item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select Selector.

In the configuration window that appears, you can either see the empty parameter values that can be configured for the actual component or you can see already configured component(s) and their parameters. The already configured components with defined parameters can be default components available in the system by default, or can be components configured by the administrator:

Figure 11. Selector main page in the Web User Interface

Click on the New navigation button to create a Selector.
Name the Selector key.
Fill in any more desired parameters.
Click the Validate button to check if the defined parameters are of the correct type and all required parameters have been filled out for configuring the component. If the configuration is erroneous or incomplete, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing or faulty elements appears at the problematic field. If the configuration of the component is valid, after clicking the Validate button, a 'Component validation successful' notification is shown.
Save the component configuration by clicking the Save button.

The following values can be configured for the Selector Brick:

Figure 12. Configuring Selector in the Web User Interface

Table 28. Selector configuration options
Key	Values	Default value	Description
Name*	Free text. Alphanumeric, may contain underscores, may not start with a number.		The name of the parameter can be referenced.
Type*	Choose the selector type from the drop-down list. For more details on the values, see Extractor types.		Extractors are used to extract data from the call. They are utilized by Selector (and Matcher as well). Extractors are included by their type in Selectors, and are used by a special syntax in matchers. For details, see Extractors and Extractor types.
Save As	The key under which the results of a selector are saved in the Insight plugin’s dictionary.	Top	If it is omitted, the result will be directly merged as top level keys. Name the configuration components with the usage of the English alphabet and numerals. When the name is composed of more than one word, use underscore. It is not allowed to use spacing or any special characters though.

Depending on what value is selected for the Type parameter, additional parameters might appear for configuration. The following table provides details on these additional parameters.

Table 29. Additional Selector configuration options
Key	Values	Default value	Description
Clear Text	True or False.	False	When turned on, whitespaces are stripped from the beginning and end of the result.
Namespaces	A list of key and expression pairs, in text.		The namespaces to use during extraction.
XPath Expression	A valid XPath expression in text.		A complete explanation on how to write XPath expressions is not in the scope of this document. There is a tutorial. There are examples. There is also a formal specification.
JMESPath Expression*	A valid JMESPath expression in text.		A complete explanation on how to write JMESPath expressions is not in the scope of this document. To learn more about it visit the JMESPath website: There is a tutorial. There are examples. There is also a formal specification.
Expression*			A regular expression specifies a set of strings that match it.
Time Format	A valid time format string in text.	YYYY-MM-DDT HH:mm:ss.SSSSSSZZ (line breaks for display purposes only)	The time format to use, see: Timestamp format options.
Time Zone	A time zone specifier in text.	UTC	The name of the time zone, or the time zone offset. The time zone can be specified by using the name, for example, "Europe/Budapest", or as the time zone offset in +/-HH:MM format, for example, +01:00.
Source Plugin	Reference to a Fraud Detector Plugin or "Last".	Last: In case there are more Fraud Detector plugins defined in the Security Flow, by using this default value, the selector will use the score value provided for the last run Fraud Detector plugin.	The Fraud Detector plugin to be used in case there are more than one defined.
Include Request Counter	True or False.	True	When turned on, the request counter is included in the Session ID. See [session-id] for details.

6.4.4. Insight Target

Insight Target bricks define where the data collected by the Insight will be sent to.

The Insight Target configuration tree contains named Insight Targets with their respective configuration.

Unlike other bricks, Insight Target configurations cannot be put inline into a Plugin’s configuration, they must always be configured here.

See the Insight Target configuration options for the available Insight Target types and their configuration options.

6.4.4.1. Data flattening

To ensure compatibility with a wide range of Insight Target types, the results collected by the Insight plugin are flattened. The path inside the complex data structure is encoded into the key for each value:

The merged key describes the path to the value in the data structure as a string.
The parts of the path will be separated by a forward slash character ("/").
Keys in nested dictionaries are added to the path by name.
List items are added to the path by their index.

You can control the separator with the Flatten separator configuration key that every Insight Target accepts.

6.4.4.2. Configuring Insight Targets

Click on the BRICKS main navigation item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select Insight Target.

Figure 13. Insight Target main page in the Web User Interface

Click on the New navigation button to create an Insight Target.
Provide the name for your Insight Target configuration.
Select the Insight Target type.
Continue with the Syslog, Elastic and Local log configurations with the help of the following tables: Syslog Insight Target configuration parameters, Elastic Insight Target configuration parameters and Local log Insight Target configuration parameters.
Configure any more desired parameter details.
Click the Validate button to check if the defined parameters are of the correct type and all required parameters have been filled out for configuring the component. If the configuration is erroneous or incomplete, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing or faulty elements appears at the problematic field. If the configuration of the component is valid, after clicking the Validate button, a 'Component validation successful' notification is shown.
Save the component configuration by clicking the Save button.

The following values can be configured for the Insight Target Brick:

Figure 14. Configuring Insight Target in the Web User Interface

Table 30. *Insight Target* configuration options
Key	Values	Default value	Description
Name*	Free text. Alphanumeric, may contain underscores, may not start with a number.		The name identifying the Insight Target. This name of the Insight Target can be referenced from other parts of the configuration.
Type*	The values can be selected from the drop-down list. The available values are: Local log Syslog Elastic		Local log: Logs the result of the insight in the local system log. For more details on configuration settings with Local log, see Local log Insight Target configuration parameters. Syslog: Sends the insight to a remote syslog server using the IETF syslog protocol defined in RFC5424. For more details on configuration settings with syslog, see table Syslog Insight Target configuration parameters. Elastic: Sends the insight to an Elasticsearch engine in JSON. For more details on configuration settings with syslog, see Elastic Insight Target configuration parameters.
Flatten	True or False.	True	Flatten the Insight Target message.
Flatten Separator		/	The separator in the flattened message.
Level		3	The log level for the logged message.
Tag	The value can be selected from a drop-down list.	info	The log tag for the logged message.
Message		The message of the insight if present, otherwise it is empty.	The message part of the log message.

The following table presents the configuration parameters for the Local log Insight Target type:

Table 31. Local log *Insight Target* configuration parameters
Key	Values	Default value	Description
Flatten	True or False.	True	Flatten the Insight Target message.
Flatten separator		/	The separator in the flattened message. Only visible when Flatten is True.
Level		3	The log level for the logged message.
Tag		info	The log tag for the logged message.
Message		The message of the insight if present, otherwise it is empty.	The message part of the log message.

The following table presents the configuration parameters for the syslog Insight Target type:

Table 32. Syslog *Insight Target* configuration parameters
Key	Values	Default value	Description
Flatten	True or False.	True	Flattens the Insight Target message. Only visible when Data Format is JSON.
Flatten Separator		/	The separator in the flattened message. Only visible when Flatten is True.
Remote Connection	Host: Hostname or IP address as text. Port: The available values are integers. Protocol: The available values are: TCP and UDP. IP Protocol: The available values are: 4 and 6, corresponding to IPv4 and IPv6. Use TLS: True or False. Syslog TLS: Reference to a TLS Brick* of type Syslog TLS.	Protocol: TCP, Port: 601 (6514 if Use TLS is True.) Protocol: UDP, Port: 514 IP Protocol: 4 Use TLS: False	Host: The hostname or the IP address of the syslog server. Port: Add the port number here to connect to the remote system. Protocol: Add the transport protocol to send messages over. The available values are: TCP and UDP. IP Protocol: The internet protocol version of the given driver. Use TLS: It enables using TLS for the Syslog communication. Syslog TLS: It is mandatory if the Use TLS* option is set to True.
Flush Lines			It specifies how many lines are flushed to a destination at a time. The Insights Director waits for this number of lines to accumulate and sends them off in a single batch. Increasing this number increases the throughput, as more messages are sent in a single batch, but also increases the message latency.
Data Format	The possible values are: SData, JSON.	SData	This is the data format of the insight.
Second Fraction Digits	Integer between 0 and 6 inclusive	3	The number of digits representing the fractions of seconds in the Syslog timestamp.
Time Zone	See table Time zones for time zone names.	GMT	The name of the time zone (for example, "Europe/Budapest") or the time zone offset in +/-HH:MM format (for example, +01:00).
Report Config Load	True or False.	False	It reports the event of a configuration being loaded with a cryptographic hash of the loaded configuration. This informs the Insight Target about changes in the configuration.
Mask Credit Card Numbers	True or False.	False	It masks the middle section of recognised credit card numbers in any fields of the log message. Recognised credit cards are from one of the following issuers: American Express, Discover Card, Mastercard, VISA.
Enable Heartbeat	True or False.	False	It enables sending heartbeat (-- MARK --) messages to the Insight Target.
Heartbeat	Frequency: A number greater than or equal to 1. Mode: The possible values are: 'idle' (heartbeat messages are only sent when there is no traffic towards the Insight Target) and 'periodical' (heartbeat messages are sent regardless of activity).	Frequency: 30 Mode: 'periodical'	Frequency: The number of seconds between heartbeat messages. Mode: The operation mode of the heartbeat functionality.

The following table presents the configuration parameters for the Elastic Insight Target type:

Table 33. Elastic *Insight Target* configuration parameters
Key	Values	Default value	Description
Flatten	True or False.	True	It flattens the Insight Target message.
Flatten Separator		/	The separator in the flattened message. Only visible when Flatten is True.
Remote Connection			Settings related to the remote connection.
Username*			The username to authenticate with on the servers.
Password*			The password to authenticate with on the servers.
Servers*	There are two values to be configured: Host: The hostname or IP address of the Elasticsearch instance. Port: The port on host* to connect to. Defaults to 9200. (Add the values by clicking the '+' sign.)		The list of Elasticsearch servers. Messages will be load balanced between servers if multiple servers are given.
Index*			The name of the index in the Elasticsearch instance.
Use TLS	True or False.	False	Enables using TLS in the connection towards the Elastic servers.
Elastic TLS*	Reference to a TLS Brick of type Elastic TLS.		The TLS configuration towards the Elastic servers. Mandatory if Use TLS is set to True.
Workers		4	The number of workers to use for communicating with the Elasticsearch servers. Should at least equal the number of servers.
Mask Credit Card Numbers	True or False.	False	It masks the middle section of recognised credit card numbers in any fields of the log message. Recognised credit cards are from one of the following issuers: American Express, Discover Card, Mastercard, VISA.

6.4.5. TLS

Transport Layer Security (TLS) is the cryptographic protocol that secures HTTPS communications. PAS can apply TLS encryption both when communicating with Clients and Backends. TLS encryption can also be used with Syslog and Elastic Insight Targets.

When HTTPS is used the TLS settings must be configured.

These parameters are used by the Insight Director and the Transport Director. For options that reference a file the path is relative to /opt/balasys/var/persistent/ inside the Transport Director container. This directory is a docker volume and by default mounted from the /opt/balasys/var/persistent/transport-director directory in the host system.

6.4.5.1. Configuring TLS Bricks

Click on the BRICKS main navigation item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select TLS.

Figure 15. TLS main page in the Web User Interface

Click on the New navigation button to create a TLS.

The following values can be configured for the TLS Brick:

Figure 16. Configuring TLS in the Web User Interface

The configuration of the first two parameters determines the TLS type and from these two steps on, it is either a Backend TLS configuration, a Client TLS configuration, a Syslog TLS configuration or an Elastic TLS configuration.

6.4.5.1.1. Configuring Client TLS Bricks

The following parameters need to be configured for Client TLS:

Configuring TLS in the Web User Interface TLS options

Figure 17. Configuring Client TLS in the Web User Interface, TLS options

Configuring TLS in the Web User Interface Certificate options

Figure 18. Configuring Client TLS in the Web User Interface, Certificate options

Name the Client TLS configuration.
Select the Type of the TLS, Client TLS in this case, from the drop-down list to configure TLS.

For details on these parameters, see the following table:

Table 34. TLS configuration
Key	Values	Default value	Description
Name*	Free text. Alphanumeric, may contain underscores, may not start with a number.		The name of the parameter can be referenced.
Type*	Choose the required value from the drop-down list.		Client TLS, Backend TLS, Syslog TLS and Elastic TLS configurations can be defined here.

Configure the mandatory parameters for Client TLS, based on the information provided in Table Client TLS configuration.

Table 35. Client TLS configuration
Key	Values	Default value	Description
Certificate			Configuration for the X.509 certificate used for TLS connections on the listener.
Certificate File*	Reference to a File Brick of type Server Certificate.		The certificate to be presented to clients.
Key File*	Reference to a File Brick of type TLS Key.		The private key corresponding to the certificate file.
Options			TLS protocol options used on the listener.
Ciphers		ECDHE-ECDSA-AES128-GCM-SHA256: ECDHE-RSA-AES128-GCM-SHA256: ECDHE-ECDSA-AES256-GCM-SHA384: ECDHE-RSA-AES256-GCM-SHA384: ECDHE-ECDSA-CHACHA20-POLY1305: ECDHE-RSA-CHACHA20-POLY1305: DHE-RSA-AES128-GCM-SHA256: DHE-RSA-AES256-GCM-SHA384	Specifies the allowed ciphers. Can be set to all, high, medium, low, or a string representation of the selected ciphers.
Minimum TLS Version	Select one of the following options in the drop-down menu: TLS v1.0 TLS v1.1 TLS v1.2 TLS v1.3	TLS v1.2	The minimum version of TLS. Minimum TLS version must be less than or equal to the maximum TLS version.
Maximum TLS Version	Select one of the following options in the drop-down menu: TLS v1.0 TLS v1.1 TLS v1.2 TLS v1.3	TLS v1.3	The maximum version of TLS. Maximum TLS version must be greater than or equal to the minimum TLS version.
Timeout		300	It drops idle connection if the timeout value (in seconds) expires.
Enable Session Cache	True or False.	False	Store session information in the session cache. Set this option to 'On' to enable TLS session reuse.
Session Cache Size		20480	The number of sessions stored in the session cache for TLS session reuse.
Disable Ticket	True or False.	False	Session tickets are a method for TLS session reuse, described in RFC 5077. Set this option to 'On' to disable TLS session reuse using session tickets.
Cipher Server Preference	True or False.	True	Use server and not client preference order when determining which cipher suite, signature algorithm or elliptic curve to use for an incoming connection.
Disable Renegotiation	True or False.	True	Set this parameter On to disable client-initiated renegotiation.
Diffie-Hellman Parameters File	Reference to a File Brick of type Diffie-Hellman Parameters.		Contains the Diffie-Hellman parameters to be used by the TLS connection.
Prioritize ChaCha20-Poly1305	True or False.	False	Set this parameter On to prioritize using the ChaCha20-Poly1305 encryption.
Enable Verification	True or False.	False	It is an option for verifying client side X.509 certificates. By default no client verification takes place.
Client Verification			Client verification options
Trusted Certs	Reference to a File Brick of type Certificates.		A directory where trusted IP addresses-certificate assignments are stored. When a peer from a specific IP address shows the certificate stored in this directory, it is accepted regardless of its expiration or issuer CA. Each file in the directory should contain a certificate in PEM format. The filename must be the IP address.
Required	True or False.	True	If it is set to True, PAS requires a certificate from the peer.
Trust Level	The values can be selected from the drop-down list. The available values are: none untrusted full	full	It defines the trust level for certificate verification: none: Accept even invalid certificates, for example self-signed certificates. untrusted: Both trusted and untrusted certificates are accepted. full: Only valid certificates signed by a trusted CA are accepted.
Verify Depth		4	The length of the longest accepted CA verification chain. PAS will automatically reject longer CA chains.
CA Directory	Reference to a File Brick of type CA.		A directory where the trusted CA certificates are stored. CA certificates are loaded on-demand from this directory when PAS verifies the certificate of the peer.
Verify CRL	True or False.	False	If it is set to True, PAS checks the CRLs (Certificate Revocation Lists) associated with trusted CAs. CRLs will load automatically if PAS verifies the certificate of the peer.
Intermediate Revocation Check Type	The values can be selected from the drop-down list. The available values are: none soft_fail hard_fail	hard_fail	The revocation check type for all certificates in the chain, except the Leaf Certificate: none: Ignore the result certificate revocation status check soft_fail: It fails if the check is successful and the certificate is revoked, it will pass otherwise hard_fail: It passes only if the check is successful and the certificate is not revoked
Leaf Revocation Check Type	The values can be selected from the drop-down list. The available values are: none soft_fail hard_fail	hard_fail	The revocation check types for the Leaf certificate are as follows: none: With this option the result of the certificate revocation status check is ignored soft_fail: It fails if the check is successful and the certificate is revoked, it passes otherwise hard_fail: It passes only if the check is successful and the certificate is not revoked

Click the Validate button to check if the defined parameters are of the correct type and all required parameters have been filled out for configuring the component. If the configuration is erroneous or incomplete, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing or faulty elements appears at the problematic field. If the configuration of the component is valid, after clicking the Validate button, a 'Component validation successful' notification is shown.
Save the component configuration by clicking the Save button.

6.4.5.1.2. Configuring Backend TLS Bricks

The following parameters need to be configured for Backend TLS:

Figure 19. Configuring Backend TLS in the Web User Interface, TLS options

Figure 20. Configuring Backend TLS in the Web User Interface, Certificate options

Name the Backend TLS configuration.
Select Backend TLS from the drop-down list to configure Backend TLS.

For details on these parameters, see the following table:

Table 36. TLS configuration
Key	Values	Default value	Description
Name*	Free text. Alphanumeric, may contain underscores, may not start with a number.		The name of the parameter can be referenced.
Type*	Choose the required value from the drop-down list.		Client TLS, Backend TLS, Syslog TLS and Elastic TLS configurations can be defined here.

Configure the mandatory parameters for Backend TLS, based on the information provided in Table Backend TLS configuration.

The configuration parameters are described in details in the following table:

Table 37. Backend TLS configuration
Key	Values	Default value	Description
Enable Certificate	True or False.	False	It is an option for enabling backend side X.509 certificates. By default no backend verification takes place.
Certificate			Configuration for the X.509 certificate used for TLS connections on the listener.
Certificate File*	Reference to a File Brick of type Client Certificate.		The certificate to be presented to the backend.
Key File*	Reference to a File Brick of type TLS Key.		The private key corresponding to the certificate file.
Options			TLS protocol options used on the listener.
Ciphers		ECDHE-ECDSA-AES128-GCM-SHA256: ECDHE-RSA-AES128-GCM-SHA256: ECDHE-ECDSA-AES256-GCM-SHA384: ECDHE-RSA-AES256-GCM-SHA384: ECDHE-ECDSA-CHACHA20-POLY1305: ECDHE-RSA-CHACHA20-POLY1305: DHE-RSA-AES128-GCM-SHA256: DHE-RSA-AES256-GCM-SHA384	Specifies the allowed ciphers. Can be set to all, high, medium, low, or a string representation of the selected ciphers.
Minimum TLS Version	Select one of the following options in the drop-down menu: TLS v1.0 TLS v1.1 TLS v1.2 TLS v1.3	TLS v1.2	The minimum version of TLS. Minimum TLS version must be less than or equal to the maximum TLS version.
Maximum TLS Version	Select one of the following options in the drop-down menu: TLS v1.0 TLS v1.1 TLS v1.2 TLS v1.3	TLS v1.3	The maximum version of TLS. Maximum TLS version must be greater than or equal to the minimum TLS version.
Timeout		300	It drops idle connection if the timeout value (in seconds) expires.
Enable Session Cache	True or False.	False	Store session information in the session cache. Set this option to 'On' to enable TLS session reuse.
Session Cache Size		20480	The number of sessions stored in the session cache for TLS session reuse.
Disable Ticket	True or False.	False	Session tickets are a method for TLS session reuse, described in RFC 5077. Set this option to 'On' to disable TLS session reuse using session tickets.
Enable Verification	True or False.	False	It is an option for verifying Backend side X.509 certificates. By default no backend verification takes place.
Backend verification			Backend verification options
Trusted Certs	Reference to a File Brick of type Certificates.		A directory where trusted IP addresses-certificate assignments are stored. When a peer from a specific IP address shows the certificate stored in this directory, it is accepted regardless of its expiration or issuer CA. Each file in the directory should contain a certificate in PEM format. The filename must be the IP address.
Trust Level	The values can be selected from the drop-down list. The available values are: none untrusted full	full	The trust level for certificate verification: none: Accept even invalid certificates, for example self-signed certificates. untrusted: Both trusted and untrusted certificates are accepted. full: Only valid certificates signed by a trusted CA are accepted.
Verify Depth		4	It defines the length of the longest accepted CA verification chain. PAS will automatically reject longer CA chains.
CA Directory	Reference to a File Brick of type CA.		A directory where the trusted CA certificates are stored. CA certificates are loaded on-demand from this directory when PAS verifies the certificate of the peer.
Verify CRL	True or False.	False	If it is set to True PAS checks the CRLs (Certificate Revocation Lists) associated with trusted CAs. CRLs will load automatically if PAS verifies the certificate of the peer.
Check Subject	True or False.	False	If it is set to, PAS compares the subject of the server-side certificate with application-layer information (for example, it checks whether the Subject matches the hostname in the URL).
Intermediate Revocation Check Type	The values can be selected from the drop-down list. The available values are: none soft_fail hard_fail	soft_fail	The revocation check types for all certificates in the chain, except for the Leaf Certificate are as follows: none: If this options is set, the certificate revocation status check results are ignored soft_fail: If this option is set, the certificate revocation check fails, if the check is successful and the certificate is revoked. The check passes otherwise. hard_fail: If this option is set, the check passes only if the check is successful, and the certificate is not revoked.
Leaf Revocation Check Type	The values can be selected from the drop-down list. The available values are: none soft_fail hard_fail	soft_fail	The revocation check type for the Leaf Certificate. none: The result of the Certificate Revocation Status Check is ignored. soft_fail: If this option is set, the certificate revocation check fails, if the check is successful and the certificate is revoked. The check passes otherwise. hard_fail: If this option is set, the check passes only if the check is successful, and the certificate is not revoked.

Click the Validate button to check if the defined parameters are of the correct type and all required parameters have been filled out for configuring the component. If the configuration is erroneous or incomplete, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing or faulty elements appears at the problematic field. If the configuration of the component is valid, after clicking the Validate button, a 'Component validation successful' notification is shown.
Save the component configuration by clicking the Save button.

6.4.5.1.3. Revocation checks for certificates

PAS tries to complete both CRL and OCSP-stapling checks for certificates.

The result for a certificate, according to the revocation check types is as follows:

Table 38. Certificate revocation checks
CRL check	OCSP stapling check	Soft fail result	Hard fail result
PASS	PASS	PASS	PASS
PASS	unsuccessful	PASS	PASS
unsuccessful	PASS	PASS	PASS
unsuccessful	unsuccessful	PASS	FAIL
PASS	FAIL	FAIL	FAIL
FAIL	PASS	FAIL	FAIL
unsuccessful	FAIL	FAIL	FAIL
FAIL	unsuccessful	FAIL	FAIL
FAIL	FAIL	FAIL	FAIL

6.4.5.1.4. Configuring Syslog TLS Bricks

The following parameters need to be configured for Syslog TLS:

Figure 21. Configuring Syslog TLS in the Web User Interface

Name the Syslog TLS configuration.
Select the Type of the TLS, Syslog TLS in this case, from the drop-down list to configure TLS.

For details on these parameters, see the following table:

Table 39. TLS configuration
Key	Values	Default value	Description
Name*	Free text. Alphanumeric, may contain underscores, may not start with a number.		The name of the parameter can be referenced.
Type*	Choose the required value from the drop-down list.		Client TLS, Backend TLS, Syslog TLS and Elastic TLS configurations can be defined here.

Configure the mandatory parameters for Syslog TLS, based on the information provided in Table Syslog TLS configuration.

Table 40. Syslog TLS configuration
Key	Values	Default value	Description
Enable Client TLS Authentication	True or False.	False	Option for enabling TLS authentication towards the server.
Client TLS Authentication			Configuration for the X.509 certificate used for TLS connections on the Insight Target.
Certificate File*	Reference to a File Brick of type Client Certificate.		The certificate to be used for the connection.
Key File*	Reference to a File Brick of type TLS Key.		The private key corresponding to the certificate file. The private key file must not be encrypted.
Options			TLS protocol options used on the Syslog Insight target.
Ciphers	Colon-separated list of ciphers from the list supported by OpenSSL 3.0.2.	ECDH+AESGCM: DH+AESGCM:ECDH+AES256: DH+AES256:ECDH+AES128: DH+AES:!aNULL:!MD5: !DSS!aNULL: !MD5: !DSS	Specifies the allowed ciphers.
Disable TLS v1.2	True or False.	False	Disables the usage of TLSv1.2 in the connection.
Disable TLS v1.3	True or False.	False	Disables the usage of TLSv1.3 in the connection.
ECDH Curve List	Add the names of one or more ECDH curves. The possible values are the ones supported by OpenSSL 3.0.2.	empty list	A list of curves permitted in the connection when using Elliptic Curve Cryptography (ECC).
Peer Verify	Select one of the following options in the drop-down menu: optional-trusted, optional-untrusted, required-trusted, required-untrusted	required-trusted	Defines the verification method of the peer. The four possible values are a combination of two properties of validation: whether the peer is required to provide a certificate (required or optional prefix), and whether the certificate provided needs to be valid (trusted or untrusted suffix).
Diffie-Hellman Parameters File	Reference to a File Brick of type Diffie-Hellman Parameters.		Contains the Diffie-Hellman parameters to be used by the TLS connection.
Enable Verification	True or False.	False	Option for enabling the verification of server side X.509 certificates.
Server Verification*			Server verification options are mandatory if Enable Verification is set to True.
CA Directory	Reference to a File Brick of type CA.		A directory where the trusted CA certificates are stored. CA certificates are loaded on-demand from this directory when PAS verifies the certificate of the peer.
Verify CRL	True or False.	False	Verifies that certificates used in the connection are not revoked by any CRLs in the CA directory.

Click the Validate button to check if the defined parameters are of the correct type and all required parameters have been filled out for configuring the component. If the configuration is erroneous or incomplete, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing or faulty elements appears at the problematic field. If the configuration of the component is valid, after clicking the Validate button, a 'Component validation successful' notification is shown.
Save the component configuration by clicking the Save button.

6.4.5.1.5. Configuring Elastic TLS Bricks

The following parameters need to be configured for Elastic TLS:

Figure 22. Configuring Elastic TLS in the Web User Interface

Name the Elastic TLS configuration.
Select the Type of the TLS brick, Elastic TLS in this case, from the drop-down list to configure the encryption used with the Elastic server.

For details on these parameters, see the following table:

Table 41. TLS configuration
Key	Values	Default value	Description
Name*	Free text. Alphanumeric, may contain underscores, may not start with a number.		The name of the parameter can be referenced.
Type*	Choose the required value from the drop-down list.		Client TLS, Backend TLS, Syslog TLS and Elastic TLS configurations can be defined here.

Configure the mandatory parameters for Elastic TLS, based on the information provided in Table Elastic TLS configuration.

Table 42. Elastic TLS configuration
Key	Values	Default value	Description
Enable Client TLS Authentication	True or False.	False	Option for enabling TLS authentication towards the server.
Client TLS Authentication			Configuration for the X.509 certificate used for TLS connections on the Insight Target.
Certificate File*	Reference to a File Brick of type Client Certificate.		The certificate to be used for the connection.
Key File*	Reference to a File Brick of type TLS Key.		The private key corresponding to the certificate file. The private key file must not be encrypted.
Options			TLS protocol options used on the Elastic Insight target.
Ciphers	Colon-separated list of ciphers from the list supported by OpenSSL 3.0.2.	ECDH+AESGCM: DH+AESGCM:ECDH+AES256: DH+AES256:ECDH+AES128: DH+AES:!aNULL:!MD5: !DSS!aNULL: !MD5: !DSS	Specifies the allowed ciphers.
TLS Version	Select one of the following options in the drop-down menu: TLS v1.0 TLS v1.1 TLS v1.2 TLS v1.3	TLS v1.2	Defines the TLS version used in the connection.
Peer Verify	True or False.	True	Defines whether the peer is verified. If set to true, the peer is required to provide a certificate, and the certificate provided needs to be valid.
Enable Verification	True or False.	False	Option for enabling the verification of the X.509 certificate presented by the Elastic server.
CA Directory	Reference to a File Brick of type CA.		A directory where the trusted CA certificates are stored. CA certificates are loaded on-demand from this directory when PAS verifies the certificate of the peer.

Click the Validate button to check if the defined parameters are of the correct type and all required parameters have been filled out for configuring the component. If the configuration is erroneous or incomplete, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing or faulty elements appears at the problematic field. If the configuration of the component is valid, after clicking the Validate button, a 'Component validation successful' notification is shown.
Save the component configuration by clicking the Save button.

6.4.6. File

The File configuration element enables the administrator to upload files used by various plugins.

6.4.6.1. Configuring File Bricks

Click on the BRICKS main navigation item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select File.

Figure 23. File main page in the Web User Interface

Click on the New navigation button to create a File Brick.
Choose the type of the file brick from the drop-down list.
Upload a file according to the selected type.
Click the Validate button to check if the defined parameters are of the correct type and all required parameters have been filled out for configuring the component. If the configuration is erroneous or incomplete, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing or faulty elements appears at the problematic field. If the configuration of the component is valid, after clicking the Validate button, a 'Component validation successful' notification is shown.
Save the component configuration by clicking the Save button.

The following values can be configured for the File Brick:

Figure 24. Configuring File in the Web User Interface

Table 43. File configuration parameters
Key	Values	Description
Name*	Free text. Alphanumeric, may contain underscores, may not start with a number.	It defines the file-related configuration.
Type*	The available values are: Swagger OpenAPI 3.0 OpenAPI 3.1 XSD WSDL CA Certificates Diffie-Hellman Parameters TLS Key Client Certificate Server Certificate See table Requirements for specific file types for specific requirements for each type.	The type selected here defines by which PLUGINS it can be used. The file uploaded here with the Type Swagger, for example, can be used by Swagger Plugins.
File*	The required file can be uploaded here.
Passphrase	String value, could be empty.	Only available for TLS Key files. The passphrase to access an encrypted private key. Leave empty if the private key is unencrypted.

Table 44. Requirements for specific file types
File type	Requirements
CA	The file must be a flat ZIP file with the CA certificates inside. It can contain copies of the certificates named following the `<hash>.0` format. The value of the `<hash>` part can be produced with the following command: `openssl x509 -noout -hash -in /path/to/cert/file`. These copies will be generated automatically after saving if they are not present already, and the original File brick will be overwritten. It can contain CRL files, and it also can contain the copies of them following the `<hash_of_the_related_ca_file>.r0` format. The hash can be produced as described above. These copies will be generated automatically after saving if they are not present already, and the original File brick will be overwritten.
Certificates	The file must be a flat ZIP file with the certificates inside. The certificates must be named after IPv4 or IPv6 addresses.
Diffie-Hellman Parameters	Must be in PEM format. Must be a parameters file, such as one generated by the `openssl dhparam` utility.
TLS Key	Must be in PEM format. Must be a private key file. Could be encrypted or unencrypted. If the file is encrypted, the passphrase must be provided in the Passphrase field.
Client Certificate	Must be in PEM format. Must be a certificate file. Must have a Common Name attribute, and have the CLIENT_AUTH ExtendedKeyUsage.
Server Certificate	Must be in PEM format. Must be a certificate file. Must have a Common Name attribute, and have the SERVER_AUTH ExtendedKeyUsage.
Swagger	The file must be a Swagger schema as described in the OpenAPI 2.0 specification.
OpenAPI 3.0	The file must be an OpenAPI 3.0 schema as described in the OpenAPI 3.0 specification.
OpenAPI 3.1	The file must be an OpenAPI 3.1 schema as described in the OpenAPI 3.1 specification.
XSD	The file must be an XML Schema Definition as described in XML Schema Part 1: Structures, XML Schema Part 2: Datatypes, XSD 1.1 Part 1: Structures and XSD 1.1 Part 2: Datatypes.
WSDL	The file must be a WSDL service descriptor as described in the Web Services Description Language 1.1 specification or in the Web Services Description Language 2.0 specification.

File editor

Files in certain File brick types are editable when configuring the File brick. A File editor is available for the following types:

Swagger
OpenAPI 3.0
OpenAPI 3.1

The uploaded file can be opened and edited by clicking the Edit button. The contents of the file open inside a new window, with the Edit tab selected:

The editor can be closed without saving any changes to the file with the Close button. The changes are saved and the editor is closed with the Save button.

The Overview tab shows errors if there are any, and the structure of the schema that the file describes:

6.4.7. Common configuration elements for BRICKS

6.4.7.1. Extractors

Extractors are used to extract data from the call.

Extractors are not independent configuration components, but common configuration elements that are utilized by Matchers and Selectors. In fact, when configuring matchers and selectors, it is extractors that are listed at their type fields. Extractors are configured and used as part of matchers and selectors. There are no named extractors.

Most extractors return simple string values. However, some (might) return dictionaries. For example, you can get all the HTTP headers, or all the URI query parameters.

See the Extractor types for more details on extractors and their configuration options.

The following table provides details on extractor types:

Key Description

Method

Extracts the HTTP method of the request. It does not require configuration.

Status

Extracts the status code of the response. It does not require configuration.

JMESPath

Extracts data from the body of a JSON call with the help of a JMESPath expression.

JMESPath is a query language for JSON. It is a very versatile tool for extracting the needed information from the body of the call, and organizing it according to requirements. A complete explanation on how to write JMESPath expressions is not in the scope of this document.

To learn more about it visit the JMESPath website:

There is a tutorial.
There are examples.
There is also a formal specification.

Header

Extracts the value of an HTTP header. It is valid for some HTTP headers to be present more than once in a call. In this case, all the values are extracted as a list. It provides the name of the header in the configuration.

Header Force List

A Header extractor that returns a list even if there is only a single extracted value.

Header First

A Header extractor that only returns the first extracted value even if there is a list of extracted values.

Headers

The Headers extractor returns all the headers from the call. The results are stored as a dictionary, therefore it is recommended to omit the 'save as' key if you use this from a selector. It is valid for some HTTP headers to be present more than once in a call. In such cases all the values are stored under the header’s key as a list. It does not require configuration.

Fraud Detector Score

Extracts the score value provided by the Fraud Detector plugin.

URI

Extracts the whole request URI as received from the client. It does not require configuration.

URI Netloc

Extracts the network location in the URI. It does not require configuration.

It includes:

username and password if present
host
port if present unless scheme default

URI Origin

Extracts the origin part of the URI. It does not require configuration.

It includes:

scheme
host
port if present, unless the default port for the scheme is used

URI Scheme

Extracts the scheme of the request (http or https). It does not require configuration.

URI Username

Extracts the username in the request if present. It does not require configuration.

URI Password

Extracts the password in the request if present. It does not require configuration.

URI Host

Extracts the host in the request. It does not require configuration.

URI Port

Extracts the port of the request, the default port — that is 80 and 443 for HTTP and HTTPS, respectively — even if it is not not displayed explicitly in the request. It does not require configuration.

URI Path

Extracts the path part of the URI. It does not require configuration.

The path is normalized to allow more robust matching and cleaner reporting. This means that:

If the path is missing / it is extracted.
Repeating forward-slash (/) characters are replaced with a single one.
dot (.) and double-dot (..) path segments are resolved.

Consequently, if the path present in the URI was //some/./nothere/../resource///./somewhere the path would be /some/resource/somewhere.

If you need to extract the path exactly as received, use URI raw path parameter.

URI Raw Path

Extracts the path part of the URI, without the normalization of URI path carried out.

NOTE: If the path is missing a single forward slash ("/") is extracted.

It does not require configuration.

URI Raw Query

Extracts the query part of the URI as a string. It does not require configuration.

URI Query

Extracts the query part of the URI. It does not require configuration.

URI Query Param

Extracts the value of a query parameter. It is also valid for URIs to include a query parameter more than once. That is, it could be 'foo=bar&qux=quz&foo=baz'. In this case both values are extracted as a list. Provide the name of the parameter in the configuration.

URI Query Param Force List

An URI Query Param extractor that returns a list even if there is only a single extracted value.

URI Query Param First

An URI Query Param extractor that only returns the first extracted value even if there is a list of extracted values.

Client Address

Extracts the client’s IP address.

Client Port

Extracts the client’s port (TCP).

Server Address

Extracts the server’s IP address.

Server Port

Extracts the server’s port (TCP).

Parsed Content

Extracts the content. It does not require configuration.

Raw Content

Extracts the raw bytes of the request or response. It saves the results as a base64 encoded string.

Text Content

Extracts the request’s or response’s content as a decoded string.

Cookie

Extracts the values for a given key from the Cookie HTTP header. It is valid for multiple key-value pairs to be present in a Cookie header for the same key. In this case, all the values are extracted as a list. It requires the name of the Cookie key in the configuration.

Cookie Force List

A Cookie extractor that returns a list even if there is only a single extracted value.

Cookie First

A Cookie extractor that only returns the first extracted value even if there is a list of extracted values.

Cookies

The Cookies extractor returns all the key-value pairs from the Cookie header. The results are stored as a dictionary, therefore it is recommended to omit the 'save as' key if you use this from a selector. It is valid for multiple key-value pairs to be present in a Cookie header for the same key. In such cases, all the values are stored under the Cookie’s key as a list. It does not require configuration.

Content Type

Extracts the content type from the HTTP header. It does not require configuration.

Content Type Charset

Extracts the charset from the content type HTTP header. It does not require configuration.

Call Direction

Extracts the call direction (request, response). It does not require configuration.

Session Id

Extracts the internal identifier of the HTTP session in keep-alive HTTP connections. Its 'Include request counter' option enables adding a request counter representing the number of requests in the session. See [session-id] for details.

Backend Response Time

Extracts the time spent between the sending the request towards the server and receiving the response from the server, in milliseconds. Only returns a value in a response flow.

Backend Name

Extracts the name of the Backend Service component handling the call.

Endpoint Name

Extracts the name of the Endpoint Service component handling the call.

Static

Extracts a string, integer, number, object, array, boolean as string from the configuration.

Timestamp

Extracts the current time. Also see the tables on Configuring timestamps and Timestamp format options.

XPath

Extracts data from the body of an XML call with the help of a XPath expression.

XPath is a query language for XML. It is a very versatile tool for extracting the needed information from the body of the call, and organizing it according to needs.

A complete explanation on how to write XPath expressions is not in the scope of this document. To learn more about it visit the main website.

Also see table XPath extractor configuration options.

Provide the XPath expression in the configuration. Depending on the expression, the return value is a single node or a list of nodes. If you want a single value or a list independent from the expression, use XPath First or XPath Force List.

XPath Force List

Works like XPath but it returns a list even if there is only a single extracted value.

XPath First

Works like XPath but it only returns the first extracted value even if there is a list of extracted values.

SOAP Version