Articles in this section

APIM Policy Reference Guide

Kathyana Queeman
Updated

Your policies are customizable rules or logic that the Gateway executes during an API transaction. Policies generally fall into security, transformation, performance, routing, or monitoring and testing categories. They are added to flows to enforce security, reliability, and proper data transfer. Examples of policies include traffic shaping, authentication/authorization, rate limiting, and dynamic routing. You can use dozens of policies; see the comprehensive list below. Learn more about the Policy Studio's features.

Policy_studio.png

Celigo's API Management offers two different packages: the Standard Plan and the Advanced Plan. Below is a list of all the policies available to Standard and Advanced Plan subscribers.

Warning

Some policies are only available when you use a v2 or v4 API definition. Learn more about API definitions.

Standard plan policies

Policy name

Description

v2 API definition supported

v4 API definition supported

API Key

You can use the api-key policy to enforce API key checks during request processing, allowing only apps with approved API keys to access your APIs. This policy ensures that API keys are valid, have not been revoked or expired, and are approved to consume the specific resources associated with your API.

✓

✓

Assign Attributes

You can use the assign-attributes policy to set variables such as request and execution context attributes. You can use it to retrieve initial request attributes after Transform headers or Transform query parameters policies and reuse them in other policies (Dynamic routing, RBAC, for example).

✓

✓

Assign Content

You can use the assign-content policy to change or transform the request or response body's content. This policy is compatible with the Freemarker template engine, which allows you to apply complex transformations, such as transforming from XML to JSON and vice versa. You can access multiple objects from the template context by default — request and response bodies, dictionaries, context attributes, and more.

✓

✓

Basic Authentication

You can use the basic-authentication policy to manage basic authentication headers sent in API calls. The policy compares the user and password sent in the basic authentication header to an APIM user to determine if the user credentials are valid.

To use the policy in an API, you need to configure:

  • an LDAP, inline, or HTTP resource for your API plan, which specifies where the APIM users are stored

  • a basic authentication policy for the API flows

✓

✓

Cache

You can use the cache policy to cache upstream responses (content, status, and headers) to eliminate the need for subsequent calls to the back end. This policy is based on a cache resource, which aligns the underlying cache system with the API lifecycle (stop/start). Consumers can bypass the cache by adding a cache=BY_PASS_ query parameter or providing an X-Gravitee-Cache=BY_PASS HTTP header.

✓

✓

Dynamic Routing

The dynamic-routing policy dispatches inbound calls to different targets/endpoints or rewrites URIs.This policy is particularly useful for creating API Mashups.

✓

✓

Generate HTTP Signature

HTTP Signature is an authentication method that adds a new level of security. Use this policy to generate an HTTP Signature with a set of headers, a max validity duration, and some other settings. The "Signature" authentication scheme is based on the model that the client must authenticate itself with a digital signature produced by either a private asymmetric key (e.g., RSA) or a shared symmetric key (e.g., HMAC).

✓

✓

Generate JWT

You use the generate-JWT policy to generate a signed JWT with a configurable set of claims. This JWT can subsequently be forwarded to backend targets or used in another way. When a signed JWT is generated, it is put in the jwt.generated attribute of the request execution context. This is useful when, say, your front-end app uses only the API key and the back-end service uses JWT.

✓

✓

GeoIP Filtering

You can use the geoip-filtering policy to control access to your API by filtering IP addresses. You can allow IPs by country or distance.

✓

✓

Groovy

You can use the Groovy policy to run Groovy scripts at any stage of request processing through the gateway.

✓

✓

HTML to JSON

You use the html-json transformation policy to transform the response content. This policy is based on the jsoup HTML parser. In APIM, you only need to provide your JSON field names with the associated selectors.

✓

✓

HTTP Callout

You can use the callout-http policy to invoke an HTTP(S) URL and place a subset or all of the content in one or more variables of the request execution context. This can be useful if you need data from an external service and want to inject it during request processing. The result of the callout is placed in a variable called calloutResponse and is only available during policy execution. If no variable is configured, the result of the callout is no longer available.

✓

✓

HTTP Signature

