Manage API Protection

After you have configured and deployed API Protection for your API, you can update the protection if your API changes, add or remove protection tokens, or change the operation mode of API Protection.

Reconfigure API Protection

If your API has changed, you can reconfigure its protection configuration. Any active API Firewall instances protecting the API are automatically restarted to run the new configuration.

  1. In 42Crunch Platform, go to the API collection you want.
  2. Click the API you want.
  3. Under Protection, click the reconfigure button.
  4. Confirm reconfiguration, and click Reconfigure.

A new protection configuration is created based on the API definition, and running API Firewall instances are reconfigured. Reconfiguration is graceful, meaning that ongoing transactions are completed without interruption, while new transactions will be serviced using the new configuration.

Note In the rare case that an API Firewall instance receives a configuration that is not valid and cannot be run, the instance and its Kubernetes pod immediately exit and this is logged in your Kubernetes logs.

When you reconfigure the protection configuration, the existing associated protection token is not regenerated but stays the same. To change a protection token for an API, you must create the new token manually.

Create or revoke protection tokens manually

You can create more than one protection token for your API, and use them to manage deployments in multiple environments independently of one another. You can also revoke protection tokens that are no longer needed.

TipIf you have several APIs and several environments, it can be difficult to keep track of where each protection token is used. To stay on top of things, in addition to giving descriptive names to protection tokens, use descriptive names for your stored secrets as well, for example, in Kubernetes secrets. We recommend that you include the name of the token and the name or API UUID of the API in the name of the secret. For example, in a Kubernetes secret generic-pixi-protection-token, generic is the name entered for the token when it was created and pixi is the name of the API the token was created for.

  1. On the Protection tab of the API, click Protection Tokens.

    The Protection tab of an API showing the menu on the left.

  2. Click Create Token.
  3. Enter a unique name for the protection token, and click Generate Token.
  4. Copy the token value and add it to your secrets.
  5. To revoke a protection token, click the Revoke button on the token.

If you want to change a protection token that is used in running API Firewall instances, you must reconfigure the firewall instances and redeploy them so that they run the correct protection configuration.

Configure health check for API Firewall

API Firewall instances provide a dedicated endpoint /hc for health check calls that, for example, load balancers can use to check that the instance is up and running. The health check uses the port 8880, so the API Firewall container (or AWS task) must expose that port. However, the load balancer must not expose the port.

  • Docker: To check that a container is healthy and the firewall instance is running properly, use the following command as the CMD/CMD_SHELL argument:
    "echo $'GET /hc HTTP/1.0\\r\\n\\rn' | nc 8880"

    For more details, see the Docker documentation.

  • Kubernetes: To configure Kubernetes probes, add the following to your Kubernetes deployment file:
          - name: apifirewall
            image: '42crunch/apifirewall:latest'  # replace latest by proper tag in prod environment.
            imagePullPolicy: Always
                path: /hc
                port: 8880
              initialDelaySeconds: 2
              periodSeconds: 5

    For more details on Kubernetes probes, see the Kubernetes documentation.

  • Load balancer: Configure your load balancer to make health checks using the following settings:
    • Protocol: HTTP
    • Port: 8880
    • Path: /hc
    • Return code: 200

    The settings may vary depending on your load balancer, for more details, see the documentation of your load balancer. The following shows is an example of configuring the health check in AWS:

    You call the health check endpoint from the load balancer with http://localhost:8880/hc. Note that HTTPS is not supported.

Switch API Protection to non-blocking mode

By default, active API Firewall instances protecting an API block any transactions that are in violation of the API contract. However, if needed, you can switch API Protection to non-blocking mode.

Security risk Non-blocking mode leaves your API unprotected! API Firewall instances execute security policies normally but do not block any transactions, they only report on what would have been blocked. Proceed with caution, and only use non-blocking mode when absolutely necessary.

  1. On the Protection tab of the API, click Settings.
  2. Switch Non-blocking mode on, and click Save Changes.
  3. Confirm switching non-blocking mode on, and click Confirm.

API Protection changes the protection configuration for this API to non-blocking mode. Any active API Firewall instances protecting the API are automatically restarted.

We recommend you switch off the non-blocking mode and return API Protection to normal operation mode as soon as possible.

Switch API Firewall to use HTTP connections

By default, the listener interface of API Firewall only accepts HTTPS connections, and you must specify the variables LISTEN_SSL_CERT and LISTEN_SSL_KEY. If you want to use HTTP connections instead, you can add the variable LISTEN_NO_TLS to your API Firewall configuration.

  1. Open the file for configuring the API Firewall variables. Where this is done depends on the environment of your deployment. For more details, see Deploy API Firewall for your own APIs.
  2. Add the environment variable LISTEN_NO_TLS and a value to it (for example, LISTEN_NO_TLS=ON, LISTEN_NO_TLS=TRUE, or LISTEN_NO_TLS=1). This variable does not need a specific value, simply adding the variable name is enough, but deploying the configuration fails if a value is not defined.
  3. Save the file, and redeploy API Firewall.

The listener interface of API Firewall now accepts HTTP connections instead of HTTPS connections. The TLS setup is ignored, so you do not need to specify LISTEN_SSL_CERT and LISTEN_SSL_KEY. If you have, you do not need to remove them, these variables are just ignored.

To switch API Firewall back to its default behavior and accept only HTTPS connections, remove LISTEN_NO_TLS from the configuration file, and make sure that the TLS setup is correctly defined, then redeploy API Firewall.

Note To switch back to HTTPS, you must completely remove the variable LISTEN_NO_TLS from the API Firewall configuration. Changing the value to false does nothing.

Switch logs destination for API Firewall logs

By default, API Firewall publishes logs to 42Crunch Platform. You can switch the logs destination to a separate directory you mount in your deployment.

An example screenshot showing two active instances for the Pixi API.

  1. Open the file for configuring the API Firewall variables. Where this is done depends on the environment of your deployment. For more details, see Deploy API Firewall for your own APIs.
  3. Add the directory where you want to publish logs in the mounted volumes in your deployment.
  4. Redeploy API Firewall. The logs are now published to the directory you mounted.

If you switch the logs destination away from 42Crunch Platform, you can no longer monitor the real-time traffic there. For more details, see API monitoring.

Note If you want switch back and publish the logs to 42Crunch Platform again, in addition to changing the LOG_DESTINATION property, you must also unmount the directory you added for the logs. Otherwise, API Firewall might not start correctly.