Apiman Policies

There are authentication-based policies which manage access to an API is governed by the identity of the user. And there are authorization-based policies which manage access to an API, or specific resources provided by an API, is governed by the role(s) assigned to a user.

Apiman supports these types of security policies:

Some Apiman policies provide an all-or-nothing level of control over access to managed APIs. For example, IP Blacklist or Whitelist policies either block or enable all access to a managed API, based on the IP address of the client. Rate limiting and quota policies provide you with more flexible ways to govern access to managed APIs. With rate limiting and quota policies, you can place limits on either the number of requests an API will accept over a specified period of time, or the total number of of bytes in the API requests. In addition, you can use combinations of fine-grained and coarse-grained rate limiting policies together to give you more flexibility in governing access to your managed API.

The ability to throttle API requests based on request counts and bytes transferred provides even greater flexibility in implementing policies. APIs that transfer larger amounts of data, but rely on fewer API requests can have that data transfer throttled on a per byte basis. For example, an API that is data intensive, will return a large amount of data in response to each API request. The API may only receive a request a few hundreds of times a day, but each request may result in several megabytes of data being transferred. Let’s say that we want to limit the amount of data transferred to 6GB per hour. For this type of API, we could set a rate limiting policy to allow for one request per minute, and then augment that policy with a transfer quota policy of 100Mb per hour.

Each of these policies, if used singly, can be effective in throttling requests. Apiman, however, adds a layer of flexibility to your use of these policy types by enabling you to use them in combinations.

Apiman supports these types of limiting policies:

Apiman supports these types of modification policies:

Apiman supports these types of other policies:

This policy enables fine grained authorization to API resources based on authenticated user roles. This policy can be used to control precisely who (authenticated users) are allowed to access the API, at an arbitrarily fine-grained level.

The configuration of this policy consists of a number of rules that are applied to any inbound request to the API. Each rule consists of a regular expression pattern, an HTTP verb, and the role that an authenticated user must possess in order for access to be granted.

This policy enables HTTP BASIC Authentication on an API. In other words, you can use this policy to require clients to provide HTTP BASIC authentication credentials when making requests to the managed API.

The BASIC Authentication policy has a number of configuration options. There are several top level configuration properties:

Additionally, one of the following complex properties must be included in the configuration, indicating whether Apiman should use JDBC, LDAP, or Static (not recommended for production) information as the source of identity used to validate provided user credentials.

Here is an example of the JSON configuration you might use when configuring a BASIC Authentication policy that uses LDAP to validate the inbound credentials:

Here is an example of the JSON configuration you might use when configuring a BASIC Authentication policy that uses JDBC to validate the inbound credentials:

This policy is deprecated. Use Caching Resources Policy instead.

Allows caching of API responses in the Gateway to reduce overall traffic to the back-end API. The Resource Caching Policy can cache requests based on their URL path, http method and specific status code.

The configuration parameters for an Caching Resources Policy are:

A policy implementing CORS (Cross-origin resource sharing): a method of defining access to resources outside the originating domain. It is principally a security mechanism to prevent the loading of resources from unexpected domains, for instance via XSS injection attacks.

For further references, see CORS W3C Recommendation 16 January 2014 and MDN’s articles.

The configuration options available, are:

Security-related HTTP headers can be set, such as HSTS, CSP and XSS protection.

The ignored resources policy type enables you to shield some of an API’s resources from being accessed, without blocking access to all the API’s resources. Requests made to access to API resources designated as “ignored” result in an HTTP 404 (“not found”) error code. By defining ignored resource policies, Apiman enables you to have fine-grained control over which of an API’s resources are accessible.

For example, let’s say that you have an Apiman managed API that provides information to remote staff. The REST resources provided by this API are structured as follows:

/customers /customers/{customer id}/orders /customers/{customer id}/orders/bad_debts

By setting up multiple ignored resource policies, these policies can work together to give you more flexibility in how you govern access to to your API’s resources. What you do is to define multiple plans, and in each plan, allow differing levels of access, based on the paths (expressed as regular expressions)defined, for resources to be ignored. To illustrate, using the above examples:

What happens when the policy is applied to an API request is that the Apiman Gateway matches the configured paths to the requested API resources. If any of the exclusion paths match, the policy triggers a failure with an HTTP return code of 404.

The IP-related policy types are less fine-grained in that they allow or block access to all of an API’s resources based on the IP address of the client application. We’ll look at these policy types next.

The configuration parameters for an Ignored Resources Policy are:

As its name indicates, the IP blacklist policy type blocks access to an API’s resources based on the IP address of the client application. The Apiman Management UI form used to create an IP blacklist policy enables you to use wildcard characters in specifying the IP addresses to be blocked. In addition, Apiman gives you the option of specifying the return error code sent in the response to the client if a request is denied. Note that an IP Blacklist policy in a plan overrides an IP Whitelist policy.

