Running API Firewall on Docker¶
This guide walks through downloading, installing, and starting Wallarm API Firewall on Docker.
OpenAPI 3.0 specification developed for the REST API of the application that should be protected with Wallarm API Firewall
Methods to run API Firewall on Docker¶
The fastest method to deploy API Firewall on Docker is Docker Compose. The steps below rely on using this method.
If required, you can also use
docker run. We have provided proper
docker run commands to deploy the same environment in this section.
Step 1. Create the
To deploy API Firewall and proper environment using Docker Compose, create the docker-compose.yml with the following content first:
version: '3.8' networks: api-firewall-network: name: api-firewall-network services: api-firewall: container_name: api-firewall image: wallarm/api-firewall:v0.6.9 restart: on-failure volumes: - <HOST_PATH_TO_SPEC>:<CONTAINER_PATH_TO_SPEC> environment: APIFW_API_SPECS: <PATH_TO_MOUNTED_SPEC> APIFW_URL: <API_FIREWALL_URL> APIFW_SERVER_URL: <PROTECTED_APP_URL> APIFW_REQUEST_VALIDATION: <REQUEST_VALIDATION_MODE> APIFW_RESPONSE_VALIDATION: <RESPONSE_VALIDATION_MODE> ports: - "8088:8088" stop_grace_period: 1s networks: - api-firewall-network backend: container_name: api-firewall-backend image: kennethreitz/httpbin restart: on-failure ports: - 8090:8090 stop_grace_period: 1s networks: - api-firewall-network
Step 2. Configure the Docker network¶
If required, change the Docker network configuration defined in docker-compose.yml →
The provided docker-compose.yml instructs Docker to create the network
api-firewall-network and link the application and API Firewall containers to it.
It is recommended to use a separate Docker network to allow the containerized application and API Firewall communication without manual linking.
Step 3. Configure the application to be protected with API Firewall¶
Change the configuration of the containerized application to be protected with API Firewall. This configuration is defined in docker-compose.yml →
The provided docker-compose.yml instructs Docker to start the kennethreitz/httpbin Docker container connected to the
api-firewall-network and assigned with the
backend network alias. The container port is 8090.
If configuring your own application, define only settings required for the correct application container start. No specific configuration for API Firewall is required.
Step 4. Configure API Firewall¶
Pass API Firewall configuration in docker-compose.yml →
services.api-firewall as follows:
services.api-firewall.volumes, please mount the OpenAPI 3.0 specification to the API Firewall container directory:
<HOST_PATH_TO_SPEC>: the path to the OpenAPI 3.0 specification for your application REST API located on the host machine. The accepted file formats are YAML and JSON (
.jsonfile extensions). For example:
<CONTAINER_PATH_TO_SPEC>: the path to the container directory to mount the OpenAPI 3.0 specification to. For example:
services.api-firewall.environment, please set the general API Firewall configuration through the following environment variables:
| ||Path to the OpenAPI 3.0 specification. There are the following ways to specify the path: ||Yes|
| ||URL for API Firewall. For example: |
If API Firewall listens to the HTTPS protocol, please mount the generated SSL/TLS certificate and private key to the container, and pass to the container the API Firewall SSL/TLS settings described below.
| ||URL of the application described in the mounted OpenAPI specification that should be protected with API Firewall. For example: ||Yes|
| ||API Firewall mode when validating requests sent to the application URL: ||Yes|
| ||API Firewall mode when validating application responses to incoming requests: ||Yes|
| ||API Firewall logging level. Possible values: ||No|
| ||HTTP response status code returned by API Firewall operating in the ||No|
|Whether to return the header ||No|
| ||The format of API Firewall logs. The value can be ||No|
(only if API Firewall is operating in the
|HTTP response status codes indicating that the requested API endpoint that is not included in the specification is NOT a shadow one. You can specify several status codes separated by a semicolon (e.g. |
By default, API Firewall operating in the
More API Firewall configuration options are described within the link.
services.api-firewall.networks, set the API Firewall container port and connect the container to the created network. The provided docker-compose.yml instructs Docker to start API Firewall connected to the
api-firewall-network network on the port 8088.
Step 5. Deploy the configured environment¶
To build and start the configured environment, run the following command:
docker-compose up -d --force-recreate
To check the log output:
docker-compose logs -f
Step 6. Test API Firewall operation¶
To test API Firewall operation, send the request that does not match the mounted Open API 3.0 specification to the API Firewall Docker container address. For example, you can pass the string value in the parameter that requires the integer value.
If the request does not match the provided API schema, the appropriate ERROR message will be added to the API Firewall Docker container logs.
Step 7. Enable traffic on API Firewall¶
To finalize the API Firewall configuration, please enable incoming traffic on API Firewall by updating your application deployment scheme configuration. For example, this would require updating the Ingress, NGINX, or load balancer settings.
API Firewall fine-tuning options¶
To address more business issues by API Firewall, you can fine-tune the tool operation. Supported fine-tuning options are listed below. Please pass them as environment variables when configuring the API Firewall Docker container.
Validation of request authentication tokens¶
If using OAuth 2.0 protocol-based authentication, you can configure API Firewall to validate the access tokens before proxying requests to the application's server. API Firewall expects the access token to be passed in the
Authorization: Bearer request header.
API Firewall considers the token to be valid if the scopes defined in the specification and in the token meta information are the same. If the value of
BLOCK, API Firewall blocks requests with invalid tokens. In the
LOG_ONLY mode, requests with invalid tokens are only logged.
To configure the OAuth 2.0 token validation flow, use the following optional environment variables:
| ||The type of authentication token validation: |
| ||The algorithm being used to sign JWTs: |
JWTs signed using the
| ||If JWTs are signed using the RS256, RS384 or RS512 algorithm, the path to the file with the RSA public key ( |
| ||If JWTs are signed using the HS256, HS384 or HS512 algorithm, the secret key value being used to sign JWTs.|
| ||Token introspection endpoint. Endpoint examples: |
| ||The method of the requests to the token introspection endpoint. Can be |
The default value is
| ||The name of the parameter with the token value in the requests to the introspection endpoint. Depending on the |
| ||The Bearer token value to authenticate the requests to the introspection endpoint.|
| ||The value of the |
| ||Time-to-live of cached token metadata. API Firewall caches token metadata and if getting requests with the same tokens, gets its metadata from the cache. |
The interval can be set in hours (
The default value is
Blocking requests with compromised authentication tokens¶
If an API leak is detected, the Wallarm API Firewall is able to stop the compromised authentication tokens from being used. If the request contains compromised tokens, API Firewall responses to this request with the code configured via
To enable the denylist feature:
Mount the denylist file with compromised tokens into the Docker container. The denylist text file may look as follows:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZDk5OTk5ODIifQ.CUq8iJ_LUzQMfDTvArpz6jUyK0Qyn7jZ9WCqE0xKTCA eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZDk5OTk5ODMifQ.BinZ4AcJp_SQz-iFfgKOKPz_jWjEgiVTb9cS8PP4BI0 eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZDk5OTk5ODQifQ.j5Iea7KGm7GqjMGBuEZc2akTIoByUaQc5SSX7w_qjY8
Configure the denylist feature passing the following variables to the Docker container:
Environment variable Description
The path to the text denylist file mounted to the container. The tokens in the file must be separated by newlines. Example value:
The name of the Cookie used to pass the authentication token.
The name of the Header used to pass the authentication token. If both the
APIFW_DENYLIST_TOKENS_HEADER_NAMEvariables are specified, API Firewall sequentially checks its values.
Whether to trim the
Bearerprefix from the authentication header when comparing its value with the denylist contents. If the
Bearerprefix is passed in the authentication header and tokens in the denylist do not contain this prefix, tokens will not be validated reliably.
The value can be
false. The default value is
Protected application SSL/TLS settings¶
To facilitate the connection between API Firewall and the protected application's server signed with the custom CA certificates or insecure connection, use the following optional environment variables:
| ||Whether to disable validation of the SSL/TLS certificate of the protected application server. The server address is specified in the variable |
The default value is
(only if the
|The path to the protected application server's CA certificate in the Docker container. The CA certificate must be mounted to the API Firewall Docker container first.|
API Firewall SSL/TLS settings¶
To set up SSL/TLS for the server with the running API Firewall, use the following optional environment variables:
| ||The path to the container directory with the mounted certificate and private key generated for API Firewall.|
| ||The name of the file with the SSL/TLS certificate generated for API Firewall and located in the directory specified in |
| ||The name of the file with the SSL/TLS private key generated for API Firewall and located in the directory specified in |
To fine-tune system API Firewall settings, use the following optional environment variables:
| ||The timeout for API Firewall to read the full request (including the body) sent to the application URL. The default value is |
| ||The timeout for API Firewall to return the response to the request sent to the application URL. The default value is |
| ||The maximum number of connections that API Firewall can handle simultaneously. The default value is |
| ||The timeout for API Firewall to read the full response (including the body) returned to the request by the application. The default value is |
| ||The timeout for API Firewall to write the full request (including the body) to the application. The default value is |
| ||The timeout for API Firewall to connect to the application. The default value is |
| ||Maximum number of the fasthttp clients. The default value is |
| ||The host of the health check service. The default value is |
Stopping the deployed environment¶
To stop the environment deployed using Docker Compose, run the following command:
docker run to start API Firewall¶
To start API Firewall on Docker, you can also use regular Docker commands as in the examples below:
To create a separate Docker network to allow the containerized application and API Firewall communication without manual linking:
docker network create api-firewall-network
To start the containerized application to be protected with API Firewall:
docker run --rm -it --network api-firewall-network \ --network-alias backend -p 8090:8090 kennethreitz/httpbin
docker run --rm -it --network api-firewall-network --network-alias api-firewall \ -v <HOST_PATH_TO_SPEC>:<CONTAINER_PATH_TO_SPEC> -e APIFW_API_SPECS=<PATH_TO_MOUNTED_SPEC> \ -e APIFW_URL=<API_FIREWALL_URL> -e APIFW_SERVER_URL=<PROTECTED_APP_URL> \ -e APIFW_REQUEST_VALIDATION=<REQUEST_VALIDATION_MODE> -e APIFW_RESPONSE_VALIDATION=<RESPONSE_VALIDATION_MODE> \ -p 8088:8088 wallarm/api-firewall:v0.6.9
When the environment is started, test it and enable traffic on API Firewall following steps 6 and 7.