Nav

Using Policies

A policy is a mechanism for enforcing filters on traffic. These filters generally control authentication, access, allotted consumption, and service level access (SLA). API Manager offers a number of pre-built policies, listed in "Available Policies". You can also build custom policies. You deploy a proxy API application and apply one or more policies to control how and when a received request is forwarded to its implementation endpoint. You can set an API alert to notify you when an API request violates a policy for SLA.

Client ID Enforcement

For example, you can apply the Client ID Enforcement policy to govern your API version at runtime. This policy allows only authorized applications to access the deployed API implementation. Each authorized application is configured with credentials: client_id and client_secret. At runtime, authorized applications provide the credentials with each request to the API implementation. Depending on the policy configuration, the application usually needs to provide credentials in one of these ways:

  • In the headers of the HTTP request

  • In the URL as query parameters

If the credentials are valid, the policy grants access to the deployed API implementation; otherwise, the policy denies access. Credentials are granted per version. If an application obtains credentials to access v1 of the API, the application cannot use the same credentials to access v2 of the API. The application needs to explicitly request access for v2 of the API even through the application credentials are the same as those for v1.

Suitable APIs for Applying Policies

You can apply policies to these types of APIs:

In Mule Runtime 3.8.0 and later, you can enhance security through policies by using Gatekeeper. Gatekeeper disables an API until all online policies are applied.

Prerequisites

Prerequisites for adding, removing, and applying policies are:

  • Roles

    Organization Administrators

    API Versions Owner

  • A declared endpoint for your API version

Use an HTTP endpoint instead of Jetty if you want to use rate-limited and throttling policies. Due to a limitation in the Jetty transport, rate-limiting and throttling policies do not work on an API that uses a Jetty inbound endpoint.

Registering Policies

Registration of the API in API Manager is a prerequisite for policy enforcement. After you apply policies in API Manager, download the policies to API Gateway runtime or Mule 3.8.0 or later runtime through the runtime Anypoint Platform agent. Policies are stored in each runtime /policies folder.

Each runtime is configured with the client id and client secret for the API Manager account. This defines the connection between the Anypoint Platform agent and the Anypoint Platform account.

Applying and Removing Policies

After declaring an endpoint for an API version, the following tabs on the API version details page become active: Applications, Policies, and SLA Tiers. You apply policies to an API version on the Policies tab as described in the procedure in this section. The Policies tab contains a list of out-of-the-box policies and any custom policies that your organization has added. Apply and Remove controls appear in the list.

using-policies-c7922

An unavailable Apply indicates one of the following conditions:

  • Another applied policy fulfills the requirement (see the Fulfills column).

  • Another policy must be applied first (see the Requires column).

To apply a policy to an endpoint:

  1. Click Policies to view the list of available policies for your organization. 

  2. Select individual policies to read their descriptions. When you find the one you want to apply, click Apply.

  3. Configure the policies. A number of configuration details are required to configure these policies:

To remove policies, click Remove. To reapply the policy, reconfigure the policy. Your previous configuration is not saved.

Disabling and Enabling Policies

To disable a policy, click Disable for the policy in the list of applied policies. Disabling preserves the state of the policy and data values, but stops enforcement of the policy. The Enable control appears for restarting enforcement.

Ordering Policies

You can set the order of execution of policies if you are using one of the following releases:

  • Studio 6.0 or later for creation, deployed to Anypoint Platform with auto-discovery

  • Mule 3.8 unified runtime or later

  • API Gateway Runtime 2.2.0 or later

Setting the Order of Execution of Policies

CORS, Throttling, and Rate Limiting policies, respectively, have the highest precedence. If you apply these policies, you cannot set other policies at a higher level. API Manager does not let you change the precedence of CORS, Throttling, and Rate Limiting for security reasons.

