resource-filtering.md

description
This page provides the technical details of the Resource Filtering policy

Resource Filtering

Overview

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 only.

A typical usage would be to allow access to all paths (/**) but in read-only mode (GET method).

Functional and implementation information for the resource-filtering policy is organized into the following sections:

• Examples
• Configuration
• Compatibility Matrix
• Errors
• Changelogs

Examples

{% hint style="warning" %} This policy can be applied to v2 APIs and v4 proxy APIs. It cannot be applied to v4 message APIs. {% endhint %}

{% tabs %} {% tab title="Proxy API example" %} Sample policy configuration:

"resource-filtering" : {
    "whitelist":[
        {
            "pattern":"/**",
            "methods": ["GET"]
        }
    ]
}

{% endtab %} {% endtabs %}

Configuration

The implementation of the resource-filtering policy supports Ant-style path patterns, where URL mapping matches URLs using the following rules:

• ? matches one character
• * matches zero or more characters
• ** matches zero or more directories in a path

Phases

The phases checked below are supported by the resource-filtering policy:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	true
onResponse	false	onResponse	false
onRequestContent	false	onMessageRequest	false
onResponseContent	false	onMessageResponse	false

Options

The resource-filtering policy can be configured with the following options:

Property	Required	Description	Type	Default
whitelist	false	List of allowed resources	array of resources	-
blacklist	false	List of restricted resources	array of resources	-

{% hint style="info" %} You can’t apply whitelisting and blacklisting to the same resource. Whitelisting takes precedence over blacklisting. {% endhint %}

A resource is defined as follows:

Property	Required	Description	Type	Default
pattern	true	An Ant-style path pattern (Apache Ant).	string	-
methods	false	List of HTTP methods for which filter is applied.	array of HTTP methods	All HTTP methods

Compatibility matrix

The following is the compatibility matrix for APIM and the resource-filtering policy:

Plugin Version	Supported APIM versions
1.x	All

Errors

HTTP status code	Message
403	Access to the resource is forbidden according to resource-filtering rules
405	Method not allowed while accessing this resource

You can use the response template feature to override the default responses provided by the policy. These templates must be defined at the API level (see the API Console Response Templates option in the API Proxy menu).

The error keys sent by this policy are as follows:

Key	Parameters
RESOURCE_FILTERING_FORBIDDEN	path - method
RESOURCE_FILTERING_METHOD_NOT_ALLOWED	path - method

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-resource-filtering/blob/master/CHANGELOG.md" %}