webMethods API Gateway tutorial
Authors: Annamalai, Aravindhan & Raj, Gokul (External)
Supported Versions: 9.12 and above
Overview of the tutorial
While the API Gateway comes with a rich set of API mediation policies such as Identification and Access control, request and response processing, traffic monitoring and different kinds of API routing rules it also provides a competent out of the box support for the threat protection rules and their configuration to protect the API Gateway and its APIs from the malicious attacks by the outsider. It also makes sure that even the native services inside the Integration server are kept safe.
In general, though there are lot of techniques and concepts we can talk about threat protection, this tutorial covers the below steps in detail to help you understand how threat protection can be achieved in API Gateway.
- Threat protection flow for an API or service request
- Threat protection rules and their configuration
- Configuration of alert settings
- Use cases in different deployment scenarios
Required Knowledge
A basic understanding of API Gateway and its APIs along with the Integration server native services are sufficient to understand the threat protection rules and their configuration in API Gateway.
Why?
Without the threat protection, the API Gateway and its APIs and the native services of the Integration server are basically insecure. That means the potential hackers or malware or any anonymous outsiders could easily attempt to propagate a series of attacks such as DoS, SQL injection, etc through the requests to the APIs in API Gateway or the native services in the Integration server when they are hosted behind the firewall. These attacks may bring an irreversible damage to the internals of the organization which runs the API Gateway or the Integration server in its production environment. To the rescue of this situation, API Gateway standard edition as well as the advanced edition comes with an out of the box support for the threat protection by means of rules and configuration. In which case the API Gateway or the Integration server which hosts the APIs and native services are deployed in the Green zone i.e. behind the firewall with their ports restricted for the outsiders whereas the API Gateway standard edition which have the threat protection rules and support for their enforcement is deployed in the demilitarized zone (DMZ) with an external port open to the outside world. With this set up, almost all the APIs and services of the API Gateway and Integration server are protected from the outside attackers because any request which violates any of the threat protection rules would be rejected at the threat protection layer.
Prerequisite steps
Complete the below prerequisites to make you ready to get into the details of the threat protection support in API Gateway.
- Install API Gateway standard and advanced editions of version 9.12 or greater
- Install a stand alone Integration server (without API Gateway) of version 9.12 or greater
- Install the attached IS package (WmEmployeeManagementSample.zip) for our tutorial's native REST service
- Create a REST API in API Gateway advanced edition using the attached Swagger file (EmployeeManagementSwagger.json)
- Edit the REST API and add the Outbound Authentication - Transport policy with Basic Authentication scheme as the native service is protected with Basic authentication. The credentials are Administrator / manage
Details
The below sections describe the details of threat protection flow, rules and their configuration elaborately followed by the demonstration of some of the use cases where threat protection can be achieved in real time scenarios.
Threat protection flow for an API or service request
The below steps explain how threat protection works when an API or service in the API Gateway is invoked through the external port of the threat protection layer.
- External client sends the request to the external port of the API Gateway which is running in the DMZ zone
- API Gateway collects client information from the request and evaluates the request against any threat protection rules and policies that have been defined. It then passes the request to the internal server when there is no violation. The internal server can be an API Gateway advanced edition or simply an Inttegration server. The communication between the API Gateway in DMZ and the internal server which is hosted in the Green zone is achieved using Reverse Invoke
- The internal server processes the request and sends the response to API Gateway in DMZ
- The API Gateway then passes the response back to the client
- If the request violates any threat protection rule, the request will be rejected and an error message configured in API Gateway would be sent to the client
The above steps are depicted in the below diagram.
Threat protection rules and their configuration
API Gateway supports the configuration and enforcement of the following threat protections rules.
| # | Threat protection rule name | Description |
|---|---|---|
| 1 | Denial of Service |
Denial of Service (DoS) attacks can be prevented by configuring Denial of Service protection. You can limit the number of requests that your API Gateway accepts within a specified time interval from all IP addresses (or) individual IP addresses |
| 2 | Trusted IPs |
To ensure that requests from trusted servers are not denied, you can configure a white-list of IP addresses so that requests from these IP addresses are always allowed |
| 3 | Message Size Filter |
This filter allows to specify the message size limit. If the request is larger than the size specified in this limit, the request violates the rule and configured action would be taken |
| 4 | Mobile Application & Devices Filter |
This filter regulates requests from mobile applications by only allowing requests from certain versions of an application and from certain device types |
| 5 | SQL Injection Filter |
SQL injection protection filter allows to block requests that could possibly cause an SQL injection attack |
| 6 | Antivirus Scan Filter |
Antivirus scan filter allows you to configure API Gateway to interact with an Internet Content Adaptation Protocol (ICAP) compliant server |
| 7 | JSON threat protection filter |
JavaScript Object Notation (JSON) is vulnerable to content level attacks. Such attacks attempt to use huge json files to overwhelm the parser and eventually crash the service |
| 8 | XML threat protection filter |
Malicious attacks on XML applications typically involve large, recursive payloads, XPath/XSLT or SQL injections, and CData to overwhelm the parser and eventually crash the service |
| 9 | Custom Filter |
Custom filter can be used to invoke an IS service that is available on the API Gateway. Using this filter, API Gateway can leverage the ICAP protocol to scan the entire incoming request for viruses |
All these threat protection rules are imposed only when they are sent to the external port. A detailed view of the above said threat protection filters and their configuration in API Gateway can be read and understood by a separate list of tutorials referenced below.
- Denial of Service
- Message Size Filter
- Mobile Application Protection Filter
- SQL Injection Protection Filter
- Antivirus Scan Filter
- JSON Threat Protection Filter
- XML Threat Protection Filter
- Custom Filter
Configuration of alert settings
Now lets see the alert settings in API Gateway that defines what happens for request which violates the threat protection rules. When a request violates a threat protection rule, the API Gateway would either deny the request or allow the request and send an alert about the violation through notifications such as Email or Flow service for that particular request. This behavior is controlled by two types of threat protection rules.
Denial rules
The API Gateway denies the request and sends an alert. The server stops processing the request as soon as it detects a match to a filter and does not consider other filters in the rule or any other rules for this request.
Alert rules
API Gateway sends an alert about the violation and then continues processing the request.
Configuration in API Gateway
The alert settings can be configured at a Global level or at a Rule level. If a rule is configured with alert settings then it overrides the global alert configuration. API Gateway provides two ways to generate an alert.
- Flow Service
Flow Service
In this case when a violation occurs, the configured IS service is invoked with the configured user. The configuration of the flow service is described below.
Send Alert
This option controls when an alert has to be sent to the configured destination.
- On Rule Violation - Alert is generated and sent to the configured destination
- Every - An alert is sent to the configured destination for every configured interval of time
webMethods IS Service
The name of the flow service which has to be invoked upon a violation.
Run as user
The user with which the flow service should get executed
In this case when a violation occurs, an email is sent to the configured mail ids.
Email Ids
Any number of email aliases can be configured and every alias receives an alert when there is a violation. The below screen shot shows the configuration of Email alert destination.
Use cases in different deployment scenarios
Now lets go through the different deployment scenarios where threat protection can be configured and enforced in API Gateway. API Gateway uses Reverse Invoke, a secure connection establishment between the API Gateway in DMZ and the internal server in Green zone, to effectively enforce the threat protection rules for an API request. For a detailed understanding of different deployment scenarios of API Gateway and Reverse Invoke, a separate article is published at Configure Reverse Invoke in webMethods API Gateway API Gateway, please go through that.
Use case 1: API Gateway standard edition in DMZ & Integration Server in Green zone
In all the use cases the threat protection is enforced in API Gateway which is hosted in the DMZ. In this use case the API Gateway standard edition is hosted in DMZ and an Integration server is set up in Green zone. Follow the below steps to configure the threat protection in this deployment scenario.
Step 1: Create external and registration ports
Create an external and a registration port in the API Gateway standard edition which is running in DMZ. The external port is the one which would be exposed to the outside world and to which all the API or service requests would come at first. All the internal server ports would be open behind the firewall and have access within the Green zone and access outside the firewall is restricted. Upon success, the request would reach the registration port from the external port.
Go to Administration → Security → Ports and click Add ports. Select type API Gateway external and enter the port details as below. In this example the external port is 6666 and the registration port is 6667.
Step 2: Create internal port
Create an internal port in the Integration server which is running in the Green zone. This internal port is a listener port which is not exposed to the outside world. This port listens for the API or service requests (which comes from external port) at the registration port created at Step 1 and through Reverse Invoke pulls the requests and routes them to the requested service inside the internal server, in this case the Integration server. Follow the below steps to create the internal port.
In the Integration server's administration page, Go to Security → Ports and click Add Port. Select the Internal Server and enter the below details.
Host
The host name of the API Gateway standard edition which is running in DMZ.
Port
The registration port number created in API Gateway standard edition in Step 1.
Registration Credentials
The basic authentication credentials of the API Gateway standard edition which is running in DMZ.
Change access mode
After the successful creation of the internal port change the Access mode of the port to Allow by Default in Ports page.
Step 3: Configure threat protection rule
For the example configure a threat protection rule for e.g Global denial of service in API Gateway standard edition which is running in DMZ.
Step 4: Service invocation
Now open a REST client and invoke an native service in the Integration server on the external port more than 5 times. When the number of invocation exceeds 5 (in our example), the Global denial of service threat protection filter is violated and an error message is sent to the client.
Use case 2: API Gateway standard edition in DMZ & API Gateway advanced edition in Green zone
In this use case the API Gateway standard edition is set up in DMZ and an API Gateway advanced edition is set up in Green zone. With the API Gateway standard edition setup, configuration of external ports and a sample threat protection rule we did in Use case 1, follow the below steps to configure threat protection in this deployment scenario.
Step 1: Create internal port
Create the internal port in API Gateway advanced edition which is running in Green zone.
After the internal port is created, enable it to listen for requests at the registration port in the API Gateway standard edition which is running in DMZ.
Step 2: Configure load balancer URL
Configure the load balancer URL with the host and port as the API Gateway standard edition host name and its external port.
The load balancer URL is configured so that the APIs in the API Gateway advanced edition would have the external port as the endpoint's port in their endpoint URL.
Step 3: API invocation
Now open a REST client and invoke an API in API Gateway advanced edition using the endpoint configured with the external port more than 5 times. The Global denial of service threat protection filter is violated and an error message is sent to the client.
Limitations
The only limitation with the threat protection in API Gateway is that all the threat protection rules are enforced only on the external port. All the requests directed to other ports do not go through the threat protection rules enforcement.
Troubleshooting
| # | Error | Message | Solution |
|---|---|---|---|
| 1 | Unable to access external port |
Access Denied. Services necessary to show the Integration Server Administrator are currently unavailable to this port. This is most likely due to port security restrictions.If this is the only port available to access the Integration Server, contact webMethods Support. |
Make sure that the access mode for the internal port is modified to "Allow by default" |
| 2 | Unable to access external port |
Error unsafe port |
If you are using a chrome browser add "--explicitly-allowed-ports=xxxx" to the executable command |
| 3 | Unable to access external port |
Access Denied |
Make sure that the registration credentials are provided for the internal port configuration |
References
For a detailed understanding on Reverse Invoke configuration please refer Configure Reverse Invoke in webMethods API Gateway
Please refer the API Gateway User Guide documentation to know about the email server configuration
Downloadable artifacts
The below files can be found in the attachments.
- IS Sample services Package - WmEmployeeManagementSample.zip
- Swagger file for the service - EmployeeManagementSwagger.json
Learn more
To know about the analytics dashboard for the threat protection events in API Gateway, please refer Threat Protection Dashboards