To set the order of execution of applied policies:

  1. Assuming you have signed in to the Anypoint Platform, click APIs.

  2. Click the version number of an API, the 1.0development version of the T-Shirt Ordering Service for example.

    APIadmin

  3. Click the Policies tab in lower part of API administration page.

    The list of any applied policies and available policies appears. The list includes RAML snippets for enforcing policies in RAML.

  4. At the top of the Applied policies list, Edit Policy Order to assign the priority.

    The Edit Policy Order button is available only when the API is actively managed by an API Gateway or Mule 3.8 unified runtime.

    api-click-policies

    The Reorder applied policies page appears.

    using-policies-28459
  5. Use the up and down arrows to rearrange the order of policies. For example, if you apply rate limiting, IP whitelist, and XML threat protection, you can reorder only the IP whitelist and XML threat protection policies because rate limiting takes precedence over the other policies.

  6. Click Apply order.

You can also set the order of execution of policies for a custom policy by configuring the policy tag or the before or after blocks.

Default Enforcement Order of Policies

A policy that you apply to an API version appears in the Applied policies list. The default order of the policy appears to the left of the policy name. The following table shows the default order of policies.

Order Policy

1

Cross-Origin Resource Sharing (CORS)

2

Rate Limiting, SLA-Based PingFederate

Rate Limiting, SLA-Based

Rate Limiting

Throttling -SLA-Based PingFederate

Throttling -SLA-Based

Throttling

3

IP Blacklist

IP Whitelist

4

HTTP Basic Authentication

5

OAuth 2.0 Access Token Enforcement Using External Provider Policy

OAuth 2.0 Access Token Enforcement

OpenAM Access Token Enforcement

PingFederate Access Token Enforcement

6

Client ID Enforcement

7

JSON Threat Protection

XML Threat Protection

Custom policies that don’t have an order configured are executed after out-of-the-box policies.

Logging of Policy Information

Logs show the order of policies:

INFO  2015-09-28 15:37:54,214 [[leagues-rest].httpListenerConfig.worker.01] org.mule.api.processor.LoggerMessageProcessor: POLICY A
INFO  2015-09-28 15:37:54,214 [[leagues-rest].httpListenerConfig.worker.01] org.mule.api.processor.LoggerMessageProcessor: POLICY B

When an Organization Owner defines the order of policy enforcement, conflicts can occur if existing API Owners have set policies on their APIs. The API Manager notifies both parties in the event of a conflict. An API Owner needs to update policies and resolve any conflicts.

Configuring the Policy Polling Time

The default policy polling time has been lengthened to 60 seconds as part of a global initiative to improve the performance and scalability of Anypoint Platform. MuleSoft based this change on careful examination of actual customer experiences. A minimum 60-second delay now occurs between the time you apply a policy from the UI and the time the policy goes into effect. The same delay occurs when you disable or edit a policy. You can [configure the length of the delay] using the following system property:

anypoint.platform.poll_policies_freq

Configure a new value in seconds by changing the wrapper.conf file. For example:

wrapper.java.additional.30=-Danypoint.platform.poll_policies_freq=45”

Configuring the APIkit Console for Policies

You can apply policies to both the API and the console, or to the API only.

The configuration of the console determines how the RAML-based, auto-generated proxy is configured, as described in "Working with the APIkit Console".

Legacy Support

API Manager now incorporates the API Gateway runtime functionality in the April 2016 release and earlier. The following table lists the policy template name and the supported API Gateway runtime in April 2016 and earlier releases.

Policy Supports Gateway

Client ID Enforcement

1 or later

Cross-Origin Resource Sharing

1.1 or later

HTTP Basic Authentication

1 or later

IP Blacklist

1 or later

IP Whitelist

1 or later

JSON Threat Protection

1 or later

LDAP Security Manager

1 or later

OAuth 2.0 Access Token Enforcement Using External Provider Policy

2 or later

OAuth 2.0 Access Token Enforcement (deprecated)

1 or later

OAuth 2.0 Provider (deprecated)

1 or later

OpenAM Access Token Enforcement

1.3.2 or later

PingFederate Access Token Enforcement

1 or later

Rate Limiting

1 or later

Rate Limiting, SLA-Based

1 or later

Simple Security Manager

1 or later

Throttling -SLA-Based

1 or later

Throttling

1 or later

XML Threat Protection

1 or later

If you use Anypoint Studio 5.x or earlier, you can upgrade Anypoint Gateway Runtime from within Studio. If you use Anypoint Studio 6.0 or later, the latest Anypoint Gateway Runtime for your Studio version is incorporated and there is no need to upgrade.