HTTP Signature is an authentication method that adds a new level of security. Under this policy, the consumer must send a signature using a secret key to temporarily identify the request and ensure that it's coming from the requesting consumer.

✓

✓

IP Filtering

You can use the IP-filtering policy to control access to your API by filtering IP addresses. With CIDR, you can allow or deny a specific IP address or range of IP addresses. Whitelist mode excludes all IP addresses except those included in the whitelist.

Blacklist mode allows all IP addresses except the addresses included in the blacklist. The blacklist takes precedence, so if an IP address is included in both lists, the policy rejects the request. You can specify a host to be resolved and checked against the remote IP.

✓

✓

JSON Threat Protection

You can use the json-threat-protection policy to validate a JSON request body by specifying limits for various JSON structures (such as arrays, field names, and string values). When an invalid request is detected (meaning the limit is reached), it will be considered a threat and rejected with a 400 BAD REQUEST.

✓

✓

JSON to JSON

You can use thejson-to-json policy to apply a transformation (or mapping) on the request, response, and/or message content. This policy is based on the JOLT library.

✓

✓

JSON to XML

You can use the json-xml policy to transform JSON content to XML content.

✓

✓

JSON Validation

You can use the json-validation policy to validate JSON payloads. This policy uses the JSON Schema Validator. It returns 400 BAD REQUEST when the request validation fails and 500 INTERNAL ERROR when the response validation fails, with a custom error message body. It can inject processing report messages into request metrics for analytics.

✓

✓

JSON Web Signature

Before sending the API call to the target backend, you can use the jws-validator policy to validate the JWS token signature, certificate information, and expiration date.

✓

✓

JWT

You can use the JWT policy to validate the token signature and expiration date before sending the API call to the target backend.

✓

✓

Keyless

This security policy does not block requests as it considers them valid by default.

✓

✓

Latency

You can use the latency policy to add latency to the request or the response. For example, if you configure the policy on the request with a latency of 100ms, the gateway waits 100ms before routing the request to the backend service.

This policy is particularly useful in two scenarios:

  • Testing: adding latency allows you to test client applications when APIs respond slowly.

  • Monetization: a longer latency can be added to free plans to encourage clients to move to a better (or paid) plan.

✓

✓

Metrics Reporter

This policy allows you to push the request metrics to a custom endpoint. Running this policy ensures the complete response is sent to the initial consumer. You can configure the payload to send to the custom endpoint by using the Freemarker template engine.

✓

X

Mock

Mock policy:

✓

✓

OAS Validation

The oas-validation policy validates aspects of the request and response from an upstream server definition according to the embedded OpenAPI Specification. In the API manager, OAS files are not directly linked with the API definition, but you can use the specification as a resource in the API to define documentation and define flows and policies on the API.

Learn more about OAS in API Management.

X

✓

OAuth2

Using token introspection, you can use the oauth2 policy to check access token validity during request processing. If the access token is valid, the request is allowed to proceed. If not, the process stops and rejects the request. The access token must be supplied in the Authorization HTTP request header.

✓

✓

OpenID Connect UserInfo

Use the policy-openid-userinfo to get the OpenId Connect user info from an OAuth2 resource through its UserInfo endpoint.

✓

✓

Override HTTP Method

You can use the override-http-method policy to override the HTTP method provided by the initial consumer with a new configured value when the inbound request is sent to the backend API.

✓

✓

Rate Limiting

There are three rate-limit policies:

  • Quota: configures the number of requests allowed over some time (hours, days, weeks, months)

  • Rate-Limit: configures the number of requests allowed over a limited period (seconds, minutes)

  • Spike-Arrest: throttles the number of requests processed and sends them to the backend to avoid a spike

✓

✓

Regex Threat Protection

You can use the regex-threat-protection to extract information from a request (headers, path, query parameters, body payload) and evaluate that content against pre-defined regular expressions. If any content matches the specified regular expression, the request is considered a threat and rejected with a 400 BAD REQUEST. The policy injects processing report messages into request metrics for analytics.

✓

✓

Request Content Limit

You can use the request-content-limit policy to specify the maximum time allowed for request content. This limit is compared to the content length header of the request.

