Copyright
Copyright © 2019 Balasys IT Ltd.. All rights reserved. This document is protected by copyright and is distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this document may be reproduced in any form by any means without prior written authorization of Balasys.
This documentation and the product it describes are considered protected by copyright according to the applicable laws.
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)
Linux™ is a registered trademark of Linus Torvalds.
Windows™ 10 is registered trademarks of Microsoft Corporation.
The Balasys™ name and the Balasys™ logo are registered trademarks of Balasys IT Ltd.
The 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-02-26 .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. |
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.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
-
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:
-
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.9.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.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.9.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.9.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.
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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 {}
.
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. |
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 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. |
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.
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. |
Key | Default | Description |
---|---|---|
config.mgmt.configapi.log_level |
INFO |
The log level can be set to DEBUG, INFO, WARNING, ERROR, CRITICAL. |
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.
$ 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:
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 |
|
config.mgmt.configapi.ldap.bind_user |
The service user to use, for searching the LDAP server. If |
|
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 |
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:
-
-
Port
-
Endpoint
For more details on the Listener's parameters, see Listeners’ configuration options.
-
-
-
Name
-
Url
For more details on the Endpoint's parameters, see Endpoint configuration.
-
-
-
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.
6.3.1. Navigation
The PAS Web UI has the following navigation areas:
The navigation areas are described here in more details:
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:
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:
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:
-
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
Error policies can be configured from the BRICKS main menu item.
-
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.
-
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:
-
Click on the New navigation button to create an error policy.
Error Policies have default values for each of their fields.
The following values can be configured for the Error Policy Brick:
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 |
It defines what action shall take place if there is an error on the request side:
|
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 |
It defines what action shall take place if there is an error on the request side:
|
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. |
The default values in the above table represent the hard coded default values. They form a strict security policy: all errors are fatal, and only mistakes made by the client are reported in detail.
For configuring error policies, continue with completing the following steps:
-
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 suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button.
The error policies configured here can be used in the Plugin’s configuration, by referencing their name.
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:
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
Matchers can be configured from the BRICKS main navigation item.
-
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.
-
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:
-
Click on the New navigation button to configure a matcher.
The following values can be configured for the Matcher Brick:
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. |
-
Provide the name of the matcher.
-
Choose the type of the matcher 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 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:
Consequently, in this example above both To match against the header named server the key will be
The syntax of this matcher differs from the others because the name of the Header must be added.
|
||||
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.
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:
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.
|
||||
Fraud Detector Score |
Matches the score value provided by the Fraud Detector plugin. |
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
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:
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:
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:
Consequently, if the path present in the URI was 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.
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 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. |
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:
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.
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.
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.
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:
|
|
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.
|
|
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. |
-
Configure the necessary parameters with the help of the above tables.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button to save the configured matcher.
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
The selector can be configured from the BRICKS main navigation item.
-
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.
-
Select Selectors.
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:
-
Click on the New navigation button to configure the Selector.
The following values can be configured for the Selector Brick:
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.
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.
|
|
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:
|
|
Expression* |
A regular expression specifies a set of strings that match it. |
||
Time Format |
A valid time format string in text. |
YYYY-MM-DDT |
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. |
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. |
-
Name the Selector key.
-
Fill in any more desired parameters.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button if you have configured all the required parameters.
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
The Insight Target can be configured from the BRICKS main navigation item.
-
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.
-
Select Insight Target.
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:
-
Click on the New navigation button to configure the Insight Target.
The following values can be configured for the Insight Target Brick:
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:
|
|
|
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. |
-
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.
The following table presents the configuration parameters for the Local log Insight Target type:
Key | Values | Default value | Description |
---|---|---|---|
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 |
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:
Key | Values | Default value | Description |
---|---|---|---|
Flatten |
True or False. |
True |
Flattens the Insight Target message. |
Flatten Separator |
/ |
The separator in the flattened message. |
|
Remote Connection |
|
|
|
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 |
|
|
|
The following table presents the configuration parameters for the Elastic Insight Target type:
Key | Values | Default value | Description |
---|---|---|---|
Flatten |
True or False. |
True |
It flattens the Insight Target message. |
Flatten Separator |
/ |
The separator in the flattened message. |
|
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:
|
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. |
-
Configure any more desired parameter details.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click Save to save your configuration settings for the Insight Target.
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 the TLS
TLS can be configured from the BRICKS main navigation item.
-
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.
-
Select TLS.
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:
-
Click on the New navigation button to configure TLS.
The following values can be configured for the TLS Brick:
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 the Client TLS
The following parameters need to be configured for Client TLS:
-
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:
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.
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.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.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:
|
full |
It defines the trust level for certificate verification:
|
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:
|
hard_fail |
The revocation check type for all certificates in the chain, except the Leaf Certificate:
|
Leaf Revocation Check Type |
The values can be selected from the drop-down list. The available values are:
|
hard_fail |
The revocation check types for the Leaf certificate are as follows:
|
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Save the Client TLS configuration by clicking Save.
6.4.5.1.2. Configuring Backend TLS
The following parameters need to be configured for Backend TLS:
-
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:
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:
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.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.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:
|
full |
The trust level for certificate verification:
|
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:
|
soft_fail |
The revocation check types for all certificates in the chain, except for the Leaf Certificate are as follows:
|
Leaf Revocation Check Type |
The values can be selected from the drop-down list. The available values are:
|
soft_fail |
The revocation check type for the Leaf Certificate.
|
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button if you have configured all the required parameters.
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:
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
The following parameters need to be configured for Syslog TLS:
-
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:
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.
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 suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Save the Syslog TLS configuration by clicking Save.
6.4.5.1.5. Configuring Elastic TLS
The following parameters need to be configured for Elastic TLS:
-
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:
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.
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.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 suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Save the Elastic TLS configuration by clicking Save.
6.4.6. File
The File configuration element enables the administrator to upload files used by various plugins.
6.4.6.1. Configuring File
File can be configured from the BRICKS main navigation item.
-
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.
-
Select File.
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:
-
Click on the New navigation button to configure File.
The following values can be configured for the File Brick:
Key | Values | Default | 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:
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. |
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Save the configuration by clicking the Save button.
File type | Requirements |
---|---|
CA |
|
Certificates |
|
Diffie-Hellman Parameters |
|
TLS Key |
|
Client Certificate |
|
Server Certificate |
|
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. |
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:
|
||
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:
|
||
URI Origin |
Extracts the origin part of the URI. It does not require configuration. It includes:
|
||
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:
Consequently, if the path present in the URI was 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. |
||
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 |
Extends the XPath extractor with predefined expressions. Extracts the SOAP message version. It identify with the SOAP namespace. Possible values:
|
||
SOAP Envelope |
Extends the XPath extractor with predefined expressions. Extracts the SOAP envelope. |
||
SOAP Header |
Extracts the SOAP header. Extends the XPath extractor with predefined expressions. |
||
SOAP Body |
Extracts the SOAP body. Extends the XPath extractor with predefined expressions. |
||
SOAP Fault |
Extracts the SOAP fault. Extends the XPath extractor with predefined expressions. |
||
SOAP Fault Code |
Extracts the SOAP fault 'code'. Extends the XPath extractor with predefined expressions. This extractor expression depends on the SOAP version.
|
||
SOAP Fault Detail |
Extends the XPath extractor with predefined expressions. Extracts the SOAP fault 'detail'. This matcher expression depends on the SOAP version.
|
||
SOAP 1.1 Fault Faultstring |
Extends the XPath extractor with predefined expressions. Extracts the SOAP fault 'faultstring'. This extractor only works with SOAP version 1.1. |
||
SOAP 1.1 Fault Faultactor |
Extends the XPath extractor with predefined expressions. Extracts the SOAP fault 'faultactor'. This extractor only works with SOAP version 1.1. |
||
SOAP 1.2 Fault Reason |
Extends the XPath extractor with predefined expressions. Extracts the SOAP fault 'Reason'. This extractor only works with SOAP version 1.2. |
||
SOAP 1.2 Fault Node |
Extends the XPath extractor with predefined expressions. Extracts the SOAP fault 'Node'. This extractor only works with SOAP version 1.2. |
||
SOAP 1.2 Fault Role |
Extends the XPath extractor with predefined expressions. Extracts the SOAP fault 'Role'. This extractor only works with SOAP version 1.2. |
You can still use Save as for extractors returning dictionaries. For example, you can save all the headers under the headers key and the URI query parameters under the parameters key.
|
Timestamp extractors can be configured as follows:
Name | Default | Description |
---|---|---|
Time Zone |
'UTC' |
Set the time zone.
|
Time Format |
YYYY-MM-DDT |
Set the format. See: Timestamp format options |
Use Request Start Time |
True |
If set to True, uses the request’s start time. This value is set once for each call. If set to False, uses the time when the selector is processed during a session. This value can change every time the selector’s value is queried during a call. |
Name | Token | Output |
---|---|---|
Year |
YYYY |
2000, 2001, 2002 … 2012, 2013 |
Month |
MMMM |
January, February, March |
Day of Year |
DDDD |
001, 002, 003 … 364, 365 |
Day of Month |
DD |
01, 02, 03 … 30, 31 |
Day of Week |
dddd |
Monday, Tuesday, Wednesday |
Hour |
HH |
00, 01, 02 … 23, 24 |
AM / PM |
A |
AM, PM, am, pm |
Minute |
mm |
00, 01, 02 … 58, 59 |
Second |
ss |
00, 01, 02 … 58, 59 |
Sub-second |
S… |
0, 02, 003, 000006, 123123123123 |
Time zone |
ZZZ |
Asia/Baku, Europe/Warsaw, GMT |
Seconds Timestamp |
X |
1381685817, 1381685817.915482 |
ms or µs Timestamp |
x |
1569980330813, 1569980330813221 |
Key | Default | Description |
---|---|---|
xpath_expression |
The expression to extract the node from the call to match against. |
|
namespaces |
Defines the XML namespaces. |
|
clear_text |
False |
Whether to remove white spaces at the beginning and at the end of the string. |
6.4.7.2. Comparators
Comparators are used for comparing the pattern with the result of the XPath expression.
Key | Description | Parameters | ||
---|---|---|---|---|
Equals |
Matches if the parameter is exactly the same as the value matched. For matchers that work with numeric data type or with IP addresses it validates if the input is a valid number or IP address. |
Ignorecase: Case differences (lower case, upper case) are ignored. When the present VaLuE would match value. 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. |
||
Not equals |
Matches if the parameter is not exactly the same as the value matched. For matchers that work with numeric data type or with IP addresses it validates if the input is a valid number or IP address. |
Ignorecase: Case differences are ignored. When the present VaLuE would not match vAlUe. 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. |
||
Starts with |
Matches if the value starts exactly with the pattern. |
Ignore case: Case differences are ignored. When the present VaLuE would match value_given. |
||
Ends with |
Matches if the value ends exactly with the pattern. |
Ignore case: Case differences are ignored. When the present VaLuE would match given_value. |
||
Contains |
Matches if the exact pattern is found somewhere in the value. |
Ignore case: Case differences are ignored. When the present VaLuE would match some-value-given. |
||
Pattern |
The Pattern treats the input as Unix shell-style wildcards. There are special characters used in shell-style wildcards:
|
Ignore case: Case differences are ignored. When the present VaLuE would match some-value-given. |
||
Regex |
Regex treats input as a regular expression for matching. Consult Python’s regular expression documentation and their Regular Expression HOWTO. |
|
||
Minimum |
Matches if the pattern is larger or equal to the value. |
|||
Maximum |
Matches if the pattern is smaller or equal to the value. |
|||
Range |
Matches if the value is between the limits in the pattern, including boundaries. The format of the pattern must be minimum..maximum. |
|||
Status class |
Status class is a special comparator for conveniently matching HTTP status code classes in a Status matcher. It takes the name of the class and checks if the status code is in the given range as stated in Checking status code range. |
|||
Subnet |
The subnet comparator examines if an extracted IP address 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). |
Pattern | Status code range | Description |
---|---|---|
Info |
1xx |
Informational response |
Success |
2xx |
Successful response |
Redirect |
3xx |
Redirects |
Client Error |
4xx |
Client Errors |
Server Error |
5xx |
Server Errors |
6.5. PLUGINS - Configuration units
A plugin is an element of the security flow that applies a specific security function. Plugins have different types based on the role they do:
Plugins are named, so that they can be referenced in other parts of the configuration.
This means that Plugin configurations are reusable. |
Certain Plugins 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:
Default object name | Key |
---|---|
default_json |
Serializer |
default_xml |
Serializer |
default_json |
Deserializer |
default_xml |
Deserializer |
default |
Compressor |
default |
Decompressor |
6.5.1. Common Plugin parameters
Regardless of what plugins do, all plugins share some common parameters.
Key | Values | Default value | Description |
---|---|---|---|
Matcher |
Reference to a Matcher Brick. |
Always: If the value is not defined, the plugin is always executed. |
Optional parameter. It decides if the Plugin should be executed based on the call’s details. If no matcher is configured the Plugin is always executed. For more details, see Matcher. |
Error Policy |
Reference to an Error Policy Brick. |
Optional parameter. It defines a custom error policy to be applied if the Plugin reports an error. The settings of the Error policy here override the Security Flow’s default error policy. If no error policy is configured, the plugin type’s default error policy is applied. For more details, see Error Policy. |
Plugins are always named so that their names refer to a Plugin that represents a certain configuration. The names themselves are referenced from the Security Flow.
6.5.2. Enforcer
An Enforcer Plugin validates calls against externally defined schemas.
The Plugin supports validation against OpenAPI (Swagger) schemas, XSD schemas, WSDL schema or WAF ruleset.
Understanding the format of these schemas is not in the scope of this document. Further information is available at:
The Enforcer Plugin uses its own default error policy, that is, the 'enforcer_default' error policy. The Plugin overrides the following fields of the default error policy:
Policy Setting | Default |
---|---|
request_code |
422 |
request_message |
Request Error |
Problems are considered errors that lead to the termination of the call. Problems in the request are reported back to the client, while errors in the response are suppressed to avoid information leak.
See Error Policy to understand how defaults are applied.
6.5.2.1. Configuring Enforcer Plugins
Enforcer plugins can be configured from the PLUGINS main navigation item.
-
Click on the PLUGINS main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of PLUGINS.
-
Select Enforcer plugin.
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:
The following values can be configured for the Enforcer Plugin:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Free text. Alphanumeric, may contain underscores, may not start with a number. |
This name identifies the Enforcer Plugin. The name of the plugin can be referenced from other parts of the configuration. |
|
Type* |
Can be selected from the drop-down list. The available values are:
|
The type of the Enforcer plugin. |
|
Matcher |
Reference to a Matcher Brick. |
Always: If the value is not defined the plugin is always executed. |
It decides if the Plugin should be executed based on the call’s details. For details see Matcher. If omitted the Plugin is always executed. |
Error Policy |
Reference to an Error Policy Brick. |
enforcer_default |
It defines a custom error policy to be applied if the Plugin reports an error. The settings of the Error policy here override the Security Flow’s default error policy. For details see Error Policy. |
Swagger*/OpenAPI 3.0*/OpenAPI 3.1*/WSDL*/Operations* |
Depending on which type of the component was selected above, the following values are available:
|
The Swagger enforcer Plugin validates against OpenAPI 2.0 schemas. The OpenAPI 3.0 enforcer Plugin validates against OpenAPI 3.0 schemas. The OpenAPI 3.1 enforcer Plugin validates against OpenAPI 3.1 schemas. WSDL enforcer Plugin validates against WSDL 1.0-2.0 schemas. XSD enforcer Plugin validates against XSD schemas. |
|
Harden Additional Properties Defaults |
True or False. |
False |
Only available for OpenAPI 3.0 and OpenAPI 3.1 enforcers. If set to True, the Enforcer will check calls as if the default value of |
Request Limit in Kilobytes |
100000 |
Only available for WAF enforcers. It defines the size limit for requests in kilobytes. |
XSD has the following configuration options for the Operations parameters:
Key | Default | Description |
---|---|---|
URI Path |
* |
The pattern for uri_path. |
Choose Method |
The method of the HTTP message. The following values are available for Method:
|
|
Status |
The status of the HTTP message. |
|
Choose Call Direction |
The direction of the message, which must be either request or response. |
|
Choose File |
The XSD schema. |
-
Name the Enforcer Plugin.
-
Choose the type of the Enforcer plugin.
-
Choose an Error policy from the drop-down list. The drop-down list will offer the error policy options configured under BRICKS.
-
Choose a Matcher from the drop-down list. The drop-down list will offer the matcher options configured under BRICKS.
-
Depending on the choice of the Enforcer plugin type selected earlier, different fields appear here for further configuration:
-
Swagger - Upload the Swagger file if the Enforcer type selected at Type field was Swagger.
-
OpenAPI 3.0 - Upload the OpenAPI 3.0 file if the Enforcer type selected at Type field was OpenAPI 3.0.
-
OpenAPI 3.1 - Upload the OpenAPI 3.1 file if the Enforcer type selected at Type field was OpenAPI 3.1.
-
WSDL - Upload the WSDL file if the Enforcer type selected earlier was WSDL.
-
Operations - Fill in the Operations fields according to XSD enforcer plugin configuration options for Operations if the Enforcer type selected earlier was XSD.
-
Request Limit in Kilobytes - Fill in a number if you want to overwrite the default setting.
-
Harden Additional Properties Defaults - Choose the desired setting.
-
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
6.5.2.2. Swagger
The Swagger enforcer Plugin validates against OpenAPI 2.0 schemas.
The Plugin needs the schema definition file of the API Endpoint. This file must be in JSON or YML format.
6.5.2.3. OpenAPI 3.0
The OpenAPI 3.0 enforcer Plugin validates against OpenAPI 3.0 schemas.
The Plugin needs the schema definition file of the API Endpoint. This file must be in JSON or YML format.
6.5.2.4. OpenAPI 3.1
The OpenAPI 3.1 enforcer Plugin validates against OpenAPI 3.1 schemas.
The Plugin needs the schema definition file of the API Endpoint. This file must be in JSON or YML format.
6.5.2.5. XSD
XSD enforcer Plugin validates against XSD schemas. Both XSD 1.0 and 1.1 are supported.
As XSD enforcer requires parsed XML content an xml deserializer plugin needs to be included before XSD enforcer. |
In the XSD enforcer you can define operations. Each operation contains criteria for identifying the call, and path of an XSD schema. If the HTTP message meets all criteria, its content will be validated using the schema.
XSD enforcer schema must contain at least one operation.
6.5.2.6. WSDL
WSDL enforcer Plugin validates against WSDL 1.0-2.0 schemas.
As WSDL enforcer requires parsed XML content, an xml deserializer plugin needs to be included before WSDL enforcer. |
The Enforcer Plugin uses its own default error policy, that is, the 'enforcer_default' error policy. The Plugin overrides the following fields of the default error policy:
Policy Setting | Default |
---|---|
request_code |
422 |
request_message |
Request Error |
Problems are considered errors that lead to the termination of the call. Problems in the request are reported back to the client, while errors in the response are suppressed to avoid information leak.
See Error Policy to understand how defaults are applied.
The plugin needs the schema definition file. This file must be in XML format.
WSDL schema validates request and response as well. Make sure that wsdl enforcer included in request and response flow as well. |
In simple cases — when the listener/endpoint is serving a single version of a single API endpoint — a matcher is usually not needed as the schemas define all known URLs in the API. If however multiple API endpoints are consolidated under a single endpoint definition, you can define multiple enforcers each matching on a sub-path by using an URI path matcher and putting them all in the Security Flow. |
6.5.2.7. WAF
The Web Application Firewall (WAF) enforcer Plugin protects against known attacks. The list of known attacks is updated by the WAF Ruleset Updater.
6.5.3. Filter
Filter Plugins are lightweight alternatives of Enforcer Plugins for filtering unwanted traffic. They only consist of a matcher and an error policy. If the matcher matches, the error policy is applied. This way you can use matchers inline, instead of creating a whole schema-based Enforcer Plugin for the simple use cases.
6.5.3.1. Configuring Filter Plugins
The Filter Plugin can be configured under the PLUGINS main navigation unit.
-
Click on the PLUGINS main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of PLUGINS.
-
Select Filter plugin.
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:
The following values can be configured for the Filter Plugin:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Free text. Alphanumeric, may contain underscores, may not start with a number. |
The name identifying the Filter Plugin. This name of the plugin can be referenced from other parts of the configuration. |
|
Matcher |
Reference to a Matcher Brick. |
Always: If the value is not defined the plugin is always executed. |
It decides if the Plugin should be executed based on the call’s details. For details see Matcher. If omitted the Plugin is always executed. |
Error Policy |
Reference to an Error Policy Brick. |
error_policy |
It defines a custom error policy to be applied if the Plugin reports an error. The settings of the Error policy here override the Security Flow’s default error policy. For details see Error Policy. |
Body |
Can be defined in free text. |
The body of the message sent in case an error policy is applied. |
|
Content Type |
The content type of HTTP error request sent, if the filter stops the call. It can be referenced by its name. |
Make sure that any component referenced in the configuration of this component, for example an Error policy or a Matcher selected from the drop-down lists, must remain part of the configuration later as well. Removing any of the referenced components might lead to invalid configuration. |
-
Add the name of the Filter Plugin.
-
Add the Body content for the error policy. (Optional)
-
Define the Content type.
-
Choose an error policy from the drop-down list. (Optional)
-
Choose a matcher from the drop-down list. (Optional)
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
The Plugin does not override any of the default error policy options.
Problems are considered errors that lead to the termination of the call. Problems in the request are reported back to the client, while errors in the response are suppressed to avoid information leak.
See Error Policy to understand how defaults are applied.
If you omit the matcher, the Plugin will always be executed. For Filter plugins this means aborting all calls. |
6.5.4. Fraud Detector
The Fraud Detector Plugin, leveraging the data collected from the calls by the selectors, evaluates the level of risk with regards to the call. The risk calculated by the Fraud Detector plugin is translated to a score between 0.0 and 100.0. The lower the score is, the more secure and trustworthy the actual call is. Consequently, the value 0.0 means that the call is perfectly secure, until the value 100.0 identifies a malicious act with the call.
6.5.4.1. Configuring Fraud Detector
The Fraud Detector Plugin can be configured under the PLUGINS main navigation unit.
-
Click on the PLUGINS main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of PLUGINS.
-
Select Fraud Detector plugin.
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:
The following values can be configured for the Fraud Detector Plugin:
Key | Values | Default value | Description | ||
---|---|---|---|---|---|
Name* |
Free text. Alphanumeric, may contain underscores, may not start with a number. |
The name identifying the Fraud Detector. This name of the plugin can be referenced from other parts of the configuration. |
|||
Matcher |
Reference to a Matcher Brick. |
Always: If the value is not defined the plugin is always executed. |
It decides if the Plugin should be executed based on the call’s details. For details see Matcher. If omitted the Plugin is always executed. |
||
Error Policy |
Reference to an Error Policy Brick. |
error_policy |
It defines a custom error policy to be applied if the Plugin reports an error. The settings of the Error policy here override the Security Flow’s default error policy. For details see Error Policy. |
||
Selectors* |
A list of references to Selector Bricks. |
A list of Selector that collect information from the call. Selectors can be configured as listed in Selector configuration for the Fraud Detector Plugin.
|
Make sure that any component referenced in the configuration of this component, for example an Error policy or a Matcher selected from the drop-down lists, must remain part of the configuration later as well. Removing any of the referenced components might lead to invalid configuration. |
-
Add the name of the Fraud Detector.
-
Choose an error policy from the drop-down list. (Optional)
-
Choose a matcher from the drop-down list. (Optional)
-
Choose a Selector from the drop-down list. When it is selected click on the plus sign to add it to the configuration.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
See Error Policy to understand how they shall be applied here.
6.5.5. Insight
It is a Plugin that extracts various data from the call and sends it to external systems (log servers, SIEMs, and other data analysis tools).
6.5.5.1. Configuring Insight Plugins
The Insight Plugin can be configured under the PLUGINS main navigation unit.
-
Click on the PLUGINS main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of PLUGINS.
-
Select Insight plugin.
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:
-
Click the New button to create an Insight Plugin configuration.
The following values can be configured for the Insight Plugin:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Free text. Alphanumeric, may contain underscores, may not start with a number. |
The name identifying the insight. This name of the insight can be referenced from other parts of the configuration. |
|
Matcher |
Reference to a Matcher Brick. |
Always: If the value is not defined the plugin is always executed. |
It decides if the Plugin should be executed based on the call’s details. For details see Matcher. If omitted the Plugin is always executed. |
Error Policy |
Reference to an Error Policy Brick. |
insight_default |
It defines a custom error policy to be applied if the Plugin reports an error. The settings of the Error policy here override the Security Flow’s default error policy. For details see Error Policy. |
Message |
Can be defined in free text. |
"" |
The message part of the log message. |
Selectors* |
A list of references to Selector Bricks. |
A list of Selectors that collect information from the call. It is possible to multiselect more than one selector in this list by clicking on them. The multiple selected elements can then be added to the configuration by clicking on the plus sign. |
|
Targets* |
A list of references to Insight Target Bricks. |
A list of Insight Targets where the collected information will be sent to. |
The Plugin uses the default Error policy by default, that is, the 'insight_default'.
The Plugin overrides the following fields of the default error policy:
Policy Setting | Default |
---|---|
request |
log |
response |
log |
Problems are considered errors that only need to be logged. If that is overridden then problems in the request are reported back to the client, while errors in the response are suppressed to avoid information leak.
See Error Policy to understand how defaults are applied.
The Plugin collects the information from all the selectors and sends them to all the targets.
The collected information from all the selectors is arranged into a dictionary: a list of key — value pairs. The key can be configured in each selector. Certain selectors might return complex data structures, that are made up of other dictionaries and/or lists. To ensure compatibility with a wide range of Insight Target types, such results are flattened. The path inside the complex data structure is encoded into the key for each value. More details are available on this in Data flattening.
-
Add the name of the Insight Plugin.
-
Choose an error policy from the drop-down list. (optional)
-
Choose a matcher from the drop-down list. (optional)
-
Add the message content for the error policy. (optional)
-
Choose a selector from the drop-down list.
-
Select the Insight Target.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
6.5.6. Serializer
The Serializer Plugin is responsible for serializing the structured data to the format of the HTTP message’s body.
Serialization needs to be done before compression. A typical Security Flow configuration starts with a Decompressor followed by a Deserializer and finishes with a Serializer followed by a Compressor. This ensures that transferred HTTP bodies are syntactically correct and that they are reconstructed to avoid transferring potentially crafted content.
The Serializer Plugin understands the Content-Type HTTP header and can work with JSON and XML content.
6.5.6.1. Configuring Serializer Plugins
The Serializer can be configured under the PLUGINS main navigation unit.
-
Click on the PLUGINS main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of PLUGINS.
-
Select Serializer.
The configuration window that appears presents the default Serializers, as listed in Default objects - PLUGINS and the configuration values already set by the user:
-
Click the New button to create a serializer configuration.
The following values can be configured for the Serializer Plugin:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Free text. Alphanumeric, may contain underscores, may not start with a number. |
The name identifying the serializer. This name of the serializer can be referenced from other parts of the configuration, that is, the Plugin is reusable. |
|
Type* |
The value can be selected from a drop-down list. The value can be:
|
There are two types of predefined (de)serializer plugins. |
|
Matcher |
Reference to a Matcher Brick. |
Depending on which 'Type' was selected for the Serializer, the default value can be: json_content or xml_content. |
It decides if the Plugin should be executed based on the call’s details. For details see Matcher. If no matcher is configured the Plugin is always executed. |
Error Policy |
Reference to an Error Policy Brick. |
error_policy |
It defines a custom error policy to be applied if the Plugin reports an error. The settings of the Error policy here override the Security Flow’s default error policy. If no error policy is configured, the plugin type’s default error policy is applied. For details see Error Policy. |
The Plugin does not override any of the default error policy options.
Problems are considered errors that lead to the termination of the call. Problems in the request are reported back to the client, while errors in the response are suppressed to avoid information leak.
See Error Policy to understand how defaults are applied.
Continue configuring the serializer with the following steps:
-
Add the name of the serializer.
-
Select the type of the Serializer.
-
Choose an Error policy from the drop-down list.
-
Choose a Matcher from the drop-down list.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
6.5.7. Deserializer
It is a Plugin responsible for parsing the HTTP message’s body to structured data. This ensures that a message is well-formed. The structured data will also be consumed by other Plugins that operate on the body of the message.
A typical Security Flow configuration starts with a Decompressor followed by a Deserializer and finishes with a Serializer followed by a Compressor. This ensures that transferred HTTP bodies are syntactically correct and that they are reconstructed to avoid transferring potentially crafted content.
6.5.7.1. Configuring Deserializer Plugins
The Deserializer can be configured under the PLUGINS main navigation unit.
-
Click on the PLUGINS main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of PLUGINS.
-
Select Deserializer plugin.
The configuration window that appears presents the default Deserializers, as listed in Default objects - PLUGINS and the configuration values already set by the user:
-
Click the New navigation button to create a deserializer configuration.
The following values can be configured for the Deserializer Plugin:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Free text. Alphanumeric, may contain underscores, may not start with a number. |
The name identifying the deserializer. This name of the deserializer can be referenced from other parts of the configuration. |
|
Type* |
The value can be selected from a drop-down list. The value can be:
|
There are two types of predefined (de)serializer plugins. |
|
Matcher |
Reference to a Matcher Brick. |
Depending on which 'Type' was selected for the Deserializer, the default value can be: json_content or xml_content. |
It decides if the Plugin should be executed based on the call’s details. For details see Matcher. If omitted the Plugin is always executed. |
Error Policy |
Reference to an Error Policy Brick. |
error_policy |
It defines a custom error policy to be applied if the Plugin reports an error. The settings of the Error policy here override the Security Flow’s default error policy. For details see Error Policy. |
Charset Conflict |
|
drop |
This parameter needs to be configured in case the 'Type' of the Deserializer is set to XML. In XML messages, there might be a conflict in the definition of the character set. The XML and the HTTP headers might instruct to use different character sets. The conflicting information on the character set can be configured to be handled in two different ways, that is the call dropped, or the call maintained and the error logged, depending on the settings of this parameter. |
The Plugin does not override any of the default error policy options.
Problems are considered errors that lead to the termination of the call. Problems in the request are reported back to the client, while errors in the response are suppressed to avoid information leak.
See Error Policy to understand how defaults are applied.
-
Add the name of the deserializer.
-
Select the Type of the Deserializer.
-
Choose an Error policy from the drop-down list.
-
Choose a Matcher from the drop-down list.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
6.5.8. Compressor
The Compressor Plugin compresses the body of the HTTP message.
Compressors understand the Transfer-Encoding HTTP header and compress data by using the gzip, deflate and brotli algorithms.
6.5.8.1. Configuring Compressors
The Compressor can be configured under the PLUGINS main navigation unit.
-
Click on the PLUGINS main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of PLUGINS.
-
Select Compressor.
The configuration window that appears presents the default Compressor, as listed in Default objects - PLUGINS and the configuration values already set by the user:
-
Click the New button to create a Compressor configuration.
The following values can be configured for the Compressor Plugin:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Free text. Alphanumeric, may contain underscores, may not start with a number. |
The name identifying the compressor. This name of the compressor can be referenced from other parts of the configuration, that is, the Plugin is reusable. |
|
Matcher |
Reference to a Matcher Brick. |
Always: If the value is not defined the plugin is always executed. |
It decides if the Plugin should be executed based on the call’s details. For details see Matcher. If no matcher is configured the Plugin is always executed. |
Error Policy |
Reference to an Error Policy Brick. |
The Plugin has a default error policy. |
It defines a custom error policy to be applied if the Plugin reports an error. The settings of the Error policy here override the Security Flow’s default error policy. If no error policy is configured, the plugin type’s default error policy is applied. For details see Error Policy. |
Continue configuring the compressor with the following steps:
-
Add the name of the compressor.
-
Choose an Error policy from the drop-down list.
-
Choose a Matcher from the drop-down list.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
6.5.9. Decompressor
The Decompressor Plugin decompresses the body of the HTTP message.
Decompressors understand the Transfer-Encoding HTTP header and can work with content optionally compressed by the gzip, deflate and brotli algorithms.
6.5.9.1. Configuring Decompressors
The Decompressor can be configured under the PLUGINS main navigation unit.
-
Click on the PLUGINS main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of PLUGINS.
-
Select Decompressor.
The configuration window that appears presents the default Decompressor, as listed in Default objects - PLUGINS and the configuration values already set by the user:
-
Click the New button to create a Decompressor configuration.
The following values can be configured for the Decompressor Plugin:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Free text. Alphanumeric, may contain underscores, may not start with a number. |
The name identifying the decompressor. This name of the decompressor can be referenced from other parts of the configuration, that is, the Plugin is reusable. |
|
Matcher |
Reference to a Matcher Brick. |
Always: If the value is not defined the plugin is always executed. |
It decides if the Plugin should be executed based on the call’s details. For details see Matcher. If no matcher is configured the Plugin is always executed. |
Error Policy |
Reference to an Error Policy Brick. |
The Plugin has a default error policy. |
It defines a custom error policy to be applied if the Plugin reports an error. The settings of the Error policy here override the Security Flow’s default error policy. If no error policy is configured, the plugin type’s default error policy is applied. For details see Error Policy. |
Continue configuring the decompressor with the following steps:
-
Add the name of the decompressor.
-
Choose an Error policy from the drop-down list.
-
Choose a Matcher from the drop-down list.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
6.6. SERVICES - Configuration units
Proxedo API Security is based on a micro-services architecture.
6.6.1. Backend
Backends are a set of servers for a given API endpoint.
Their configuration is made up of two main parts:
-
a list of servers: port pairs and how to route traffic to them
-
TLS configuration for talking to the servers
6.6.1.1. Configuring the Backend
Backend can be configured under the SERVICES main navigation item.
-
Click on the SERVICES main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of SERVICES.
-
Select Backend.
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:
-
Click the New navigation button to create a Backend configuration.
The following values can be configured for the Backend Service:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Free text. Alphanumeric, may contain underscores, may not start with a number. |
The name identifying the backend. This name of the backend can be referenced from other parts of the configuration. |
|
Servers* |
There are two values to be configured:
|
The list of servers that serve API endpoint(s). See Backend servers' configuration for details. |
|
Load Balancing Method |
One of the following methods can be used:
If the value is not configured the default value will be added. |
Failover |
Load balancing method to use. |
Backend Timeout |
If the value is not configured the default value will be added. |
30000 |
The connection timeout in milliseconds of a server that is down. |
Backend Retry In |
If the value is not configured the default value will be added. |
600000 |
The timeout in milliseconds before a server -that was down- is restarted again. |
Use TLS |
True or False. |
False |
Enables using TLS in the connection towards the backend servers. |
Backend TLS* |
Reference to a File Brick of type Backend TLS. |
The TLS configuration towards the backend servers. See Configuring Backend TLS for details. Mandatory if Use TLS is set to True. |
-
Name the Backend configuration.
-
Provide the values for the Servers parameter: Host and Port.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
6.6.2. Endpoint
An endpoint holds together all the policies that apply to a certain API endpoint:
-
List of URLs
-
The default error policy for the endpoint
-
The backend to which requests will be forwarded
-
The security flow that will be applied to the traffic
6.6.2.1. Security Flow
The Security Flow definition in an endpoint lists what happens to the traffic on a given endpoint.
To understand how requests flow through PAS, see Understanding processing flow. The Security Flow starts when the Transport Director has already set up client connection and routed the request to the Flow Director. At this point the TLS and HTTP layers are already processed, but the content in the body of the request is available only in raw format and has not been parsed yet.
At this stage, the configuration security flow decides on what happens to the traffic by applying a list of Plugins one by one. Plugin is a collective name for Enforcers, Insights, Filters, etc. Once, all the plugins have processed the request, the control is handed back to the Transport Director which routes the request to a backend server, and comes back with the response after handling TLS and HTTP. At this point, the Flow Director applies another list of Plugins to response, and once done, it hands back the response to the Transport Director which in turn returns that to the client.
If at any point an error occurs, the error policy is applied — which might either mean to lead to logging the error or to terminating processing and returning an error indication to the client.
Plugins can override the endpoint’s error policy.
Also note that different Plugins need different data. An Insight that applies a JMESPath query needs parsed JSON, while one that extracts value from an HTTP header field does not. Other Plugins provide these required values, like a JSON deserializer Plugin. It is important that the Plugins are configured in such an order that the required data is made available beforehand.
6.6.2.2. Configuring the Endpoint
Endpoints can be configured under the SERVICES navigation item.
-
Click on the SERVICES main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of SERVICES.
-
Select Endpoint.
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:
-
Click the New navigation button to create an Endpoint configuration.
The following values can be configured for the Endpoint Service:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Free text. Alphanumeric, may contain underscores, may not start with a number. |
The name identifying the endpoint. This name of the endpoint can be referenced from other parts of the configuration. |
|
URLs* |
The URLs which the clients use to address the API endpoint. |
||
URL Rewrite Rule |
The URL by which the backend servers understand incoming requests. When set, two transformations take place:
|
||
SNI Rewrite Rule |
<Dynamic> |
It can be used to rewrite the Server Name Indication (SNI) field in a TLS handshake towards the backends. The <Dynamic> default value means that the SNI value used towards the backend will be the same as the value of the Host header, either coming from the client or defined in the URL Rewrite Rule. |
|
Backend* |
Reference to a Backend Service. |
Backends are a set of servers for a given API endpoint. For more details, see Backend. |
|
Failure Policy |
Two values have to be configured:
|
Silent: True; Code: 500 |
With the help of the Failure Policy, it can be configured whether the client shall receive notification or not, and whether the notification shall contain the code on the type of the failure. The values in details are as follows:
|
Security Flow* |
The security flow process requires the configuration of the following values, each containing a list of Plugins.
|
The values in details are as follows:
Note, that both for the Request and Response parameters, it is possible to multiselect more than one element in the list by clicking on them. The multiple selected elements can then be added to the configuration by clicking on the plus sign. |
-
Name the Endpoint Service.
-
Select the Backend parameter from the drop-down list. Backend servers are configured under the SERVICES main navigation item.
-
Complete a Security Flow from the configured (and the default) plugins. For more details, see Security Flow.
-
Choose the Request plugin from the drop-down list. The Plugin options available from the drop-down list have been configured under the PLUGINS main navigation item.
-
Choose the Response plugin from the drop-down list. The Plugin options available from the drop-down list have been configured under the PLUGINS main navigation item.
-
-
Provide the URL to address the API endpoint.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
While ports must be unique, as only one listener can bind to a specific port, it is perfectly valid to route incoming traffic from multiple listeners to the same endpoint. |
A typical security flow is configured with the plugins in the following order:
-
a Decompressor Plugin that decompresses the content of the request
-
a Deserializer Plugin that parses the content of the request
-
an Enforcer Plugins that ensure the call is valid
-
Insight Plugins that extract important data from certain calls
-
a Serializer Plugin that rebuilds the contents of the request
-
a Compressor Plugin that compresses the content of the request
The Plugin configurations are reusable. |
6.6.3. Listeners
Listeners are network endpoints where services are exposed to the network. They consist of:
-
a listening port
-
an optional client-side TLS configuration if HTTPS is used
-
a list of endpoints that handle the traffic.
Since these are the entry points for client traffic it must be routed here on the network.
6.6.3.1. Configuring Listeners
Listeners can be configured under the SERVICES navigation unit.
-
Click on the SERVICES main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of SERVICES.
-
Select Listener.
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:
-
Click the New button to create a Listener configuration.
At least one listener must always be configured in the Proxedo API Security configuration.
The following values can be configured for the Listener Service:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Free text. Alphanumeric, may contain underscores, may not start with a number. |
The name identifying the listener. This name of the listener can be referenced from other parts of the configuration. |
|
Port |
Any port value can be defined. Note that the port value has to be within the range configured in the docker. |
49000 |
The number of the port the listener binds to. |
Endpoints* |
A list of references to Endpoint Services. |
The list of endpoint(s), as defined under Endpoint that serve traffic coming in on the listener. |
|
Use TLS |
True or False. |
False |
Enables using TLS in the connection towards the clients. |
Client TLS* |
Reference to a File Brick of type Client TLS. |
The TLS configuration towards the clients. See TLS for details. Mandatory if Use TLS is set to True. |
Also consider the followings:
All endpoints in the list must have the same backend and backend URL configured. |
Ports must be unique, only one listener can bind to a specific port. It is however perfectly valid to route incoming traffic from multiple listeners to the same endpoint. |
-
Name the Listener Service.
-
Select the Client TLS parameter from the drop-down list. The client side TLS parameter values have to be defined previously under BRICKS.
-
Select the Endpoint from the drop-down list. The endpoint values have to be defined previously under SERVICES/Endpoint.
-
Fill in the Port information. If it is not configured, the default value will be applied.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
6.6.4. Log
If at any point an error occurs during the Security Flow, the error policy is applied and logging takes place if configured so.
6.6.4.1. Configuring Logs
Logging can be configured under the SERVICES main navigation item.
-
Click on the SERVICES main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of SERVICES.
-
Select Log.
The following values can be configured for the Log Service:
Increasing the verbosity hugely increases the amount of logs generated, and will reduce performance. |
The logs at the highest level of verbosity (9) might include sensitive information, such as passwords. |
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Log has a default name 'default', that cannot be changed. |
The name identifying the log configuration. |
|
Verbosity |
The value can take number format. |
3 |
The verbosity of logging. It must be between 1-9. |
Message Filter Expression |
A single message filter expression consists of a wildcard matching log category, a colon, and a number specifying the verbosity level of that given category. Categories match from left to right. For example: |
*.accounting:4,core.summary:4 |
Set verbosity mask on a per category basis. Each log message has an assigned multi-level category, where levels are separated by a dot. |
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
6.6.5. Transport Director
The 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
6.6.5.1. Configuring the Transport Director
The Transport Director can be configured under the SERVICES main navigation item.
-
Click on the SERVICES main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of SERVICES.
-
Select Transport Director.
The following values can be configured for the Transport Director Service:
Changes in these settings do not take effect during configuration application. For these changes to take effect, restarting the {pas_systemd_service_core} service is necessary.
|
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Transport Director has a default name 'default', that cannot be changed. |
The name identifying the Transport Director configuration. This name of the Transport Director can be referenced from other parts of the configuration. |
|
Enable Core Dump |
True or False. |
False |
Enables core dumps on failures. |
Threads |
0 |
Set the maximum number of threads that can be used in parallel. Note, that setting the value to zero means that the number of threads that can be used in parallel is unlimited. |
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button, when all required configuration fields have been defined.
6.6.6. Fraud Detector
The Fraud Detector, leveraging the data collected by the Fraud Detector plugin, establishes the actual connection with the Fraud API for an evaluation on the data of the calls.
Although the average response time of the Fraud API is half second, depending on the size and the complexity of the traffic to be investigated the response time might increase up to three seconds. Consequently, it is recommended to carefully identify the content selected for detection.
It is also recommended to consider that the API evaluates the maximum of 10 requests per second, therefore it is important to carefully define the matcher for the fraud detection, so that the load of requests is not unnecessarily high and the requests exceeding the value of 10 requests per second do not get dropped.
There are three recommended data types to be configured as selectors when configuring the Fraud Detector plugin, namely the IP address, the phone number and the e-mail address. For more details on how to configure Fraud Detector plugin, see Fraud Detector Plugin’s configuration options.
6.6.6.1. Configuring the Fraud Detector
The Fraud Detector can be configured under the SERVICES navigation unit.
-
Click on the SERVICES main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of SERVICES.
-
Select Fraud Detector.
The following values can be configured for the Fraud Detector Service:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
Fraud Detector has a default name 'default', that cannot be changed. |
default |
The name identifying the Fraud Detector. This name of the Fraud Detector can be referenced from other parts of the configuration. |
Active |
True or False. |
False |
If the license for the Fraud Detector is purchased, the service can be activated. |
Continue with the steps if the Fraud Detector is required in active state:
-
Set the Fraud Detector service to active state. The Fraud Detector is set to 'inactive' state by default, as for the 'active' state license is required.
If the Fraud Detector service is set to active, the following further parameters are available:
Key | Values | Default value | Description |
---|---|---|---|
Client Configuration |
Configure the parameters of Fraud Detector. |
||
API Endpoint |
The default value is as follows: https://fraud-api.balasys.hu/api. |
The API endpoint. |
|
API Key* |
The value for the API Key is provided by the purchase of the Fraud Detector license. |
The API key is provided when the license for the Fraud Detector is purchased. |
|
Connection Timeout |
The value can be provided in seconds. |
5 |
The time limit for establishing connection with the provided URL. |
Response Timeout |
The value can be provided in seconds. |
10 |
The time limit for how long the PAS awaits the answer from the Fraud API after an established connection. |
-
Define the API Endpoint destination.
-
Fill in the API key. The API Key is provided together with the license purchased for the Fraud Detector.
-
Add the value for the Connection Timeout parameter. The value has to be provided in seconds.
-
Provide the value for the Response Timeout parameter. The value has to be provided in seconds.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button.
6.6.7. WAF Ruleset Updater
The Web Application Firewall (WAF) Ruleset Updater Service is designed to automatically update the ruleset used for WAF enforcers, it is thereby critical in ensuring real-time protection against zero-day attacks by maintaining an up-to-date defense mechanism.
To activate this service, extra credentials will be necessary which can be obtained from the Balasys sales team.
6.6.7.1. Configuring the WAF Ruleset Updater
The WAF Ruleset Updater can be configured under the SERVICES navigation unit.
-
Click on the SERVICES main configuration item in the Left navigation area. Alternatively you can also click on the
sign to open up the sub-navigation items of SERVICES.
-
Select WAF Ruleset Updater.
The following values can be configured for the WAF Ruleset Updater Service:
Key | Values | Default value | Description |
---|---|---|---|
Name* |
WAF Ruleset Updater has a default name 'default', that cannot be changed. |
default |
It is the name identifying the WAF Ruleset Updater. This name of the WAF Ruleset Updater can be referenced from other parts of the configuration. |
Active |
True or False. |
False |
The service needs to be activated only if a WAF Enforcer is to be used. |
Continue with the steps if the WAF Ruleset Updater is required in active state:
-
Set the WAF Ruleset Updater service to active state. To activate the WAF Ruleset Updater a license is required. To acquire a license, contact our sales team at the e-mail address <sales@balasys.hu>.
If the WAF Ruleset Updater service is set to active, the following further parameters are available:
Key | Values | Default value | Description |
---|---|---|---|
Updater Configuration |
Configure the parameters of WAF Ruleset Updater. |
||
API Username* |
The username required to download and update the WAF enforcer’s ruleset. The value for the API Username is provided with the purchase of the WAF license. |
The API Username is provided when the license for the WAF API is purchased. |
|
API Password* |
The password required to download and update the WAF enforcer’s ruleset. The value for the API Password is provided with the purchase of the WAF license. |
The API Password is provided when the license for the WAF API is purchased. |
|
Poll Interval Seconds |
The value must be provided in seconds. |
3600 |
The time between two ruleset updates. |
Connection Timeout Seconds |
The value must be provided in seconds. |
5 |
The time limit for how long the PAS awaits the answer from the WAF API to establish the connection. |
Response Timeout Seconds |
The value must be provided in seconds. |
10 |
The time limit for how long the PAS awaits the answer from the WAF API after an established connection. |
-
Fill in the API Username. The API Username is provided together with the license purchased for the WAF API.
-
Fill in the API Password. The API Password is provided together with the license purchased for the WAF API.
-
Add the value for the Poll Interval Seconds parameter. The value has to be provided in seconds.
-
Add the value for the Connection Timeout Seconds parameter. The value has to be provided in seconds.
-
Provide the value for the Response Timeout Seconds parameter. The value has to be provided in seconds.
-
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
-
Click the Save button.
6.7. Checking and finalizing changes in Proxedo API Security configuration
It is possible to list and check any changes made to the PAS configuration until the changes have not been applied with the Apply Configuration button.
Click on the Changes button in the Top-left navigation area to list the changes made to the configuration.
The following pieces of information are displayed:
-
configuration integrity problems
-
changes made to any of the configuration components
6.7.1. Configuration Integrity
For changes on configuration integrity, the following pieces of information are displayed in table format:
-
Type: It denotes the type of the integrity problem, for example cycle detection.
-
Description: Description provides details on the nature of the integrity change.
-
Recommended action: A recommended action might be displayed here for the configuration integrity problem.
Until the configuration integrity errors listed here are not corrected, the configuration cannot be applied. |
For details on configuration integrity errors, see the examples in section Integrity errors.
6.7.2. Configuration Changes
For changes on the configuration components, the following pieces of information are displayed in table format:
-
Type: Type denotes the category (Brick, Plugin, Service) and the class (for example, Matcher, Filter, Log) of the configuration component, for example Brick/Matcher.
-
Name: The name of the configuration component is displayed here, to which the actual change has been made.
-
Change: The nature of the change made to the configuration component is provided here, that is, added, edited, deleted or no (no change).
-
Validity: This field informs the user on whether the configured component is valid or not, as follows:
-
- Any instance marked with this sign is invalid.
-
- Any instance marked with this sign is valid.
-
Click on the |
Invalid configuration components can be corrected and revalidated by using the Validate button, available at each component’s configuration page. For more information, see section Component-level validation in chapter Applying and validating Proxedo API Security configuration.
-
Actions: This field provides possibility to edit the configuration data for a component or to undo any configuration changes to a component. By selecting the undo icon, all changes made to the actual component will be deleted.
If the edit button is disabled, that is, it is not active, it means that the instance has been deleted. If the undo button is disabled, that is, it is not active, no changes have been made to the actual component. |
By selecting the Discard button, it is possible to discard all changes made to the configuration. However, the default elements that are created by the system to ease configuration, or the changes that have been applied to the configuration already cannot be discarded.
6.8. Applying and validating Proxedo API Security configuration
PAS configuration can be checked and validated on two levels:
-
component-level validation
-
validating the whole configuration
6.8.1. Component-level validation
Component-level validation takes place while configuring the actual elements of the configuration and by using the Validate button on the Web UI page of the specific component.
If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the Component validation failed. Also a warning with information on the missing details appears at the problematic field for the user.
If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the Component Validation successful notification. Click OK. For related errors see, section Validation errors.
6.8.2. Validating the whole configuration
Configuration integrity errors can be viewed on the Changes page, along with a summary of valid and invalid component changes. To make it available click the Changes button so that all the changes made to any component by the user will be visible. For related errors, see section Validation errors.
6.8.3. Applying the whole configuration
The Apply Configuration button is available from the Changes page. To make it available click the Changes button so that all the changes made to any component by the user will be visible. In order to take the changes into effect, click the Apply Configuration button. The configuration can only be applied if all changes are valid. When applying the configuration by using the Apply Configuration button, the Web UI provides either of the following messages:
-
The configuration is applied successfully. Click OK.
-
The configuration failed.
If applying the configuration failed, the Web UI also provides an additional pop-up window with the description of the problem. The problems can be as follows:-
At least one of the services failed to start, the previous configuration settings have been restored.
-
Restoring the original configuration was not successful.
-
During the process of applying the configuration, no changes can be completed to the configuration. The process however shall not take more than 10 seconds. |
6.8.4. Validation errors
In case the configuration could not be applied, the following result messages help the user to correct the configuration and achieve a valid configuration.
6.8.4.1. Component-related errors
These errors are the results of the validation of the actual components. By correcting these the user can achieve a functioning configuration.
6.8.4.1.1. Missing data for required fields
Each component has compulsory configuration fields that must be filled in. In case any of those fields are left empty, the Web UI provides a Missing data for required field notification when the component is validated, that is, the Validate button is used. Each compulsory field is highlighted with a * sign.
Example
The Insight Target component requires the Host field to be filled in, otherwise the component’s configuration is not valid.
Error message: Missing data for required field.
6.8.4.1.2. Missing reference
This error indicates that the component references a non-existing component.
Example
The user creates an error policy, Error Policy A which error policy is referenced in a Filter. Following that, this specific error policy, Error Policy A is deleted from the configuration. This results in a missing reference in the Filter.
Error message: Reference to a non-existing component: Error Policy A.
To correct the missing reference, navigate to the Filter component. In order to clear the invalid reference to the missing component, the |
6.8.4.2. Integrity errors
6.8.4.2.1. Cycle detection
This error indicates that there is a cycle of references between the instances. The cycle of references can only be configured in between compound matchers.
Example
If the compound matcher Matcher A is configured to reference the compound matcher Matcher B and the compound matcher Matcher B is also referencing the compound matcher Matcher A, there will be a cycle of references between these two compound matchers.
Error message: Cycle detected in configuration: BRICK/Matcher/Matcher A→BRICK/Matcher/Matcher B→BRICK/Matcher/Matcher A.
6.8.4.2.2. Required Instance is missing
This error indicates that a required instance is not configured. It is required that at least one Listener service must be configured.
Error message: At least one service/listener must be configured.
6.8.4.2.3. Fraud Detector Plugin configured with the Fraud Detector in inactive state
The following integrity error is indicated:
This error indicates that there is a Fraud Detector Endpoint configured, however, the Fraud Detector service is not activated. In order to solve this integrity error, either the Fraud Detector Endpoint has to be removed from the configuration, or, in case the license for the Fraud Detector is purchased, the Fraud Detector service has to be activated and configured.
6.9. Backup and restore running or user configuration for Proxedo API Security
It is possible to backup and restore the Proxedo API Security configuration in the Web UI.
In order to export any configuration information from the system, complete the following steps:
-
Select the Configuration Backup button.
-
To export a configuration, select the type of the configuration to be exported at the Export configuration button. The following options can be selected from the drop-down menu:
-
Running: This export option downloads the configuration settings of the currently running configuration.
-
User: This export option downloads the default configuration settings of the system.
-
The configuration will be downloaded in .zip file format.
-
To import an existing configuration file, select the empty field beside Import configuration. Only .zip file formats can be uploaded.
-
Select the Download or the Upload buttons to finish the activity. The system will ask you to define the Insight Target or source destination for the activity. Note that only files in .zip format can be downloaded or uploaded.
In case of importing a configuration file, the system will notify the user that by importing a configuration file, the existing configuration will be overwritten: 'This operation overwrites user configuration. Are You sure?' |
7. Operation of Proxedo API Security in Kubernetes environment
This section introduces different methods of inspecting a PAS service state. For inspecting a PAS service state, it is recommended to use selectors, as selectors utilize all the three labels that are added to most objects of the PAS installation.
The three labels are as follows:
-
app: This label is present on each object with the value of proxedo-api-security.
-
component: This label is present on all objects that can be associated with any of the three main components of PAS, such as :
-
mgmt for the management object
-
core for the core objects
-
storage for the storage objects
-
-
subcomponent: This label is attached to all objects that are directly and exclusively associated with one subcomponent (services, deployments, pods, network policies, etc.).
The value of this label is always the name of the subcomponent, for example, flow-director, blob-store, config-api, etc. Since objects are named, using the proxedo-api-security-<subcomponent-name> convention, using the proxedo-api-security-flow-director object name is most often equivalent to using the subcomponent=flow-director selector. Using the selector can be more advantageous, especially with pods, if there are multiple running instances. Since pod names are suffixed with dynamically changing hashes, using a specific pod name can be both inconvenient and sometimes too narrow.
These labels are useful for semantically narrowing down the focus of queries about kubernetes objects.
7.1. Querying objects
By using the kubectl get
command, objects can be queried with basic information about them.
Run the kubectl get pods --namespace=proxedo-api-security --selector=app=proxedo-api-security
command to get the list of pods related to PAS.
The output will be similar to the following example:
NAME READY STATUS RESTARTS AGE
proxedo-api-security-blob-store-768f54bddd-fpd2v 1/1 Running 0 20m
proxedo-api-security-config-api-5b8b845744-htswp 1/1 Running 0 20m
proxedo-api-security-consul-65f4c78f-26bsg 1/1 Running 0 20m
proxedo-api-security-content-filtering-director-55b859df9-sztwp 1/1 Running 0 20m
proxedo-api-security-flow-director-7459896d6c-k9ttm 0/1 ContainerCreating 0 20m
proxedo-api-security-frontend-84798447c4-svrvj 1/1 Running 0 20m
proxedo-api-security-insight-director-5756f4f4b4-jw4vv 0/1 ContainerCreating 0 20m
proxedo-api-security-transport-director-7d4f7fbdf-sh9kw 0/1 ContainerCreating 0 20m
In this example, the core components do not have configuration, as that is to be set on the Web UI, and for this reason they are not in Running state in the example.
To get PAS services, network policies, and so on, the relevant part of the command referring to 'pods' needs to be changed to the object type in question.
7.2. Inspecting objects
To get more detailed information about any specific kubernetes object, use the kubectl describe
command. Selectors can also be used with this command, however it is recommended to use this command with a specific object name.
Based on the previous example where core pods were not in Running state, the kubectl kubectl --namespace=proxedo-api-security describe pod proxedo-api-security-flow-director-7459896d6c-k9ttm
command can be used to find out the reason behind its malfunction.
The output will be similar to the following example:
Name: proxedo-api-security-flow-director-7459896d6c-k9ttm
Namespace: mate
Priority: 0
Node: api-kube-node-2/10.90.31.63
Start Time: Mon, 04 Jul 2022 10:40:56 +0200
Labels: app=proxedo-api-security
component=core
pod-template-hash=7459896d6c
subcomponent=flow-director
Annotations: <none>
Status: Pending
IP:
IPs: <none>
Controlled By: ReplicaSet/proxedo-api-security-flow-director-7459896d6c
Containers:
flow-director:
Container ID:
Image: docker.balasys.hu/api-security/flow-director:4.9.0
Image ID:
Ports: 1318/TCP, 8080/TCP
Host Ports: 0/TCP, 0/TCP
State: Waiting
Reason: ContainerCreating
Ready: False
Restart Count: 0
Requests:
cpu: 250m
memory: 600Mi
Readiness: http-get http://:8000/health delay=5s timeout=1s period=10s #success=1 #failure=1
Environment:
INSIGHT_DIRECTOR_HOSTNAME: proxedo-api-security-insight-director
SERVICE_ADAPTOR_PORT: 8000
Mounts:
/opt/balasys/etc/pas from license (ro)
/opt/balasys/etc/pas/k8s/configmap from config-configmap (ro)
/opt/balasys/etc/pas/k8s/secret from config-secret (ro)
/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-qbnnv (ro)
Conditions:
Type Status
Initialized True
Ready False
ContainersReady False
PodScheduled True
Volumes:
license:
Type: Secret (a volume populated by a Secret)
SecretName: proxedo-api-security-license
Optional: false
config-configmap:
Type: ConfigMap (a volume populated by a ConfigMap)
Name: proxedo-api-security-core-config
Optional: false
config-secret:
Type: Secret (a volume populated by a Secret)
SecretName: proxedo-api-security-core-config
Optional: false
kube-api-access-qbnnv:
Type: Projected (a volume that contains injected data from multiple sources)
TokenExpirationSeconds: 3607
ConfigMapName: kube-root-ca.crt
ConfigMapOptional: <nil>
DownwardAPI: true
QoS Class: Burstable
Node-Selectors: <none>
Tolerations: node.kubernetes.io/not-ready:NoExecute op=Exists for 300s
node.kubernetes.io/unreachable:NoExecute op=Exists for 300s
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 37m default-scheduler Successfully assigned mate/proxedo-api-security-flow-director-7459896d6c-k9ttm to api-kube-node-2
Warning FailedMount 33m kubelet Unable to attach or mount volumes: unmounted volumes=[config-configmap config-secret], unattached volumes=[config-configmap config-secret kube-api-access-qbnnv license]: timed out waiting for the condition
Warning FailedMount 31m (x11 over 37m) kubelet MountVolume.SetUp failed for volume "config-secret" : secret "proxedo-api-security-core-config" not found
Warning FailedMount 17m (x5 over 31m) kubelet Unable to attach or mount volumes: unmounted volumes=[config-configmap config-secret], unattached volumes=[license config-configmap config-secret kube-api-access-qbnnv]: timed out waiting for the condition
Warning FailedMount 7m7s (x23 over 37m) kubelet MountVolume.SetUp failed for volume "config-configmap" : configmap "proxedo-api-security-core-config" not found
Warning FailedMount 106s (x4 over 35m) kubelet Unable to attach or mount volumes: unmounted volumes=[config-secret config-configmap], unattached volumes=[config-secret kube-api-access-qbnnv license config-configmap]: timed out waiting for the condition
In this example, the Events section of the output shows (among other details) that two necessary configuration objects do not exist, and therefore the pods cannot be started. It also describes the volumes, ports, environment variables and many more attributes that can be helpful for finding out the reason behind its malfunction.
7.3. Checking logs
Logs of PAS components are by default available through the kubectl logs
command. An extract of the output of kubectl logs --namespace=proxedo-api-security pods/proxedo-api-security-frontend-84798447c4-svrvj
command is displayed in the following example:
2022-07-04T09:36:50 config-webui 192.168.235.192 - - [04/Jul/2022:09:36:50 +0000] "POST /api/v1/auth/login HTTP/1.1" 200 1005 "http://api-kube-node-3.dev.balasys:30001/login" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36"
2022-07-04T09:36:50 config-webui 192.168.235.192 - - [04/Jul/2022:09:36:50 +0000] "GET /api/v1/ui-adaptor/menu HTTP/1.1" 200 1942 "http://api-kube-node-3.dev.balasys:30001/login" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36"
2022-07-04T09:36:50 config-webui 192.168.235.192 - - [04/Jul/2022:09:36:50 +0000] "GET /assets/outline/appstore.svg HTTP/1.1" 200 574 "http://api-kube-node-3.dev.balasys:30001/" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36"
2022-07-04T09:36:50 config-webui 192.168.235.192 - - [04/Jul/2022:09:36:50 +0000] "GET /assets/outline/api.svg HTTP/1.1" 200 1134 "http://api-kube-node-3.dev.balasys:30001/" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36"
2022-07-04T09:36:50 config-webui 192.168.235.192 - - [04/Jul/2022:09:36:50 +0000] "GET /assets/images/proxedo_API_transparent.svg HTTP/1.1" 200 3975 "http://api-kube-node-3.dev.balasys:30001/changes" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36"
2022-07-04T09:36:50 config-webui 192.168.235.192 - - [04/Jul/2022:09:36:50 +0000] "GET /assets/outline/setting.svg HTTP/1.1" 200 1873 "http://api-kube-node-3.dev.balasys:30001/" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36"
2022-07-04T09:36:50 config-webui 192.168.235.192 - - [04/Jul/2022:09:36:50 +0000] "GET /SourceSansPro-SemiBold.43cc81b496222dc9ce3c.ttf HTTP/1.1" 200 268280 "http://api-kube-node-3.dev.balasys:30001/styles.e68c8c26486c2eba6127.css" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36"
2022-07-04T09:36:51 config-webui 192.168.235.192 - - [04/Jul/2022:09:36:51 +0000] "GET /api/v1/ui-adaptor/config/changes HTTP/1.1" 200 1969 "http://api-kube-node-3.dev.balasys:30001/changes" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36"
2022-07-04T09:36:51 config-webui 192.168.235.192 - - [04/Jul/2022:09:36:51 +0000] "GET /assets/outline/rollback.svg HTTP/1.1" 200 265 "http://api-kube-node-3.dev.balasys:30001/changes" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.53 Safari/537.36"
The kubectl logs
command can also be used with Selectors and other object types like deployments or services. In this case, its scope is wider and can sometimes be more adequate.
7.3.1. Understanding logs
As multiple pieces of software run in each container, there are two layers of logs in each containers' output.
The first field is always an ISO formatted date. Then the name of the process inside the container follows. The remaining fields are the output of the process itself.
In the below example, we see logs from the flow-director
container. It prints output for processes called pre
, pas-event-handler
, flow-director
and service-adaptor
.
2021-04-20T09:15:30 pre Container starts 2021-04-20T09:15:33 pre INFO:confgen: Generating configuration files 2021-04-20T09:15:34 pas-event-handler INFO:SupervisordEventDispatcher:Dispatching event; processname='pre', eventname='PROCESS 2021-04-20T09:15:34 pas-event-handler INFO:SupervisordEventDispatcher:Process exited; processname=pre, success=True 2021-04-20T09:15:34 pas-event-handler INFO:SupervisordEventDispatcher:Starting main processes. 2021-04-20T09:15:34 pas-event-handler INFO:SupervisordEventDispatcher:Starting process; process='flow-director' [...] 2021-04-20T09:15:37 flow-director 2021-04-20T09:15:37+0200: flow_builder.info(3) (nosession): Loaded plugin; [...] 2021-04-20T09:15:37 flow-director 2021-04-20T09:15:37+0200: flow_builder.info(3) (nosession): Loaded plugin; [...] 2021-04-20T09:15:37 flow-director 2021-04-20T09:15:37+0200: flow_builder.info(3) (nosession): Loaded plugin; [...] 2021-04-20T09:15:37 flow-director 2021-04-20T09:15:37+0200: flow_builder.info(3) (nosession): Loaded plugin; [...] 2021-04-20T09:15:37 flow-director 2021-04-20T09:15:37+0200: flow_builder.info(3) (nosession): Loaded plugin; [...] 2021-04-20T09:15:37 flow-director 2021-04-20T09:15:37+0200: flow_builder.info(3) (nosession): Loaded plugin; [...] 2021-04-20T09:15:37 flow-director 2021-04-20T09:15:37+0200: flow_builder.info(3) (nosession): Loaded plugin; [...] 2021-04-20T09:15:37 flow-director 2021-04-20T09:15:37+0200: flow_set.info(3) (nosession): Start building flows [...] 2021-04-20T09:15:39 pas-event-handler INFO:SupervisordEventDispatcher:Starting process; process='service-adaptor' [...] 2021-05-07T14:23:55 service-adaptor INFO:PASHealthCheck:All services are healthy. 2021-05-07T14:23:55 service-adaptor [pid: 47|app: 0|req: 223/223] 172.19.0.3 () {28 vars in 350 bytes} [Fri May 7 14:23:55 2021] [...]
7.3.1.1. Flow Director and Transport Director logs
As from the API security perspective, the most important components are Flow Director and Transport Director, we discuss their logs more in detail. There are two important concepts related to these logs: categories and Session IDs.
-
Categories help filtering logs based on their relevance. They are composed of a component, a tag, and a severity, for example: http.info(3).
-
The component helps to identify the part of the solution. For the Transport Director this is usually core or http, for the Flow Director it is either core, or the Plugin’s type, such as serializer or enforcer.
-
The tag helps to define the type of the message. Usually one of info, error, debug, policy or accounting.
-
The severity defines how important the message is. It is a number between 1-9 where 1 is the highest.
-
-
Session ID helps identifying log lines that belong to the same session. This is especially important as the calls travel between the Transport Director and the Flow Director.
It is usually in the form of svc/default/<listener>:<transport-director-session>/default/http#<http-request-count>/flow:<flow-director-id>/ch:<flow-director-channel>/<endpoint_name>/<plugin_type>/<plugin_name>, for example: svc/default/httpbin:14/default/http#0/flow:1/ch:28/endpoint_test/enforcer/manualtest.
Information that is not available at the time, will be missing from the Session ID. Generally, the part until /flow: belongs to the Transport Director. Consequently, the Transport Director will never see that part. The Flow Director however will fetch and include that information. Nevertheless, in early phases it might not be available, and the Session ID will start with flow.
Despite some parts not being always available, the ID is constructed in such a manner that grepping on any part will find other messages with extra information as well.
7.4. Troubleshooting containers
7.4.1. Inspecting files
For inspecting file content inside PAS containers, it is recommended to log into a specific container and use the shell for navigating in the file system and the available tools for reading them.
kubectl --namespace proxedo-api-security exec --stdin --tty pods/proxedo-api-security-config-api-579b59fc8d-59hqh -- /bin/bash
root@proxedo-api-security-config-api-579b59fc8d-59hqh:/# ls -1 /opt/balasys/etc/mgmt/
config.yml
users.htpass
7.4.2. Inspecting processes and network
Processes and network can best be troubleshot using the kubectl debug
tool and the PAS debug image. This image holds basic process and network debugging tools and enables installing new ones.
kubectl --namespace proxedo-api-security debug --stdin --tty --image=docker.balasys.hu/api-security/container-debugger:4.9.0 pods/proxedo-api-security-config-api-579b59fc8d-59hqh -- tcpdump -i any
Defaulting debug container name to debugger-wcrnx.
If you don't see a command prompt, try pressing enter.
[...]
7.5. Changing bootstrap configuration
Since bootstrap configuration is provided during Helm installation, the parameters used there can be changed in the provided files. Moreover, all the input files may be changed. As soon as the changes are made, they can be made effective by running the installation command, as displayed in Providing the necessary files for Helm installation.
7.6. Backup and restore
7.6.1. Bootstrap configuration
As the whole bootstrap configuration is provided at the time of installation, the directory, in which the installation was carried out, needs to be saved, so that the installation procedure can be repeated.
7.6.2. Running configuration
To completely backup the running configuration, the storage component’s Persistent Volume needs to be backed up. This can be done by directly backing up the Persistent Volume that is assigned to the proxedo-api-security-storage
Persistent Volume Claim.
This solution is specific to the Kubernetes Cluster and therefore it is the responsibility of the cluster administrator. In this case, the cluster administrator also needs to make sure that the restored Persistent Volume gets assigned to the new Persistent Volume Claim from the new PAS installation.
Another method for creating a backup of the running configuration is to use the backup mechanism available on the Web UI, see Backup and restore running or user configuration for Proxedo API Security.
7.7. Factory reset
In case a factory reset is necessary, the simplest solution is to delete the namespace, PAS is installed in. If that is not feasible, an alternative is to explicitly delete Kubernetes objects related to PAS. To do so, two main steps are required:
-
Uninstall the PAS Helm chart using the
helm uninstall --namespace=proxedo-api-security proxedo-api-security
command. This will remove all kubernetes objects managed by the Helm charts, including the Persistent Volume Claim associated with the storage components.
-
Delete the core configuration objects. These objects are not managed by the Helm chart but by the management component. To complete this, run the following commands:
-
kubectl --namespace=proxedo-api-security delete configmap proxedo-api-security-core-config
-
kubectl --namespace=proxedo-api-security delete secrets proxedo-api-security-core-config proxedo-api-security-registry-credentials
-
Following these steps, PAS shall be installed from scratch. For more details, see Installation of Proxedo API Security in Kubernetes environment.
Appendix A: Selector configuration for the Fraud Detector Plugin
The following fields can be defined in the Save as field when creating a new Selector. The saved Selector can be used by the Fraud Detector plugin.
The data type selected in the API for the actual selector option shall be the one listed in this table as Type for the actual selector. Currently, no data type conversion is possible for selectors. |
Values for Save as field | Data type | Description | Example |
---|---|---|---|
action_type |
string |
The type of the user action being scored. Any string can be valid. |
|
client_address |
string |
The user’s IP address at the time of the transaction. It shall include the full IPv4 or IPv6 address. |
|
transaction_id |
string |
A unique identifier for the transaction, as found in the system. If it is not specified, it is automatically generated. |
|
affiliate_id |
string |
The user’s unique affiliate identifier in the system. |
|
affiliate_name |
string |
The name of the affiliate for the registered user. Can be ASCII-encoded via a secure hash algorithm, such as MD5 or SHA-2. |
|
order_memo |
string |
The description of the transaction found in the system. |
|
string |
The full email address of the registered user. |
||
email_domain |
string |
The email address domain of the registered user. |
|
password_hash |
string |
The hash of the user’s password in ASCII encoding (we recommend using HMAC-SHA256 or RSA-SHA256). |
|
user_fullname |
string |
The user’s registered full name. Can be hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). |
|
user_name |
string |
The user’s registered username. Can be hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). |
|
user_id |
string |
The user’s unique identifier. If the request was sent without a user_id value, a unique ID is automatically generated based on the user_name and/or the email fields, based on which is available. If none of these identifiers were included in the request, the user ID is generated randomly. |
|
user_created |
integer |
The date when the user first registered to the protected service, using the UNIX time format and UTC time zone, without milliseconds. |
|
user_category |
string |
The user’s category. |
|
user_account_status |
string |
The user’s current account status. |
|
user_bank_account |
string |
The user’s bank account number for monetary transfer. |
IBAN number |
user_bank_name |
string |
The name of the user’s bank account. |
|
user_balance |
float |
The user’s current balance. |
|
user_verification_level |
string |
The user’s verification level. |
|
user_dob |
date |
The user’s date of birth in the format of YYYY-MM-DD. |
|
user_country |
string |
The country code for the user’s registered address. Uses the two-character ISO 3166-1 format. |
|
user_city |
string |
The complete name of the city associated with the user’s registered address. |
|
user_region |
string |
The state or region code for the user’s registered address. Uses the two-character ISO 3166-2 format. |
|
user_zip |
string |
The zip/postal code of the user’s registered address. |
|
user_street |
string |
The first line of the user’s registered street address. Can be hashed in ASCII encoding as well. |
MD5, SHA-2 family: |
user_street2 |
string |
The second line of the user’s registered street address. Can be hashed in ASCII encoding as well. |
MD5, SHA-2 family: |
session_id |
string |
The session ID is a custom, unique ID that links the user’s device data with the transactions. It shall be based on the user’s current browsing session, by tracking cookies for example. If JavaScript Agent v4 is used, the encrypted payload returned by the SDK (supported by JS Agent v4, iOS SDK 3.0.0, Android SDK 3.0.0) shall be sent in the session field, instead of the session_id. |
|
session |
string |
The base64 encoded session data returned by the SDKs. |
|
device_id |
string |
This field shall only be used if a device fingerprinting solution is used already. This is the ID that shall be linked to the transactions or in case rules are required to be built on those IDs. |
|
payment_mode |
string |
The method of payment used. |
|
payment_provider |
string |
The name of the payment service provider related to the transaction. |
|
card_fullname |
string |
The user’s full name found on the card. Can be hashed in ASCII encoding as well. |
MD5, SHA-2 family |
card_bin |
string |
The first 4, 6 or 8 digits of the card number. |
|
card_hash |
string |
The hash of the credit card used by the user in ASCII encoding. We recommend using HMAC-SHA256 or RSA-SHA256 formats and strictly advise not to use MD5 hash format. |
|
card_expire |
string |
The card’s expiration date. |
|
card_last |
string |
The last 4 digits of the card number. These help to identify the card. |
|
avs_result |
string |
The standard Address verification Service (AVS) codes sent by the credit card processor. |
|
cvv_result |
boolean |
The Cad Verification Value (CVV) result. |
|
status_3d |
string |
The Cad Verification Value (CVV) result. |
|
sca_method |
string |
The result of the Strong Customer Authentication method. |
|
phone_number |
string |
The user’s registered phone number, including the country code. Cannot include spaces or hyphens, the + sign is optional. The maximum length is 19 characters. |
|
transaction_type |
string |
The transaction type of the actual business. |
|
transaction_amount |
float |
The full transaction amount. As a decimal point use '.' (full stop). |
|
transaction_currency |
string |
The currency used by the user, in ISO 4217 format. Crypto currencies are also supported. |
|
shipping_country |
string |
A two-character ISO 3166-1 country code for the country associated with the user’s shipping address. |
|
shipping_city |
string |
The full name of the city associated with the user’s shipping address. |
|
shipping_region |
string |
The state or region code for the user’s shipping address. Uses the two-character ISO 3166-2 format |
|
shipping_zip |
string |
The zip/postal code of the user’s shipping address. |
|
shipping_street |
string |
The first line of the user’s shipping street address. Can be hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). |
|
shipping_street2 |
string |
The second line of the user’s shipping street address. Can be hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). |
|
shipping_phone |
string |
The phone number associated with the user’s shipping address, including the country code. Cannot include spaces or hyphens, the + sign is optional. The maximum length is 19 characters. |
|
shipping_fullname |
string |
The user’s registered full name. Can be hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). |
|
shipping_method |
string |
The type of the shipping method used by the customer. |
|
billing_country |
string |
The country code for the user’s billing address. Uses the two-character ISO 3166-1 format. |
|
billing_city |
string |
The full name of the city associated with the user’s billing address. |
|
billing_region |
string |
The state or region code for the user’s billing address. Uses the two-character ISO 3166-2 format |
|
billing_zip |
string |
The zip/postal code of the user’s billing address. |
|
billing_street |
string |
The user’s billing street address line 1. Can be hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). |
|
billing_street2 |
string |
The user’s billing street address line 2. Can be hashed in ASCII encoding as well (e.g. MD5, SHA-2 family). |
|
billing_phone |
string |
The phone number associated with the user’s billing address, including the country code. Cannot include spaces or hyphens, the + sign is optional. The maximum length is 19 characters. |
|
discount_code |
string |
The discount code that the user applied during the checkout. |
|
gift |
boolean |
The user can mark the order with true or false value, dependent on if it is a gift or not. |
|
gift_message |
boolean |
The user can mark the order with true or false value, dependent on if the order has a gift message or not. |
|
merchant_category |
string |
The category of the merchant. |
|
merchant_id |
string |
The unique merchant identifier in case the orders are from different merchants. |
|
merchant_created_at |
integer |
The date the merchant was created, using the UNIX time format and UTC time zone. |
|
merchant_country |
string |
The country code for the merchant’s address. Uses the two-character ISO 3166-1 format. |
|
receiver_fullname |
string |
The receiver’s full name for monetary transfer. |
IBAN number |
details_url |
string |
The URL of the transaction in the management platform. |
|
regulation |
string |
The license or market name for gambling operator. |
|
bonus_campaign_id |
string |
The bonus campaign’s unique identifier. |
|
brand_id |
string |
The brand’s unique identifier. |
|
The maximum length of all request parameters is 100 characters, except for the following: 500 characters for card_hash 64 characters for the session_id (sent directly or within the session field) 19 characters for the phone_number 15 characters for card_bin 4 characters for transaction_currency 50 characters for discount_code and shipping_method ** 255 characters for transaction_id |
Appendix B: Time zones
Country Code | Time zone Name |
---|---|
AD |
Europe/Andorra |
AE |
Asia/Dubai |
AF |
Asia/Kabul |
AG |
America/Antigua |
AI |
America/Anguilla |
AL |
Europe/Tirane |
AM |
Asia/Yerevan |
AO |
Africa/Luanda |
AQ |
Antarctica/McMurdo |
AQ |
Antarctica/Casey |
AQ |
Antarctica/Davis |
AQ |
Antarctica/DumontDUrville |
AQ |
Antarctica/Mawson |
AQ |
Antarctica/Palmer |
AQ |
Antarctica/Rothera |
AQ |
Antarctica/Syowa |
AQ |
Antarctica/Troll |
AQ |
Antarctica/Vostok |
AR |
America/Argentina/Buenos_Aires |
AR |
America/Argentina/Cordoba |
AR |
America/Argentina/Salta |
AR |
America/Argentina/Jujuy |
AR |
America/Argentina/Tucuman |
AR |
America/Argentina/Catamarca |
AR |
America/Argentina/La_Rioja |
AR |
America/Argentina/San_Juan |
AR |
America/Argentina/Mendoza |
AR |
America/Argentina/San_Luis |
AR |
America/Argentina/Rio_Gallegos |
AR |
America/Argentina/Ushuaia |
AS |
Pacific/Pago_Pago |
AT |
Europe/Vienna |
AU |
Australia/Lord_Howe |
AU |
Antarctica/Macquarie |
AU |
Australia/Hobart |
AU |
Australia/Currie |
AU |
Australia/Melbourne |
AU |
Australia/Sydney |
AU |
Australia/Broken_Hill |
AU |
Australia/Brisbane |
AU |
Australia/Lindeman |
AU |
Australia/Adelaide |
AU |
Australia/Darwin |
AU |
Australia/Perth |
AU |
Australia/Eucla |
AW |
America/Aruba |
AX |
Europe/Mariehamn |
AZ |
Asia/Baku |
BA |
Europe/Sarajevo |
BB |
America/Barbados |
BD |
Asia/Dhaka |
BE |
Europe/Brussels |
BF |
Africa/Ouagadougou |
BG |
Europe/Sofia |
BH |
Asia/Bahrain |
BI |
Africa/Bujumbura |
BJ |
Africa/Porto-Novo |
BL |
America/St_Barthelemy |
BM |
Atlantic/Bermuda |
BN |
Asia/Brunei |
BO |
America/La_Paz |
BQ |
America/Kralendijk |
BR |
America/Noronha |
BR |
America/Belem |
BR |
America/Fortaleza |
BR |
America/Recife |
BR |
America/Araguaina |
BR |
America/Maceio |
BR |
America/Bahia |
BR |
America/Sao_Paulo |
BR |
America/Campo_Grande |
BR |
America/Cuiaba |
BR |
America/Santarem |
BR |
America/Porto_Velho |
BR |
America/Boa_Vista |
BR |
America/Manaus |
BR |
America/Eirunepe |
BR |
America/Rio_Branco |
BS |
America/Nassau |
BT |
Asia/Thimphu |
BW |
Africa/Gaborone |
BY |
Europe/Minsk |
BZ |
America/Belize |
CA |
America/St_Johns |
CA |
America/Halifax |
CA |
America/Glace_Bay |
CA |
America/Moncton |
CA |
America/Goose_Bay |
CA |
America/Blanc-Sablon |
CA |
America/Toronto |
CA |
America/Nipigon |
CA |
America/Thunder_Bay |
CA |
America/Iqaluit |
CA |
America/Pangnirtung |
CA |
America/Atikokan |
CA |
America/Winnipeg |
CA |
America/Rainy_River |
CA |
America/Resolute |
CA |
America/Rankin_Inlet |
CA |
America/Regina |
CA |
America/Swift_Current |
CA |
America/Edmonton |
CA |
America/Cambridge_Bay |
CA |
America/Yellowknife |
CA |
America/Inuvik |
CA |
America/Creston |
CA |
America/Dawson_Creek |
CA |
America/Fort_Nelson |
CA |
America/Vancouver |
CA |
America/Whitehorse |
CA |
America/Dawson |
CC |
Indian/Cocos |
CD |
Africa/Kinshasa |
CD |
Africa/Lubumbashi |
CF |
Africa/Bangui |
CG |
Africa/Brazzaville |
CH |
Europe/Zurich |
CI |
Africa/Abidjan |
CK |
Pacific/Rarotonga |
CL |
America/Santiago |
CL |
America/Punta_Arenas |
CL |
Pacific/Easter |
CM |
Africa/Douala |
CN |
Asia/Shanghai |
CN |
Asia/Urumqi |
CO |
America/Bogota |
CR |
America/Costa_Rica |
CU |
America/Havana |
CV |
Atlantic/Cape_Verde |
CW |
America/Curacao |
CX |
Indian/Christmas |
CY |
Asia/Nicosia |
CY |
Asia/Famagusta |
CZ |
Europe/Prague |
DE |
Europe/Berlin |
DE |
Europe/Busingen |
DJ |
Africa/Djibouti |
DK |
Europe/Copenhagen |
DM |
America/Dominica |
DO |
America/Santo_Domingo |
DZ |
Africa/Algiers |
EC |
America/Guayaquil |
EC |
Pacific/Galapagos |
EE |
Europe/Tallinn |
EG |
Africa/Cairo |
EH |
Africa/El_Aaiun |
ER |
Africa/Asmara |
ES |
Europe/Madrid |
ES |
Africa/Ceuta |
ES |
Atlantic/Canary |
ET |
Africa/Addis_Ababa |
FI |
Europe/Helsinki |
FJ |
Pacific/Fiji |
FK |
Atlantic/Stanley |
FM |
Pacific/Chuuk |
FM |
Pacific/Pohnpei |
FM |
Pacific/Kosrae |
FO |
Atlantic/Faroe |
FR |
Europe/Paris |
GA |
Africa/Libreville |
GB |
Europe/London |
GD |
America/Grenada |
GE |
Asia/Tbilisi |
GF |
America/Cayenne |
GG |
Europe/Guernsey |
GH |
Africa/Accra |
GI |
Europe/Gibraltar |
GL |
America/Godthab |
GL |
America/Danmarkshavn |
GL |
America/Scoresbysund |
GL |
America/Thule |
GM |
Africa/Banjul |
GN |
Africa/Conakry |
GP |
America/Guadeloupe |
GQ |
Africa/Malabo |
GR |
Europe/Athens |
GS |
Atlantic/South_Georgia |
GT |
America/Guatemala |
GU |
Pacific/Guam |
GW |
Africa/Bissau |
GY |
America/Guyana |
HK |
Asia/Hong_Kong |
HN |
America/Tegucigalpa |
HR |
Europe/Zagreb |
HT |
America/Port-au-Prince |
HU |
Europe/Budapest |
ID |
Asia/Jakarta |
ID |
Asia/Pontianak |
ID |
Asia/Makassar |
ID |
Asia/Jayapura |
IE |
Europe/Dublin |
IL |
Asia/Jerusalem |
IM |
Europe/Isle_of_Man |
IN |
Asia/Kolkata |
IO |
Indian/Chagos |
IQ |
Asia/Baghdad |
IR |
Asia/Tehran |
IS |
Atlantic/Reykjavik |
IT |
Europe/Rome |
JE |
Europe/Jersey |
JM |
America/Jamaica |
JO |
Asia/Amman |
JP |
Asia/Tokyo |
KE |
Africa/Nairobi |
KG |
Asia/Bishkek |
KH |
Asia/Phnom_Penh |
KI |
Pacific/Tarawa |
KI |
Pacific/Enderbury |
KI |
Pacific/Kiritimati |
KM |
Indian/Comoro |
KN |
America/St_Kitts |
KP |
Asia/Pyongyang |
KR |
Asia/Seoul |
KW |
Asia/Kuwait |
KY |
America/Cayman |
KZ |
Asia/Almaty |
KZ |
Asia/Qyzylorda |
KZ |
Asia/Qostanay |
KZ |
Asia/Aqtobe |
KZ |
Asia/Aqtau |
KZ |
Asia/Atyrau |
KZ |
Asia/Oral |
LA |
Asia/Vientiane |
LB |
Asia/Beirut |
LC |
America/St_Lucia |
LI |
Europe/Vaduz |
LK |
Asia/Colombo |
LR |
Africa/Monrovia |
LS |
Africa/Maseru |
LT |
Europe/Vilnius |
LU |
Europe/Luxembourg |
LV |
Europe/Riga |
LY |
Africa/Tripoli |
MA |
Africa/Casablanca |
MC |
Europe/Monaco |
MD |
Europe/Chisinau |
ME |
Europe/Podgorica |
MF |
America/Marigot |
MG |
Indian/Antananarivo |
MH |
Pacific/Majuro |
MH |
Pacific/Kwajalein |
MK |
Europe/Skopje |
ML |
Africa/Bamako |
MM |
Asia/Yangon |
MN |
Asia/Ulaanbaatar |
MN |
Asia/Hovd |
MN |
Asia/Choibalsan |
MO |
Asia/Macau |
MP |
Pacific/Saipan |
MQ |
America/Martinique |
MR |
Africa/Nouakchott |
MS |
America/Montserrat |
MT |
Europe/Malta |
MU |
Indian/Mauritius |
MV |
Indian/Maldives |
MW |
Africa/Blantyre |
MX |
America/Mexico_City |
MX |
America/Cancun |
MX |
America/Merida |
MX |
America/Monterrey |
MX |
America/Matamoros |
MX |
America/Mazatlan |
MX |
America/Chihuahua |
MX |
America/Ojinaga |
MX |
America/Hermosillo |
MX |
America/Tijuana |
MX |
America/Bahia_Banderas |
MY |
Asia/Kuala_Lumpur |
MY |
Asia/Kuching |
MZ |
Africa/Maputo |
NA |
Africa/Windhoek |
NC |
Pacific/Noumea |
NE |
Africa/Niamey |
NF |
Pacific/Norfolk |
NG |
Africa/Lagos |
NI |
America/Managua |
NL |
Europe/Amsterdam |
NO |
Europe/Oslo |
NP |
Asia/Kathmandu |
NR |
Pacific/Nauru |
NU |
Pacific/Niue |
NZ |
Pacific/Auckland |
NZ |
Pacific/Chatham |
OM |
Asia/Muscat |
PA |
America/Panama |
PE |
America/Lima |
PF |
Pacific/Tahiti |
PF |
Pacific/Marquesas |
PF |
Pacific/Gambier |
PG |
Pacific/Port_Moresby |
PG |
Pacific/Bougainville |
PH |
Asia/Manila |
PK |
Asia/Karachi |
PL |
Europe/Warsaw |
PM |
America/Miquelon |
PN |
Pacific/Pitcairn |
PR |
America/Puerto_Rico |
PS |
Asia/Gaza |
PS |
Asia/Hebron |
PT |
Europe/Lisbon |
PT |
Atlantic/Madeira |
PT |
Atlantic/Azores |
PW |
Pacific/Palau |
PY |
America/Asuncion |
QA |
Asia/Qatar |
RE |
Indian/Reunion |
RO |
Europe/Bucharest |
RS |
Europe/Belgrade |
RU |
Europe/Kaliningrad |
RU |
Europe/Moscow |
UA |
Europe/Simferopol |
RU |
Europe/Kirov |
RU |
Europe/Astrakhan |
RU |
Europe/Volgograd |
RU |
Europe/Saratov |
RU |
Europe/Ulyanovsk |
RU |
Europe/Samara |
RU |
Asia/Yekaterinburg |
RU |
Asia/Omsk |
RU |
Asia/Novosibirsk |
RU |
Asia/Barnaul |
RU |
Asia/Tomsk |
RU |
Asia/Novokuznetsk |
RU |
Asia/Krasnoyarsk |
RU |
Asia/Irkutsk |
RU |
Asia/Chita |
RU |
Asia/Yakutsk |
RU |
Asia/Khandyga |
RU |
Asia/Vladivostok |
RU |
Asia/Ust-Nera |
RU |
Asia/Magadan |
RU |
Asia/Sakhalin |
RU |
Asia/Srednekolymsk |
RU |
Asia/Kamchatka |
RU |
Asia/Anadyr |
RW |
Africa/Kigali |
SA |
Asia/Riyadh |
SB |
Pacific/Guadalcanal |
SC |
Indian/Mahe |
SD |
Africa/Khartoum |
SE |
Europe/Stockholm |
SG |
Asia/Singapore |
SH |
Atlantic/St_Helena |
SI |
Europe/Ljubljana |
SJ |
Arctic/Longyearbyen |
SK |
Europe/Bratislava |
SL |
Africa/Freetown |
SM |
Europe/San_Marino |
SN |
Africa/Dakar |
SO |
Africa/Mogadishu |
SR |
America/Paramaribo |
SS |
Africa/Juba |
ST |
Africa/Sao_Tome |
SV |
America/El_Salvador |
SX |
America/Lower_Princes |
SY |
Asia/Damascus |
SZ |
Africa/Mbabane |
TC |
America/Grand_Turk |
TD |
Africa/Ndjamena |
TF |
Indian/Kerguelen |
TG |
Africa/Lome |
TH |
Asia/Bangkok |
TJ |
Asia/Dushanbe |
TK |
Pacific/Fakaofo |
TL |
Asia/Dili |
TM |
Asia/Ashgabat |
TN |
Africa/Tunis |
TO |
Pacific/Tongatapu |
TR |
Europe/Istanbul |
TT |
America/Port_of_Spain |
TV |
Pacific/Funafuti |
TW |
Asia/Taipei |
TZ |
Africa/Dar_es_Salaam |
UA |
Europe/Kiev |
UA |
Europe/Uzhgorod |
UA |
Europe/Zaporozhye |
UG |
Africa/Kampala |
UM |
Pacific/Midway |
UM |
Pacific/Wake |
US |
America/New_York |
US |
America/Detroit |
US |
America/Kentucky/Louisville |
US |
America/Kentucky/Monticello |
US |
America/Indiana/Indianapolis |
US |
America/Indiana/Vincennes |
US |
America/Indiana/Winamac |
US |
America/Indiana/Marengo |
US |
America/Indiana/Petersburg |
US |
America/Indiana/Vevay |
US |
America/Chicago |
US |
America/Indiana/Tell_City |
US |
America/Indiana/Knox |
US |
America/Menominee |
US |
America/North_Dakota/Center |
US |
America/North_Dakota/New_Salem |
US |
America/North_Dakota/Beulah |
US |
America/Denver |
US |
America/Boise |
US |
America/Phoenix |
US |
America/Los_Angeles |
US |
America/Anchorage |
US |
America/Juneau |
US |
America/Sitka |
US |
America/Metlakatla |
US |
America/Yakutat |
US |
America/Nome |
US |
America/Adak |
US |
Pacific/Honolulu |
UY |
America/Montevideo |
UZ |
Asia/Samarkand |
UZ |
Asia/Tashkent |
VA |
Europe/Vatican |
VC |
America/St_Vincent |
VE |
America/Caracas |
VG |
America/Tortola |
VI |
America/St_Thomas |
VN |
Asia/Ho_Chi_Minh |
VU |
Pacific/Efate |
WF |
Pacific/Wallis |
WS |
Pacific/Apia |
YE |
Asia/Aden |
YT |
Indian/Mayotte |
ZA |
Africa/Johannesburg |
ZM |
Africa/Lusaka |
ZW |
Africa/Harare |
Appendix C: values.yml examples
C.1. Minimal configuration
The configuration example is set as follows:
-
Default TLS settings are used for storage-storage configuration
-
Certificates and encryption key are generated by openssl commands
-
INFO log level is defined
-
If the parameters for the management configuration are not defined, the default values will be used.
config:
storage:
consul:
gossip_encryption_key: MhstT80sqle63WC7knOak+c7GfK7k5OY2n/4Qk/fSXs=
blob_store:
access_key: your_access_key
secret_key: your_secret_key
C.2. Management configuration with LDAP authentication
The configuration examples are set as follows:
-
LDAP authentication is configured without TLS.
-
The authentication configuration was tested using Microsoft Active Directory.
config:
mgmt:
configapi:
ldap:
ldap_url: ldap://ad.example.com
use_ntlm: on
bind_user: AD_domain\administrator # The name of the user follows the domain.
bind_password: your_administrator_password
user_base_dn: CN=Users,DC=example,DC=com
group_base_dn: CN=Users,CN=Builtin,DC=example,DC=com
allowed_groups:
- Users
storage:
consul:
gossip_encryption_key: MhstT80sqle63WC7knOak+c7GfK7k5OY2n/4Qk/fSXs=
blob_store:
access_key: your_access_key
secret_key: your_secret_key
config:
mgmt:
configapi:
ldap:
ldap_url: ldap://ad.example.com
use_ntlm: off
bind_user: CN=administrator,CN=Users,DC=example,DC=com # This must be the DN of the user
bind_password: your_administrator_password
user_base_dn: CN=Users,DC=example,DC=com
group_base_dn: CN=Users,CN=Builtin,DC=example,DC=com
allowed_groups:
- Users
storage:
consul:
gossip_encryption_key: MhstT80sqle63WC7knOak+c7GfK7k5OY2n/4Qk/fSXs=
blob_store:
access_key: your_access_key
secret_key: your_secret_key
Appendix D: LDAP certificate examples
-----BEGIN CERTIFICATE----- ... (the certificate for the CA)... -----END CERTIFICATE-----
-----BEGIN CERTIFICATE----- ... (the certificate for the CA)... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... (the root certificate for the CA's issuer)... -----END CERTIFICATE-----