Guidance for Application Programming Interface (API) Gateways

On this page

1. Manage the Traffic
2. Control the Connectivity
3. Control the Access
4. Inspect the Content
5. Monitor the Requests

Application Programming Interfaces (APIs) provide powerful interfaces to remotely access data and system functionality. Direct system-to-system access enabled through APIs increases the risk and impact of a security breach. API security should be top of mind in any API implementation. The API Gateway is a solution concept to address the various security risks associated with exposing APIs both within and outside of an organization, such as throttling and proxying.

• Why do we need API Gateways? Different security and policy controls are essential when managing access to your APIs internally and externally to your organization. API Gateways allow you to adapt to the significantly higher risk profile of your externally-accessible APIs. API Gateways also provide the ability to externalize controls to avoid defining those policies into each of the APIs themselves.
• How do I implement API Gateways? While there are a number of products calling themselves API Gateways, there is a large variation in functionality and focus of these technologies (e.g., security vs. traffic management). This guidance document provides a reference list of controls and in which scenarios they need to be applied to aid in your decisions on which API Gateway products to deploy and what additional controls need to be implemented.
• Do I need to put API Gateways in front of all of my APIs? Not necessarily. Different usage scenarios for APIs require different policy controls. Government of Canada Standards on APIs states that all internet-facing APIs must use gateways and proxies instead of whitelists. When dealing with internal or GC-to-GC APIs, whether or not an API Gateway component is needed to manage access to your API is completely up to you, as long as you are able to address the necessary controls.
• Do I need to go through an API Gateway to access external or third party APIs? No. API Gateways control access to your APIs (i.e., inbound). Outbound requests to someone else’s APIs should follow normal network and connectivity security policies and best practices such as going through a forward proxy.
• Do I still need to implement API level security if I implement API Gateways? Yes. Defence-in-depth should be practiced when implementing APIs. APIs can be attacked in many of the same ways as web applications, as both are HTTP based. Therefore, OWASP Controls should still be applied holistically to the API.

This guide is intended to serve as a baseline set of considerations for technical practitioners (e.g., API developers, architects) when implementing API-centric solutions. It is by no means an exhaustive list of all possible API Gateway functionality. The marketplace for API Gateway technologies is evolving rapidly, especially due to the rise of microservice architectures, and the boundaries between API Gateways, API Management, Enterprise Service Buses, and Service Meshes are blurring quickly. There is no one-size-fits-all approach to API Gateways and it is unlikely that a single product will address all of your needs.

1. Manage the Traffic

Various methods should be deployed to control the amount of traffic hitting an API to reduce the risk of an API being brought down due to unexpected high request loads, either malicious or not. Most of these methods are available in even the most basic open source HTTP reverse proxy technologies (e.g., NGINX).

• Throttling – APIs should ideally be deployed to hyperscale infrastructure such as Cloud and have automated scaling implemented. Realistically, the large majority of the infrastructure across the GC is fixed capacity in nature. The ability to set request rate limits (e.g., 1000 requests per minute) for specific APIs should be mandatory for any exposed to other departments or external parties. It is much better to have a throttle limit return error codes back to API consumers when limits are reached than to have the API go down as a result of excessive load.
• Caching – Read-only APIs, especially those against slow-changing reference data (e.g., country codes, office locations, organization chart information), should be cached at the API Gateway layer if the frequency of requests is expected to be high or can have extreme peaks. Caching this kind of data stored in memory at the Gateway layer limits the processing load on the API each time. Transactional APIs or those where repeated queries against the same record is unlikely (e.g., individual tax data) should not be cached.
• Quality of Service (QoS) – There may be preferential treatment given to certain API consumers to offer a higher level of transaction rate (e.g., fee for service APIs, trusted partners, and public safety systems). In these cases, a Gateway technology with a QoS feature should be selected. QoS is typically only available on Gateways embedded within API Management platforms or those with a more robust access control capability set as QoS is highly dependent on the ability to manage API consumer credentials (e.g., keys, certificates) inside the Gateway.
• Intrusion Detection – Denial of Service (DoS, DDoS) attacks are a major concern for internet-facing APIs. Any APIs accessible from the internet should be protected with appropriate boundary protection and security services such as DoS protection and Intrusion Detection System (IDS)/Intrusion Protection System (IPS). The Government of Canada’s secure perimeter initiatives (e.g., TIP/CAP) may address this in the future.
• Load Balancing – Load balancing across a cluster of API nodes at the API Gateway layer should only be implemented if an existing web (i.e., HTTPS) load balancer does not already exist for the solution.

2. Control the Connectivity

API Gateways provide a connectivity consolidation point to simplify and control network flows between APIs and API consumers. This is particularly important for APIs exposed to other departments or external parties as the internal IPs should be abstracted from external systems. This also ensures any internal changes to deployment topology or infrastructure does not impact the API consumers. These features are typically available in any HTTP reverse proxy technologies and are universally available in most API Gateway products.