✓

✓

Resource Filtering

You can use the resource-filtering policy to filter REST resources. By applying this filter, you can restrict or allow access to a specific resource determined by a path and a method (or an array of methods).

This policy is mainly used in plan configuration to limit subscriber access to specific resources. A typical usage would be to allow access to all paths (/**) but in read-only mode (GET method).

✓

✓

REST to SOAP

You can use the rest-to-soap policy to expose the SOAP backend service as a REST API. The policy will pass the SOAP envelope message to the backend service as a POST request. SOAP envelopes support Expression Language to provide dynamic SOAP actions.

✓

✓

Retry

You can use the retry policy to replay requests when experiencing backend connection issues or if the response meets a given condition.

✓

✓

Role Based Access Control

You can use the role-based-access-control policy (RBAC policy) to control access to a resource by specifying the required roles to access it.

The policy can be configured to either:

  • allow only incoming requests with roles exactly matching the configured roles (strict mode)

  • allow incoming requests with at least one role matching the configured roles

✓

✓

SSL Enforcement

You can use the ssl-enforcement policy to filter incoming SSL requests. It allows you to restrict or allow access only to requests with client certificate authentication or only to a subset of valid clients.

✓

✓

Traffic Shadowing

Traffic shadowing allows you to copy traffic to another service asynchronously. This policy duplicates requests and sends them to the target, an endpoint defined at the API level. The request can be enriched with additional headers.

✓

X

Transform Headers

You can use the transformheaders policy to override HTTP headers in incoming requests or outbound responses. You can override the HTTP headers by:

  • Adding to or updating the list of headers

  • Removing headers individually

  • Defining a whitelist

✓

✓

Transform Query Parameters

You can use the transformqueryparams policy to override incoming HTTP request query parameters. You can override the HTTP query parameters by:

  • Clearing all existing query parameters

  • Adding to or updating the list of query parameters

  • Removing query parameters individually

✓

✓

URL Rewriting

You can use the url-rewriting policy to rewrite URLs from an HTTP response header or body.

✓

✓

Validate Request

You can use the request-validation policy to validate an incoming HTTP request according to defined rules. A rule is defined for an input value. This input value supports Expression Language expressions and is validated against constraint rules. For example, it can be used after OpenID Connect UserInfo policy to vaidate who is making the request.

To perform an advanced request validation, all you have to do is add the following code to the Field value in your API Management console:

  • For query params: {#request.params['<queryparam>'][0]}

  • For path params: {#request.paths[5]}

  • For body: {#jsonPath(#request.content, '$.<jsonparentnode>.<jsonchildnode>')}

✓

✓

XML to JSON

You can use the xml-json policy to transform XML content to JSON content.

✓

✓

XML Threat Protection

You can use the xml-threat-protection policy to validate an XML request body by limiting XML structures such as elements, entities, attributes and string values. When an invalid request is detected (meaning the limit is reached), the request will be considered a threat and rejected with a 400 BAD REQUEST.

✓

✓

XML validation

You can use the xml-validation policy to validate XML using an XSD schema. This policy uses javax.xml. When validation fails, a 400 BAD REQUEST error is received with a custom error message body. It also injects processing report messages into request metrics for analytics.

✓

✓

XSLT Transformation

If your backend exposes XML content, you can use the XSLT policy based on the Saxon library to apply an XSL transformation to an incoming XML request body or to the response body.

✓

✓

Advanced plan policies

All the standard plan policies are available to APIM Advanced plan subscribers, along with these advanced policies.

Policy name

Description

v2 API definition supported

v4 API definition supported

Assign Metrics

You can use the assign-metrics policy to push extra metrics in addition to the natively provided request metrics. These metrics can then be used from analytics dashboards to create custom widgets and, optionally, apply aggregations based on their value. This policy is also required for the API monetization use case, where it generates the billable system metrics used to associate usage data with specific plans or customers for reporting and invoicing.

✓

✓

Data Logging Masking

You can use the data-logging-masking policy to configure rules to conceal sensitive data. You can use JSON-path, XML-path, or a regular expression to identify the information to hide.

✓

X