The configuration parameters for an IP Blacklist Policy are:

The IP Whitelist Policy Type is the counterpart to the IP Blacklist Policy type. In the IP Whitelist policy, only inbound API requests from Client Apps, policies, or APIs that satisfy the policy are accepted.

The IP Blacklist and IP Whitelist policies are complementary, but different, approaches to limiting access to an API:

The configuration parameters for an IP Whitelist Policy are:

This policy turns a standard REST endpoint into a JSONP compatible endpoint. For example, a REST endpoint may typically return the following JSON data:

If the JSONP policy is applied to this API, then the caller must provide a JSONP callback function name via the URL (for details on this, see the Configuration section below). When this is done, the API might respond with this instead:

The JSONP policy has a single configuration property, which can be used to specify the name of the HTTP query parameter that the caller must use to pass the name of the JSONP callback function.

If the above configuration were to be used, the API client (caller) must send the JSONP callback function name in the URL of the request as a query parameter named callback. For example:

In this example, the response might look like this:

The JWT Policy helps you to validate JWT Tokens by providing a signing key and also via JSON Web Key Set (JWK(S)). You can also require claims and strip them to forward them as header to the backend API.

A Keycloak-specific OAuth2 policy to regulate access to APIs. This plugin enables a wide range of sophisticated auth facilities in combination with, for instance, Keycloak’s federation, brokering and user management capabilities. An exploration of the basics can be found in our blog, but we encourage users to explore the project documentation, as there is a tremendous depth and breadth of functionality, most of which works extremely well with Apiman.

Keycloak’s token format and auth mechanism facilitate excellent performance characteristics, with users able to easily tune the setup to meet their security requirements. In general, this is one of the best approaches for achieving security without greatly impacting performance.

A policy that logs the headers to standard out. Useful to analyse inbound HTTP traffic to the gateway when added as the first policy in the chain or to analyse outbound HTTP traffic from the gateway when added as the last policy in the chain.

The Log Policy can be configured to output the request headers, the response headers, or both. When configuring this policy via the Apiman REST API, there is only property:

The Quota Policy type performs the same basic functionality as the Rate Limiting policy type, however, the intended use of this policy type is for less fine grained processing (e.g., 10,000 requests per month).

The configuration parameters for a Quota Policy are:

The Rate Limiting Policy type governs the number of times requests are made to an API within a specified time period. The requests can be filtered by user, application, or API and can set the level of granularity for the time period to second, minute, hour, day, month, or year. The intended use of this policy type is for fine grained processing (e.g., 10 requests per second).

The configuration parameters for a Rate Limiting Policy are:

Set and remove headers on request, response or both. The values can be literal strings, environment, system properties or request headers. Headers can be removed by simple string equality or regular expression.

This policy is nearly identical to our Authorization Policy, with the exception that it accepts a SOAPAction in the HTTP header. Please note that this policy will only accept a single SOAPAction header, and will not extract the operation name from the SOAP body.

Just as with the Authorization policy, you can define any number of rules you’d like.

This policy is used to only allow access to an API during certain times. In fact, the policy can be configured to apply different time restrictions to different API resources (matched via regular expressions). This allows you to control when client and users are allowed to access your API.

The configuration parameters for a Time Restricted Access Policy are:

In contrast to the other policy types, Transfer Quota tracks the number of bytes transferred (either uploaded or downloaded) rather than the total number of requests made.

The configuration parameters for a Quota Policy are:

This policy converts an API format between JSON and XML. If an API is implemented to return XML, but a client would prefer to receive JSON data, this policy can be used to automatically convert both the request and response bodies. In this way, the client can work with JSON data even though the back-end API requires XML (and responds with XML).

Note that this policy is very generic, and does an automatic conversion between XML and JSON. For more control over the specifics of the format conversion, a custom policy may be a better choice.

The configuration of this policy consists of two properties which indicate:

From these two properties, the policy can decide how (and if) to convert the data.

This policy is used to re-write responses from the back-end API such that they will be modified by fixing up any incorrect URLs found with modified ones. This is useful because Apiman works through an API Gateway, and in some cases an API might return URLs to followup action or data endpoints. In these cases the back-end API will likely be configured to return a URL pointing to the unmanaged API endpoint. This policy can fix up those URL references so that they point to the managed API endpoint (the API Gateway endpoint) instead.

This policy requires some basic configuration, including a regular expression used to match the URL, as well as a replacement value.

This policy allows users to explicitly allow only certain API subpaths to be accessed. It’s particularly useful when only a small subset of resources from a back-end API should be exposed through the managed endpoint.

Configuration of the URL Whitelist Policy consists of a property to control the stripping of the managed endpoint prefix, and then a list of items representing the endpoint paths that are allowed.