• Routing and proxying – The API Gateway layer should present a single base URL to external consumers which would then route to a number of host URLs for APIs in the backend. APIs should only see traffic coming from the API Gateway layer instead of the outside API consumers.
• IP whitelisting – APIs exposed to trusted partners over the internet should implement IP whitelisting in the API Gateway layer to reduce the risk of attacks and unauthorized access. While IP whitelisting for on-premises APIs can be implemented at the network layer, having the controls being managed by the API operations teams will speed up the process to onboard and offboard partners. Care should be taken in scenarios where consuming systems may not have static IPs (e.g., cloud-hosted) and therefore IP ranges should be used.

3. Control the Access

More robust API Gateway solutions offer authentication and authorization on API requests. While offloading the heavy lifting in authentication and authorization logic makes sense in some cases, it does not mean that authentication or authorization is not required at the API level as well. Unauthenticated APIs are only appropriate for Open Data and public unclassified APIs, while Gateway access control is an added layer of security for more sensitive data.

• Authentication – The API Gateway layer should at minimum be configured to carry out some level of authentication on behalf of the backend API. This authentication ensures that invalid connection attempts are dealt with before the request ever gets to the API, which reduces risk and unnecessary processing. However, the authentication design should take into account whether the backend API needs to be aware of the identity of the API consumer. In many cases, other more advanced API Gateway functionality such as QoS and usage tracking require the authentication to happen at the API Gateway so that traffic can be associated with specific API consumers.
• Credential translation – Backend APIs do not always need to uniquely authenticate each API consumer. For example, an address verification API that verifies that a given address is valid may not require user-level information. In those cases, it is sufficient for the API Gateway to authenticate via a single generic system API key. In other cases, the consumer credential or system identifier is needed but only for auditing purposes. This can be achieved by translating the API consumer credential into an attribute string that is added to the request content sent to the backend API.

  Credential translation is not typically seen as an explicit feature on most API Gateway products, but rather an implementation pattern carried out through a combination of selecting the appropriate authentication mechanisms and leveraging request translation capabilities.

• Coarse-grained authorization – Managing authorization at the API Gateway layer should be limited to the resource or operations level at most. Any fine-grained authorizations such as data filtering should be left up to the backend API itself.

4. Inspect the Content

Security-focused API Gateway solutions provide the ability perform a significant amount of the payload data security controls in addition to implementing it within the API itself. The goal is to move the initial security enforcement point further into the perimeter and away from the data without compromising the security posture of the API itself.

• Digital signature verification – For APIs with high-integrity requirements, the validation of the digital signature should be done at the API Gateway layer to ensure that tampered messages are rejected at the perimeter. Security-optimized API Gateway solutions also tend to deal with cryptographic validations faster, which reduces the processing overhead for the API itself and improves both throughput and response time.
• Malicious content scanning – Like all other web payloads, malicious content such as scripts or malware can be embedded into an API request. All API requests from external sources should be scanned for malicious content at the perimeter and any threats rejected before they ever reach the API. While content scanning of API requests from internal systems or trusted partners is generally not required, in the case of federated or forwarded API requests care should be taken to understand where the originating request came from.
• Request schema validation – Some APIs benefit from having schema validations conducted at the API Gateway layer. The gateway can validate the request message against the expected schema and reject any malformed requests. In scenarios where the throughput is expected to be high or where the API is public facing, the risk of malformed messages is greater and thus offloading that processing overhead is beneficial. This implementation does require increased deployment and testing complexities to keep the API Gateway synchronized with request schema changes, but that operational trade-off can be worthwhile to prevent the burden of dealing with large numbers of malformed messages at the API level.
• Request schema mapping – Request schema translations have traditionally been an Enterprise Service Bus (ESB) function. API Gateway solutions have increasingly offered this feature for scenarios where there is insufficient complexity to justify an ESB, but there is a need to account for different request schemas (e.g., internal vs. external consumer of the same API). Mapping a consumer request schema to the backend API schema is appropriate in the API Gateway solution only if the mapping is straight forward (i.e., attribute names only) and does not involve data manipulation (e.g., concatenation) or logic (e.g., conditional translations, calculations). Actual business logic should be avoided and be handled by the API.

5. Monitor the Requests

All traffic through the API Gateway solution should be monitored, logged, and reported on. This data is one of the key benefits to using a gateway and should be used to provide both an operational and a business view on how the API is being leveraged and how it is performing.

• Usage reporting – All request statistics (e.g., requesting API consumer, time of access, response time, operations requested) should be captured and reported on at the API Gateway layer, including both successful and failed requests. The API Gateway should be able to provide out-of-box dashboards for usage metrics or provide some method of exporting the data to a 3^rd party operational reporting solution.
• Request auditing and logging – All API requests should be logged by the API Gateway with the following information being captured as a minimum:
  • API name and destination URL
  • API operation
  • Consumer API key and ID
  • Time of request
  • Response HTTP code or error code
  • Internal error code (if applicable)

  The API Gateway should have the option to capture more API details for API interactions with specific audit requirements such as payload and response.

• Suspicious activity reporting – The API Gateway Solution should be able to identify and flag suspicious usage patterns such as:
  • Multiple invalid API keys
  • Same API key being requested from multiple IPs or locations
  • Multiple attempts to access unauthorized operations/data
  • Multiple failures on digital signature verification
  • Any content-related security violations