Chapter 4. APIcast policies

APIcast policies are units of functionality that modify how APIcast operates. Policies can be enabled, disabled, and configured to control how they modify APIcast. Use standard policies provided by Red Hat 3scale.

The following topics provide information about the standard APIcast policies, creating your own custom APIcast policies, and creating a policy chain.

Control policies for a service with a policy chain. Policy chains do the following:

  • specify what policies APIcast uses
  • provide configuration information for policies 3scale uses
  • specify the order in which 3scale loads policies

4.1. APIcast standard policies

3scale provides the following standard policies:

You can enable and configure standard policies in 3scale.

4.1.1. 3scale Auth Caching

The 3scale Auth Caching policy caches authentication calls made to APIcast. You can select an operating mode to configure the cache operations.

3scale Auth Caching is available in the following modes:

1. Strict - Cache only authorized calls.

"Strict" mode only caches authorized calls. If a policy is running under the "strict" mode and if a call fails or is denied, the policy invalidates the cache entry. If the backend becomes unreachable, all cached calls are rejected, regardless of their cached status.

2. Resilient – Authorize according to last request when backend is down.

The "Resilient" mode caches both authorized and denied calls. If the policy is running under the "resilient" mode, failed calls do not invalidate an existing cache entry. If the backend becomes unreachable, calls hitting the cache continue to be authorized or denied based on their cached status.

3. Allow - When backend is down, allow everything unless seen before and denied.

The "Allow" mode caches both authorized and denied calls. If the policy is running under the "allow" mode, cached calls continue to be denied or allowed based on the cached status. However, any new calls are cached as authorized.

Important

Operating in the "allow" mode has security implications. Consider these implications and exercise caution when using the "allow" mode.

4. None - Disable caching.

The "None" mode disables caching. This mode is useful if you want the policy to remain active, but do not want to use caching.

Configuration properties

propertydescriptionvaluesrequired?

caching_type

The caching_type property allows you to define which mode the cache will operate in.

data type: enumerated string [resilient, strict, allow, none]

yes

Policy object example

{
  "name": "caching",
  "version": "builtin",
  "configuration": {
    "caching_type": "allow"
  }
}

For information on how to configure policies, see the Creating a policy chain section of the documentation.

4.1.2. 3scale Referrer

The 3scale Referrer policy enables the Referrer Filtering feature. When the policy is enabled in the service policy chain, APIcast sends the value of the 3scale Referrer policy to the Service Management API as an upwards AuthRep call. The value of the 3scale Referrer policy is sent in the referrer parameter in the call.

For more information on how Referrer Filtering works, see the Referrer Filtering section under Authentication Patterns.

4.1.3. Anonymous Access

The Anonymous Access policy exposes a service without authentication. It can be useful, for example, for legacy applications that cannot be adapted to send the authentication parameters. The Anonymous policy only supports services with API Key and App Id / App Key authentication options. When the policy is enabled for API requests that do not have any credentials provided, APIcast will authorize the calls using the default credentials configured in the policy. For the API calls to be authorized, the application with the configured credentials must exist and be active.

Using the Application Plans, you can configure the rate limits on the application used for the default credentials.

Note

You need to place the Anonymous Access policy before the APIcast Policy, when using these two policies together in the policy chain.

Following are the required configuration properties for the policy:

  • auth_type: Select a value from one of the alternatives below and make sure the property corresponds to the authentication option configured for the API:

    • app_id_and_app_key: For App ID / App Key authentication option.
    • user_key: For API key authentication option.
  • app_id (only for app_id_and_app_key auth type): The App Id of the application that will be used for authorization if no credentials are provided with the API call.
  • app_key (only for app_id_and_app_key auth type): The App Key of the application that will be used for authorization if no credentials are provided with the API call.
  • user_key (only for the user_key auth_type): The API Key of the application that will be used for authorization if no credentials are provided with the API call.

Figure 4.1. Anonymous Access policy

Anonymous Access policy

4.1.4. Camel Service

You can use the Camel Service policy to define an HTTP proxy where the 3scale traffic is sent over the defined Apache Camel proxy. In this case, Camel works as a reverse HTTP proxy, where APIcast sends the traffic to Camel, and Camel then sends the traffic on to the API backend.

The following example shows the traffic flow:

Camel Service policy request flow

All APIcast traffic sent to the 3scale backend does not use the Camel proxy. This policy only applies to the Camel proxy and the communication between APIcast and API backend.

If you want to send all traffic through a proxy, you must use an HTTP_PROXY environment variable.

Note
  • The Camel Service policy disables all load-balancing policies, and traffic is sent to the Camel proxy.
  • If the HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY parameters are defined, this policy overwrites those values.
  • The proxy connection does not support authentication. You use the Header Modification policy for authentication.

4.1.4.1. Configuration

The following example shows the policy chain configuration:

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.camel",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8888/",
          "https_proxy": "https://192.168.15.103:8888/",
          "http_proxy": "https://192.168.15.103:8888/"
      }
    }
]

The all_proxy value is used if http_proxy or https_proxy is not defined.

4.1.4.1.1. Example use case

The Camel Service policy is designed to apply more fine-grained policies and transformation in 3scale using Apache Camel. This policy supports integration with Apache Camel over HTTP and HTTPS. For more details, see Chapter 5, Transforming 3scale message content using policy extensions in Fuse.

For details on a generic HTTP proxy policy, see Section 4.1.14, “Proxy Service”.

Example project

See the camel-netty-proxy example on GitHub. This project shows an HTTP proxy that transforms the response body from the API backend to uppercase.

4.1.5. CORS Request Handling

The Cross Origin Resource Sharing (CORS) Request Handling policy allows you to control CORS behavior by allowing you to specify:

  • Allowed headers
  • Allowed methods
  • Allowed credentials
  • Allowed origin headers

The CORS Request Handling policy will block all unspecified CORS requests.

Note

You need to place the CORS Request Handling policy before the APIcast Policy, when using these two policies together in the policy chain.

Configuration properties

propertydescriptionvaluesrequired?

allow_headers

The allow_headers property is an array in which you can specify which CORS headers APIcast will allow.

data type: array of strings, must be a CORS header

no

allow_methods

The allow_methods property is an array in which you can specify which CORS methods APIcast will allow.

data type: array of enumerated strings [GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS, TRACE, CONNECT]

no

allow_origin

The allow_origin property allows you to specify an origin domain APIcast will allow

data type: string

no

allow_credentials

The allow_credentials property allows you to specify whether APIcast will allow a CORS request with credentials

data type: boolean

no

Policy object example

{
  "name": "cors",
  "version": "builtin",
  "configuration": {
    "allow_headers": [
      "App-Id", "App-Key",
      "Content-Type", "Accept"
    ],
    "allow_credentials": true,
    "allow_methods": [
      "GET", "POST"
    ],
    "allow_origin": "https://example.com"
  }
}

For information on how to configure policies, see the Creating a policy chain in 3scale section of the documentation.

4.1.6. Custom metrics

The Custom metrics policy adds the availability to add metrics after the response sent by the upstream API. The main use case for this policy is to add metrics based on response code status, headers, or different NGINX variables.

4.1.6.1. Limitations of custom metrics

  • When authentication happens before the request is sent to the upstream API, a second call to the back end will be made to report the new metrics to the upstream API.
  • This policy does not work with batching policy.
  • Metrics need to be created in the Admin Portal before the policy will push the metric values.

4.1.6.2. Examples for request flows

The following chart shows the request flow example of when authentication is not cached, as well as the flow when authentication is cached.

Custom metrics request flows

4.1.6.3. Configuration examples

This policy increments the metric error by the header increment if the upstream API returns a 400 status:

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "error",
        "increment": "{{ resp.headers['increment'] }}",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "400",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

This policy increments the hits metric with the status_code information if the upstream API return a 200 status:

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "hits_{{status}}",
        "increment": "1",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "200",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

4.1.7. Echo

The Echo policy prints an incoming request back to the client, along with an optional HTTP status code.

Configuration properties

propertydescriptionvaluesrequired?

status

The HTTP status code the Echo policy will return to the client

data type: integer

no

exit

Specifies which exit mode the Echo policy will use. The request exit mode stops the incoming request from being processed. The set exit mode skips the rewrite phase.

data type: enumerated string [request, set]

yes

Policy object example

{
  "name": "echo",
  "version": "builtin",
  "configuration": {
    "status": 404,
    "exit": "request"
  }
}

For information on how to configure policies, see the Creating a policy chain in 3scale section of the documentation.

4.1.8. Header Modification

The Header Modification policy allows you to modify the existing headers or define additional headers to add to or remove from an incoming request or response. You can modify both response and request headers.

The Header Modification policy supports the following configuration parameters:

  • request: List of operations to apply to the request headers
  • response: List of operations to apply to the response headers

Each operation consists of the following parameters:

  • op: Specifies the operation to be applied. The add operation adds a value to an existing header. The set operation creates a header and value, and will overwrite an existing header’s value if one already exists. The push operation creates a header and value, but will not overwrite an existing header’s value if one already exists. Instead, push will add the value to the existing header. The delete operation removes the header.
  • header: Specifies the header to be created or modified and can be any string that can be used as a header name (e.g. Custom-Header).
  • value_type: Defines how the header value will be evaluated and can either be plain for plain text or liquid for evaluation as a Liquid template. For more information, see Section 4.7, “Using variables and filters in policies”.
  • value: Specifies the value that will be used for the header. For value type "liquid" the value should be in the format {{ variable_from_context }}. Not needed when deleting.

Policy object example

{
  "name": "headers",
  "version": "builtin",
  "configuration": {
    "response": [
      {
        "op": "add",
        "header": "Custom-Header",
        "value_type": "plain",
        "value": "any-value"
      }
    ],
    "request": [
      {
        "op": "set",
        "header": "Authorization",
        "value_type": "plain",
        "value": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
      },
      {
        "op": "set",
        "header": "Service-ID",
        "value_type": "liquid",
        "value": "{{service.id}}"
      }
    ]
  }
}

For information on how to configure policies, see the Creating a policy chain in 3scale section of the documentation.

4.1.9. IP Check

The IP Check policy is used to deny or allow requests based on a list of IPs.

Configuration properties

propertydescriptiondata typerequired?

check_type

The check_type property has two possible values, whitelist or blacklist. blacklist will deny all requests from IPs on the list. whitelist will deny all requests from IPs not on the list.

string, must be either whitelist or blacklist

yes

ips

The ips property allows you to specify a list of IP addresses to whitelist or blacklist. Both single IPs and CIDR ranges can be used.

array of strings, must be valid IP addresses

yes

error_msg

The error_msg property allows you to configure the error message returned when a request is denied.

string

no

client_ip_sources

The client_ip_sources property allows you to configure how to retrieve the client IP. By default, the last caller IP is used. The other options are X-Forwarded-For and X-Real-IP.

array of strings, valid options are one or more of X-Forwarded-For, X-Real-IP, last_caller.

no

Policy object example

{
  "name": "ip_check",
  "configuration": {
    "ips": [ "3.4.5.6", "1.2.3.0/4" ],
    "check_type": "blacklist",
    "client_ip_sources": ["X-Forwarded-For", "X-Real-IP", "last_caller"],
    "error_msg": "A custom error message"
  }
}

For information on how to configure policies, see the Creating a policy chain in 3scale section of the documentation.

4.1.10. JWT Claim Check

Based on JSON Web Token (JWT) claims, the JWT Claim Check policy allows you to define new rules to block resource targets and methods.

4.1.10.1. About JWT Claim Check policy

In order to route based on the value of a JWT claim, you need a policy in the chain that validates the JWT and stores the claim in the context that the policies share.

If the JWT Claim Check policy is blocking a resource and a method, the policy also validates the JWT operations. Alternatively, in case that the method resource does not match, the request continues to the backend API.

Example: In case of a GET request, the JWT needs to have the role claim as admin, if not the request will be denied. On the other hand, any non GET request will not validate the JWT operations, so POST resource is allowed without JWT constraint.

{
  "name": "apicast.policy.jwt_claim_check",
  "configuration": {
      "error_message": "Invalid JWT check",
      "rules": [
          {
              "operations": [
                  {"op": "==", "jwt_claim": "role", "jwt_claim_type": "plain", "value": "admin"}
              ],
              "combine_op":"and",
              "methods": ["GET"],
              "resource": "/resource",
              "resource_type": "plain"
          }
      ]
  }
}

4.1.10.2. Configuring JWT Claim Check policy in your policy chain

To configure the JWT Claim Check policy in your policy chain, do the following:

Prerequisites:

  • You need to have access to a 3scale installation.
  • You need to wait for all the deployments to finish.
4.1.10.2.1. Configuring the policy
  1. To add the JWT Claim Check policy to your API, follow the steps described in Enabling a standard Policy and choose JWT Claim Check.
  2. Click the JWT Claim Check link.
  3. To enable the policy, select the Enabled checkbox.
  4. To add rules, click the plus + icon.
  5. Specify the resource_type.
  6. Choose the operator.
  7. Indicate the resource controlled by the rule.
  8. To add the allowed methods, click the plus + icon.
  9. Type the error message to show to the user when traffic is blocked.
  10. When you have finished setting up your API with JWT Claim Check, click Update Policy.

    • You can add more resource types and allowed methods by clicking the plus + icon in the corresponding section.
  11. Click Update & test in Staging Environment to save your changes.

4.1.11. Liquid Context Debug

Note

The Liquid Context Debug policy is meant only for debugging purposes in the development environment and not in production.

This policy responds to the API request with a JSON, containing the objects and values that are available in the context and can be used for evaluating Liquid templates. When combined with the 3scale APIcast or upstream policy, Liquid Context Debug must be placed before them in the policy chain in order to work correctly. To avoid circular references, the policy only includes duplicated objects once and replaces them with a stub value.

An example of the value returned by APIcast when the policy is enabled:

    {
      "jwt": {
        "azp": "972f7b4f",
        "iat": 1537538097,
        ...
        "exp": 1537574096,
        "typ": "Bearer"
      },
      "credentials": {
        "app_id": "972f7b4f"
      },
      "usage": {
        "deltas": {
          "hits": 1
        },
        "metrics": [
          "hits"
        ]
      },
      "service": {
        "id": "2",
        ...
      }
      ...
    }

4.1.12. Maintenance Mode

The Maintenance Mode policy allows you reject incoming requests with a specified status code and message. It is useful for maintenance periods or to temporarily block an API.

Configuration properties

The following is a list of possible properties and default values.

propertyvaluedefaultdescription

status

integer, optional

503

Response code

message

string, optional

503 Service Unavailable - Maintenance

Response message

Maintenance Mode policy example

{
  "policy_chain": [
    {"name": "maintenance-mode", "version": "1.0.0",
    "configuration": {"message": "Be back soon..", "status": 503} },
  ]
}

For information on how to configure policies, see the Creating a policy chain in 3scale section of the documentation.

4.1.13. OAuth 2.0 Mutual TLS Client Authentication

This policy executes OAuth 2.0 Mutual TLS Client Authentication for every API call.

An example of the OAuth 2.0 Mutual TLS Client Authentication policy JSON is shown below:

{
  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
  "name": "OAuth 2.0 Mutual TLS Client Authentication",
  "summary": "Configure OAuth 2.0 Mutual TLS Client Authentication.",
  "description": ["This policy executes OAuth 2.0 Mutual TLS Client Authentication ",
    "(https://tools.ietf.org/html/draft-ietf-oauth-mtls-12) for every API call."
  ],
  "version": "builtin",
  "configuration": {
    "type": "object",
    "properties": { }
  }
}

4.1.14. Proxy Service

You can use the Proxy Service policy to define a generic HTTP proxy where the 3scale traffic will be sent using the defined proxy. In this case, the proxy service works as a reverse HTTP proxy, where APIcast sends the traffic to the HTTP proxy, and the proxy then sends the traffic on to the API backend.

The following example shows the traffic flow:

Proxy Service policy request flow

All APIcast traffic sent to the 3scale backend does not use the proxy. This policy only applies to the proxy and the communication between APIcast and API backend.

If you want to send all traffic through a proxy, you must use an HTTP_PROXY environment variable.

Note
  • The Proxy Service policy disables all load-balancing policies, and traffic is sent to the proxy.
  • If the HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY parameters are defined, this policy overwrites those values.
  • The proxy connection does not support authentication. You use the Header Modification policy for authentication.

4.1.14.1. Configuration

The following example shows the policy chain configuration:

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.http_proxy",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8888/",
          "https_proxy": "https://192.168.15.103:8888/",
          "http_proxy": "https://192.168.15.103:8888/"
      }
    }
]

The all_proxy value is used if http_proxy or https_proxy is not defined.

4.1.14.1.1. Example use case

The Proxy Service policy was designed to apply more fine-grained policies and transformation in 3scale using Apache Camel over HTTP. However, you can also use the Proxy Service policy as a generic HTTP proxy service. For integration with Apache Camel over HTTPS, see Section 4.1.4, “Camel Service”.

Example project

See the camel-netty-proxy example on GitHub. This project shows an HTTP proxy that transforms the response body from the API backend to uppercase.

4.1.15. Rate Limit Headers

The Rate Limit Headers policy adds RateLimit headers to response messages when your application subscribes to an application plan with rate limits. These headers provide useful information about the configured request quota limit and the remaining request quota and seconds in the current time window.

4.1.15.1. RateLimit headers

The following RateLimit headers are added to each message:

  • RateLimit-Limit: Displays the total request quota in the configured time window, for example, 10 requests.
  • RateLimit-Remaining: Displays the remaining request quota in the current time window, for example, 5 requests.
  • RateLimit-Reset: Displays the remaining seconds in the current time window, for example, 30 seconds. The behavior of this header is compatible with the delta-seconds notation of the Retry-After header.

By default, there are no rate limit headers in the response message when the Rate Limit Headers policy is not configured or when your application plan does not have any rate limits.

Note

If you are requesting an API metric with no rate limits but the parent metric has limits configured, the rate limit headers are still included in the response because the parent limits apply.

4.1.16. RH-SSO/Keycloak Role Check

This policy adds role check when used with the OpenID Connect authentication option. This policy verifies realm roles and client roles in the access token issued by Red Hat Single Sign-On (RH-SSO). The realm roles are specified when you want to add role check to every client resource of 3scale.

There are the two types of role checks that the type property specifies in the policy configuration:

  • whitelist (default): When whitelist is used, APIcast will check if the specified scopes are present in the JWT token and will reject the call if the JWT doesn’t have the scopes.
  • blacklist: When blacklist is used, APIcast will reject the calls if the JWT token contains the blacklisted scopes.

It is not possible to configure both checks – blacklist and whitelist in the same policy, but you can add more than one instance of the RH-SSO/Keycloak Role Check policy to the APIcast policy chain.

You can configure a list of scopes via the scopes property of the policy configuration.

Each scope object has the following properties:

  • resource: Resource (endpoint) controlled by the role. This is the same format as Mapping Rules. The pattern matches from the beginning of the string and to make an exact match you must append $ at the end.
  • resource_type: This defines how the resource value is evaluated.

    • As plain text (plain): Evaluates the resource value as plain text. Example: /api/v1/products$.
    • As Liquid text (liquid): Allows using Liquid in the resource value. Example: /resource_{{ jwt.aud }} manages access to the resource containing the Client ID.
  • methods: Use this parameter to list the allowed HTTP methods in APIcast, based on the user roles in RH-SSO. As examples, you can allow methods that have:

    • The role1 realm role to access /resource1. For those methods that do not have this realm role, you need to specify the blacklist.
    • The client1 role called role1 to access /resource1.
    • The role1 and role2 realm roles to access /resource1. Specify the roles in realm_roles. You can also indicate the scope for each role.
    • The client role called role1 of the application client, which is the recipient of the access token, to access /resource1. Use liquid client type to specify the JSON Web Token (JWT) information to the client.
    • The client role including the client ID of the application client, the recipient of the access token, to access /resource1. Use liquid client type to specify the JWT information to the name of the client role.
    • The client role called role1 to access the resource including the application client ID. Use liquid client type to specify the JWT information to the resource.
  • realm_roles: Use it to check the realm role (see the Realm Roles in Red Hat Single Sign-On documentation).

    The realm roles are present in the JWT issued by Red Hat Single Sign-On.

      "realm_access": {
        "roles": [
          "<realm_role_A>", "<realm_role_B>"
        ]
      }

    The real roles must be specified in the policy.

    "realm_roles": [
      { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" }
    ]

    Following are the available properties of each object in the realm_roles array:

  • name: Specifies the name of the role.
  • name_type: Defines how the name must be evaluated; it can be plain or liquid (works the same way as for the resource_type).
  • client_roles: Use client_roles to check for the particular access roles in the client namespace (see the Client Roles in Red Hat Single Sign-On documentation).

    The client roles are present in the JWT under the resource_access claim.

      "resource_access": {
        "<client_A>": {
          "roles": [
            "<client_role_A>", "<client_role_B>"
          ]
        },
        "<client_B>": {
          "roles": [
            "<client_role_A>", "<client_role_B>"
          ]
        }
      }

    Specify the client roles in the policy.

    "client_roles": [
      { "name": "<client_role_A>", "client": "<client_A>" },
      { "name": "<client_role_B>", "client": "<client_A>" },
      { "name": "<client_role_A>", "client": "<client_B>" },
      { "name": "<client_role_B>", "client": "<client_B>" }
    ]

    Following are the available properties of each object in the client_roles array:

  • name: Specifies the name of the role.
  • name_type: Defines how the name value must be evaluated; it can be plain or liquid (works the same way as for the resource_type).
  • client: Specifies the client of the role. When it is not defined, this policy uses the aud claim as the client.
  • client_type: Defines how the client value must be evaluated; it can be plain or liquid (works the same way as for the resource_type).

4.1.17. Routing

The Routing policy allows you to route requests to different target endpoints. You can define target endpoints and then you will be able to route incoming requests from the UI to those using regular expressions.

When combined with the APIcast policy, the Routing policy should be placed before the APIcast one in the chain, as the two policies that comes first will output content to the response. When the second gets a change to run its content phase, the request will already be sent to the client, so it will not output anything to the response.

4.1.17.1. Routing rules

  • If multiple rules exist, the Routing policy applies the first match. You can sort these rules.
  • If no rules match, the policy will not change the upstream and will use the defined Private Base URL defined in the service configuration.

4.1.17.2. Request path rule

This is a configuration that routes to http://example.com when the path is /accounts:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

4.1.17.3. Header rule

This is a configuration that routes to http://example.com when the value of the header Test-Header is 123:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

4.1.17.4. Query argument rule

This is a configuration that routes to http://example.com when the value of the query argument test_query_arg is 123:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "query_arg",
                "query_arg_name": "test_query_arg",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

4.1.17.5. JWT claim rule

To route based on the value of a JWT claim, there needs to be a policy in the chain that validates the JWT and stores it in the context that the policies share.

This is a configuration that routes to http://example.com when the value of the JWT claim test_claim is 123:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "jwt_claim",
                "jwt_claim_name": "test_claim",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

4.1.17.6. Multiple operations rule

Rules can have multiple operations and route to the given upstream only when all of them evaluate to true (using the 'and' combine_op), or when at least one of them evaluates to true (using the 'or' combine_op). The default value of combine_op is 'and'.

This is a configuration that routes to http://example.com when the path of the request is /accounts and when the value of the header Test-Header is 123:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "and",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

This is a configuration that routes to http://example.com when the path of the request is /accounts or when the value of the header Test-Header is 123:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "or",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

4.1.17.7. Combining rules

Rules can be combined. When there are several rules, the upstream selected is one of the first rules that evaluates to true.

This is a configuration with several rules:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/users"
              }
            ]
          }
        }
      ]
    }
  }

4.1.17.8. Catch-all rules

A rule without operations always matches. This can be useful to define catch-all rules.

This configuration routes the request to http://some_upstream.com if the path is /abc, routes the request to http://another_upstream.com if the path is /def, and finally, routes the request to http://default_upstream.com if none of the previous rules evaluated to true:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/abc"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/def"
              }
            ]
          }
        },
        {
          "url": "http://default_upstream.com",
          "condition": {
            "operations": []
          }
        }
      ]
    }
  }

4.1.17.9. Supported operations

The supported operations are ==, !=, and matches. The latter matches a string with a regular expression and it is implemented using ngx.re.match

This is a configuration that uses !=. It routes to http://example.com when the path is not /accounts:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "!=",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

4.1.17.10. Liquid templating

It is possible to use liquid templating for the values of the configuration. This allows you to define rules with dynamic values if a policy in the chain stores the key my_var in the context.

This is a configuration that uses that value to route the request:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "{{ my_var }}",
                "value_type": "liquid"
              }
            ]
          }
        }
      ]
    }
  }

4.1.17.11. Set the host used in the host_header

By default, when a request is routed, the policy sets the Host header using the host of the URL of the rule that matched. It is possible to specify a different host with the host_header attribute.

This is a configuration that specifies some_host.com as the host of the Host header:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "host_header": "some_host.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/"
              }
            ]
          }
        }
      ]
    }
  }

4.1.18. SOAP

The SOAP policy matches SOAP action URIs provided in the SOAPAction or Content-Type header of an HTTP request with mapping rules specified in the policy.

Configuration properties

propertydescriptionvaluesrequired?

pattern

The pattern property allows you to specify a string that APIcast will seek matches for in the SOAPAction URI.

data type: string

yes

metric_system_name

The metric_system_name property allows you to specify the 3scale backend metric with which your matched pattern will register a hit.

data type: string, must be a valid metric

yes

Policy object example

{
  "name": "soap",
  "version": "builtin",
  "configuration": {
    "mapping_rules": [
      {
        "pattern": "http://example.com/soap#request",
        "metric_system_name": "soap",
        "delta": 1
      }
    ]
  }
}

For information on how to configure policies, see the Creating a policy chain in 3scale section of the documentation.

4.1.19. TLS Client Certificate Validation

With the TLS Client Certificate Validation policy, APIcast implements a TLS handshake and validates the client certificate against a whitelist. A whitelist contains certificates signed by the Certified Authority (CA) or just plain client certificates. In case of an expired or invalid certificate, the request is rejected and no other policies will be processed.

The client connects to APIcast to send a request and provides a Client Certificate. APIcast verifies the authenticity of the provided certificate in the incoming request according to the policy configuration. APIcast can also be configured to use a client certificate of its own to use it when connecting to the upstream.

4.1.19.1. Setting up APIcast to work with TLS Client Certificate Validation

APIcast needs to be configured to terminate TLS. Follow the steps below to configure the validation of client certificates provided by users on APIcast with the Client Certificate Validation policy.

Prerequisites:

  • You need to have access to a 3scale installation.
  • You need to wait for all the deployments to finish.
4.1.19.1.1. Setting up APIcast to work with the policy

To set up APIcast and configure it to terminate TLS, follow these steps:

  1. You need to get the access token and deploy APIcast self-managed, as indicated in Deploying APIcast using the OpenShift template.

    Note

    APIcast self-managed deployment is required as the APIcast instance needs to be reconfigured to use some certificates for the whole gateway.

  2. For testing purposes only, you can use the lazy loader with no cache and staging environment and --param flags for the ease of testing

    oc new-app -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/master/apicast-gateway/apicast.yml --param CONFIGURATION_LOADER=lazy --param DEPLOYMENT_ENVIRONMENT=staging --param CONFIGURATION_CACHE=0
  3. Generate certificates for testing purposes. Alternatively, for production deployment, you can use the certificates provided by a Certificate Authority.
  4. Create a Secret with TLS certificates

    oc create secret tls apicast-tls
    --cert=ca/certs/server.crt
    --key=ca/keys/server.key
  5. Mount the Secret inside the APIcast deployment

    oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tls
  6. Configure APIcast to start listening on port 8443 for HTTPS

    oc set env dc/apicast APICAST_HTTPS_PORT=8443 APICAST_HTTPS_CERTIFICATE=/var/run/secrets/apicast/tls.crt APICAST_HTTPS_CERTIFICATE_KEY=/var/run/secrets/apicast/tls.key
  7. Expose 8443 on the Service

    oc patch service apicast -p '{"spec":{"ports":[{"name":"https","port":8443,"protocol":"TCP"}]}}'
  8. Delete the default route

    oc delete route api-apicast-staging
  9. Expose the apicast service as a route

    oc create route passthrough --service=apicast --port=https --hostname=api-3scale-apicast-staging.$WILDCARD_DOMAIN
    Note

    This step is needed for every API you are going to use and the domain changes for every API.

  10. Verify that the previously deployed gateway works and the configuration was saved, by specifying [Your_user_key] in the placeholder.

    curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN?user_key=[Your_user_key] -v --cacert ca/certs/ca.crt

4.1.19.2. Configuring TLS Client Certificate Validation in your policy chain

To configure TLS Client Certificate Validation in your policy chain, do the following:

Prerequisites

4.1.19.2.1. Configuring the policy
  1. To add the TLS Client Certificate Validation policy to your API, follow the steps described in Enabling a standard Policy and choose TLS Client Certificate Validation.
  2. Click the TLS Client Certificate Validation link.
  3. To enable the policy, select the Enabled checkbox.
  4. To add certificates to the whitelist, click the plus + icon.
  5. Specify the certificate including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
  6. When you have finished setting up your API with TLS Client Certificate Validation, click Update Policy.

Additionally:

  • You can add more certificates by clicking the plus + icon.
  • You can also reorganize the certificates by clicking the up and down arrows.

To save your changes, click Update & test in Staging Environment.

4.1.19.3. Verifying functionality of the TLS Client Certificate Validation policy

To verify the functionality of the TLS Client Certificate Validation policy, do the following:

Prerequisites:

4.1.19.3.1. Verifying policy functionality

You can verify the applied policy by specifying [Your_user_key] in the placeholder.

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/client.crt --key ca/keys/client.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/server.crt --key ca/keys/server.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt

4.1.19.4. Removing a certificate from the whitelist

To remove a certificate from the whitelist, do the following:

Prerequisites

4.1.19.4.1. Removing a certificate
  1. Click the TLS Client Certificate Validation link.
  2. To remove certificates from the whitelist, click the x icon.
  3. When you have finished removing the certificates, click Update Policy.

To save your changes, click Update & test in Staging Environment.

4.1.19.5. Reference material

For more information about working with certificates, you can refer to Red Hat Certificate System.

4.1.20. TLS Termination

This section provides information about the Transport Layer Security (TLS) Termination policy: concepts, configuration, verification and file removal from the policy.

With the TLS Termination policy, you can configure APIcast to finish TLS requests for each API without using a single certificate for all APIs. APIcast pulls the configuration setting before establishing a connection to the client; in this way, APIcast uses the certificates from the policy and makes the TLS terminate. This policy works with these sources:

  • Stored in the policy configuration.
  • Stored on the file system.

By default, this policy is not enabled in policy chains.

4.1.20.1. Configuring TLS Termination in your policy chain

This section describes the prerequisites and steps to configure the TLS Termination in your policy chain, with Privacy Enhanced Mail (PEM) formatted certificates.

Prerequisites

  • Certificate issued by user
  • A PEM-formatted server certificate
  • A PEM-formatted certificate private key
4.1.20.1.1. Configuring the policy
  1. To add the TLS Termination policy to your API, follow the steps described in Enabling a standard Policy and choose TLS Termination.
  2. Click the TLS Termination link.
  3. To enable the policy, select the Enabled checkbox.
  4. To add TLS certificates to the policy, click the plus + icon.
  5. Choose the source of your certificates:

    • Embedded certificate: Specify the path to the server certificate, and the path to the certificate private key.
    • Certificate from local file system: Browse the files for the certificate private key, and the server certificate.
  6. When you have finished setting up your API with TLS Termination, click Update Policy.

Additionally:

  • You can add more certificates by clicking the plus + icon.
  • You can also reorganize the certificates by clicking the up and down arrows.

To save your changes, click Update Policy Chain.

4.1.20.2. Verifying functionality of the TLS Termination policy

Prerequisites

4.1.20.2.1. Verifying policy functionality

You can test in the command line if the policy works with the following command:

curl “${public_URL}:${port}/?user_key=${user_key}" --cacert ${path_to_certificate}/ca.pem -v

where:

  • public_URL= The staging public base URL
  • port= The port number
  • user_key= The user key you want to authenticate with
  • path_to_certificate= The path to the CA certificate in your local file system

4.1.20.3. Removing files from TLS Termination

This section describes the steps to remove the certificate and key files from the TLS Termination policy.

Prerequisites

4.1.20.3.1. Removing a certificate
  1. Click the TLS Termination link.
  2. To remove certificates and keys, click the x icon.
  3. When you have finished removing the certificates, click Update Policy.

To save your changes, click Update Policy Chain.

4.1.21. Upstream

The Upstream policy allows you to parse the Host request header using regular expressions and replace the upstream URL defined in the Private Base URL with a different URL.

For Example:

A policy with a regex /foo, and URL field newexample.com would replace the URL https://www.example.com/foo/123/ with newexample.com

Policy chain reference:

propertydescriptionvaluesrequired?

regex

The regex property allows you to specify the regular expression that the Upstream policy will use when searching for a match with the request path.

data type: string, Must be a valid regular expression syntax

yes

url

Using the url property, you can specify the replacement URL in the event of a match. Note that the Upstream policy does not check whether or not this URL is valid.

data type: string, ensure this is a valid URL

yes

Policy object example

{
  "name": "upstream",
  "version": "builtin",
  "configuration": {
    "rules": [
      {
        "regex": "^/v1/.*",
        "url": "https://api-v1.example.com",

      }
    ]
  }
}

For information on how to configure policies, see the Creating a policy chain in 3scale section of the documentation.

4.1.22. Upstream Mutual TLS

With the Upstream Mutual TLS policy, you can establish mutual TLS connections between APIcast and upstream APIs based on the certificates set in the configuration. This policy supports multiple certificates for different upstream APIs.

4.1.22.1. Configuring Upstream Mutual TLS in your policy chain

This section describes the steps to configuring the Upstream Mutual TLS policy in your policy chain.

Prerequisites

  • You need to have access to a 3scale installation.

Procedure

  1. To add the Upstream Mutual TLS policy to your API, follow the steps described in Enabling a standard policy and choose Upstream Mutual TLS.
  2. Click the Upstream Mutual TLS link.
  3. To enable the policy, select the Enabled checkbox.
  4. Choose a Certificate type:

    • path: If you want to specify the path of a certificate, such as the one generated by OpenShift.
    • embedded: If you want to use a third-party generated certificate, by uploading it from your file system.
  5. In Certificate, specify the client certificate.
  6. Indicate the key in Certificate key.
  7. When you have finished setting up your API with Upstream Mutual TLS, click Update Policy Chain.

To promote your changes:

  1. Go to [Your_product] page > Integration > Configuration.
  2. Under APIcast Configuration, click Promote v# to Staging APIcast.

    • v# represents the version number of the configuration to be promoted.

4.1.23. URL Rewriting

The URL Rewriting policy allows you to modify the path of a request and the query string.

When combined with the 3scale APIcast policy, if the URL Rewriting policy is placed before the APIcast policy in the policy chain, the APIcast mapping rules will apply to the modified path. If the URL Rewriting policy is placed after APIcast in the policy chain, then the mapping rules will apply to the original path.

The policy supports the following two sets of operations:

  • commands: List of commands to be applied to rewrite the path of the request.
  • query_args_commands: List of commands to be applied to rewrite the query string of the request.

4.1.23.1. Commands for rewriting the path

Following are the configuration parameters that each command in the commands list consists of:

  • op: Operation to be applied. The options available are: sub and gsub. The sub operation replaces only the first occurrence of a match with your specified regular expression. The gsub operation replaces all occurrences of a match with your specified regular expression. See the documentation for the sub and gsub operations.
  • regex: Perl-compatible regular expression to be matched.
  • replace: Replacement string that is used in the event of a match.
  • options (optional): Options that define how the regex matching is performed. For information on available options, see the ngx.re.match section of the OpenResty Lua module project documentation.
  • break (optional): When set to true (checkbox enabled), if the command rewrote the URL, it will be the last one applied (all posterior commands in the list will be discarded).

4.1.23.2. Commands for rewriting the query string

Following are configuration parameters that each command in the query_args_commands list consists of:

  • op: Operation to be applied to the query arguments. The following options are available:

    • add: Add a value to an existing argument.
    • set: Create the arg when not set and replace its value when set.
    • push: Create the arg when not set and add the value when set.
    • delete: Delete an arg.
  • arg: The query argument name that the operation is applied on.
  • value: Specifies the value that is used for the query argument. For value type "liquid" the value should be in the format {{ variable_from_context }}. For the delete operation the value is not taken into account.
  • value_type (optional): Defines how the query argument value is evaluated and can either be plain for plain text or liquid for evaluation as a Liquid template. For more information, see Section 4.7, “Using variables and filters in policies”. If not specified, the type "plain" is used by default.

Example

The URL Rewriting policy is configured as follows:

{
  "name": "url_rewriting",
  "version": "builtin",
  "configuration": {
    "query_args_commands": [
      {
        "op": "add",
        "arg": "addarg",
        "value_type": "plain",
        "value": "addvalue"
      },
      {
        "op": "delete",
        "arg": "user_key",
        "value_type": "plain",
        "value": "any"
      },
      {
        "op": "push",
        "arg": "pusharg",
        "value_type": "plain",
        "value": "pushvalue"
      },
      {
        "op": "set",
        "arg": "setarg",
        "value_type": "plain",
        "value": "setvalue"
      }
    ],
    "commands": [
      {
        "op": "sub",
        "regex": "^/api/v\\d+/",
        "replace": "/internal/",
        "options": "i"
      }
    ]
  }

The original request URI that is sent to the APIcast:

https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original

The URI that APIcast sends to the API backend after applying the URL rewriting:

https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue

The following transformations are applied:

  1. The substring /api/v1/ matches the only path rewriting command and it is replaced by /internal/.
  2. user_key query argument is deleted.
  3. The value pushvalue is added as an additional value to the pusharg query argument.
  4. The value original of the query argument setarg is replaced with the configured value setvalue.
  5. The command add was not applied because the query argument addarg is not present in the original URL.

For information on how to configure policies, see the Creating a policy chain in 3scale section of the documentation.

4.1.24. URL Rewriting with Captures

The URL Rewriting with Captures policy is an alternative to the Section 4.1.23, “URL Rewriting” policy and allows rewriting the URL of the API request before passing it to the API backend.

The URL Rewriting with Captures policy retrieves arguments in the URL and uses their values in the rewritten URL.

The policy supports the transformations configuration parameter. It is a list of objects that describe which transformations are applied to the request URL. Each tranformation object consist of two properties:

  • match_rule: This rule is matched to the incoming request URL. It can contain named arguments in the {nameOfArgument} format; these arguments can be used in the rewritten URL. The URL is compared to match_rule as a regular expression. The value that matches named arguments must contain only the following characters (in PCRE regex notation): [\w-.~%!$&'()*,;=@:]. Other regex tokens can be used in the match_rule expression, such as ^ for the beginning of the string and $ for the end of the string.
  • template: The template for the URL that the original URL is rewritten with; it can use named arguments from the match_rule.

The query parameters of the original URL are merged with the query parameters specified in the template.

Example

The URL Rewriting with Captures policy is configured as follows:

{
  "name": "rewrite_url_captures",
  "version": "builtin",
  "configuration": {
    "transformations": [
      {
        "match_rule": "/api/v1/products/{productId}/details",
        "template": "/internal/products/details?id={productId}&extraparam=anyvalue"
      }
    ]
  }
}

The original request URI that is sent to the APIcast:

https://api.example.com/api/v1/products/123/details?user_key=abc123secret

The URI that APIcast sends to the API backend after applying the URL rewriting:

https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123

4.2. Enabling a policy in the Admin Portal

Perform the following steps to enable policies in the Admin Portal:

  1. Log in to 3scale.
  2. Navigate to the API service.
  3. From [your_API_name] > Integration > Configuration, select edit APIcast configuration.
  4. Under the POLICIES section, click add policy.
  5. Select the policy you want to add and fill out the required fields.
  6. Click the Update and test in Staging Environment button to save the policy chain.

4.3. Making custom policies available in the Admin Portal

Note

3scale hosted supports custom policies with APIcast self-managed only.

When APIcast is self-managed, you can push custom policy schemas to the Admin Portal using the apicast CLI to enable those policies to be used in policy chains.

The behavior for 3scale hosted with APIcast self-managed is as follows:

  • After creating custom policies and rebuilding the on-premises image, you can use the apicast push_policy command to make these policies available in the 3scale hosted Admin Portal for use in policy chains.
  • When you have pushed custom policies using the apicast push_policy command, these policies will be displayed in the Admin Portal when APIcast self-managed is selected.

4.3.1. Pushing custom policies to the Admin Portal

The apicast push_policy command enables you to push a custom policy manifest to the Admin Portal:

apicast push_policy <name> <version> <admin_portal_domain> <access_token>

The required arguments are as follows:

name

The name of the custom policy.

version

The version of the custom policy.

admin_portal_domain

The domain of your 3scale Admin Portal. For example, for 3scale hosted with APIcast self-managed, this is YOUR_ACCOUNT-admin.3scale.net.

access_token

The access token that you get from the Admin Portal.

For example:

$ bin/apicast push_policy my_custom_policy 1.0 my_account-admin.3scale.net XXXXXXXXXXXX...

4.3.2. Impact of adding or removing custom policies

When a custom policy is added, and APIcast is restarted, existing services will see this new policy in the list of available policies, and it can be used in any policy chain.

When a custom policy is removed from an image, and APIcast is restarted, the policy will no longer be available in the list, and you can no longer add it to a policy chain.

4.4. Creating custom APIcast policies

You can create custom APIcast policies entirely or modify the standard policies.

In order to create custom policies, you must understand the following:

  • Policies are written in Lua.
  • Policies must adhere to and be placed in the proper file directory.
  • Policy behavior is affected by how they are placed in a policy chain.
  • The interface to add custom policies is fully supported, but not the custom policies themselves.

4.5. Adding custom policies to APIcast

This document outlines details about adding custom policies to APIcast, considering different deployments.

4.5.1. Adding custom policies to the APIcast deployments

If you have created custom policies, you must add them to APIcast. How you do this depends on where APIcast is deployed:

  • You can add custom policies to the following APIcast self-managed deployments: APIcast on OpenShift and the Docker containerized environment.
  • You cannot add custom policies to APIcast hosted.
  • For 3scale Hosted (SaaS), custom policies are only possible with self-managed APIcast.
Warning

Never make policy changes directly onto a production gateway. Always test your changes.

4.5.2. Adding custom policies to the built-in APIcast

To add custom APIcast policies to an on-premises deployment, you must build an OpenShift image containing your custom policies and add it to your deployment. 3scale provides a sample repository you can use as a framework to create and add custom policies to an on-premises deployment.

This sample repository contains the correct directory structure for a custom policy, as well as a template which creates an image stream and BuildConfigs for building a new APIcast OpenShift image containing any custom policies you create.

Warning

When you build apicast-custom-policies, the build process pushes a new image to the amp-apicast:latest tag. When there is an image change on this image stream tag (:latest), both the apicast-staging and the apicast-production tags, by default, are configured to automatically start new deployment. To avoid any disruptions to your production service (or staging, if you prefer) it is recommended to disable automatic deployment ("Automatically start a new deployment when the image changes" checkbox), or configure a different image stream tag for production (e.g. amp-apicast:production).

Follow these steps to add a custom policy to an on-premises deployment:

  1. Fork the https://github.com/3scale/apicast-example-policy [public repository with the policy example] or create a private repository with its content. You need to have the code of your custom policy available in a Git repository for OpenShift to build the image. Note that in order to use a private Git repository, you must set up the secrets in OpenShift.
  2. Clone the repository locally, add the implementation for your policy, and push the changes to your Git repository.
  3. Update the openshift.yml template. Specifically, change the following parameters:

    1. spec.source.git.uri: https://github.com/3scale/apicast-example-policy.git in the policy BuildConfig – change it to your Git repository location.
    2. spec.source.images[0].paths.sourcePath: /opt/app-root/policies/example in the custom policies BuildConfig - change example to the name of the custom policy that you have added under the policies directory in the repository.
    3. Optionally, update the OpenShift object names and image tags. However, you must ensure that the changes are coherent (example: apicast-example-policy BuildConfig builds and pushes the apicast-policy:example image that is then used as a source by the apicast-custom-policies BuildConfig. So, the tag should be the same).
  4. Create the OpenShift objects by running the command:

    oc new-app -f openshift.yml --param AMP_RELEASE=2.8
  5. In case the builds do not start automatically, run the following two commands. In case you changed it, replace apicast-example-policy with your own BuildConfig name (e.g. apicast-<name>-policy). Wait for the first command to complete before you execute the second one.

    oc start-build apicast-example-policy
    oc start-build apicast-custom-policies

If the build-in APIcast images have a trigger on them tracking the changes in the amp-apicast:latest image stream, the new deployment for APIcast will start. After apicast-staging has restarted, go to the Integration page on the admin portal, and click the Add Policy button to see your custom policy listed. After selecting and configuring it, click Update & test in Staging Environment to make your custom policy work in the staging APIcast.

4.5.3. Adding custom policies to APIcast on another OpenShift Container Platform

You can add custom policies to APIcast on OpenShift Container Platform (OCP) by fetching APIcast images containing your custom policies from the Integrated OpenShift Container Platform registry.

Add custom policies to APIcast on another OpenShift Container Platform

  1. Add policies to APIcast built-in
  2. If you are not deploying your APIcast gateway on your primary OpenShift cluster, establish access to the internal registry on your primary OpenShift cluster.
  3. Download the 3scale 2-saas APIcast OpenShift template.
  4. To modify the template, replace the default image directory with the full image name in your internal registry.

    image: <registry>/<project>/amp-apicast:latest
  5. Deploying APIcast using the OpenShift template, specifying your customized image:

    oc new-app -f customizedApicast.yml
Note

When custom policies are added to APIcast and a new image is built, those policies are automatically displayed as available in the Admin Portal when APIcast is deployed with the image. Existing services can see this new policy in the list of available policies, so it can be used in any policy chain.

When a custom policy is removed from an image and APIcast is restarted, the policy will no longer be available in the list, so you can no longer add it to a policy chain.

4.6. Creating a policy chain in 3scale

Create a policy chain in 3scale as part of your APIcast gateway configuration. Follow these steps to modify the policy chain in the UI:

  1. Log in to your AMP
  2. Navigate to the API service

    navigate to APIcast integrations page
  3. From [your_API_name] > Integration > Configuration, select edit APIcast configuration

    navigate to APIcast configuration page
  4. Under the POLICIES section, use the arrow icons to reorder policies in the policy chain. Always place the APIcast policy last in the policy chain.

    policyChainOverview
  5. Click the Update and test in Staging Environment button to save the policy chain

4.7. Using variables and filters in policies

Some Section 4.1, “APIcast standard policies” support Liquid templating that allows using not only plain string values, but also variables that are present in the context of the request.

To use a context variable, wrap its name in {{ and }}, example: {{ uri }}. If the variable is an object, you can also access its attributes, for example: {{ somevar.attr }}.

Following are the standard variables that are available in all the policies:

  • uri: The path of the request with query parameters excluded from this path. The value of the embedded NGINX variable $uri.
  • host: The host of the request (the value of the embedded NGINX variable $host).
  • remote_addr: The IP address of the client (the value of the embedded NGINX variable $remote_addr).
  • headers: The object containing the request headers. Use {{headers['Some-Header']}} to get a specific header value.
  • http_method: The request method: GET, POST, etc.

These standard variables are used in the context of the request, but policies can add more variables to the context. A phase refers to all the execution steps that APIcast has. Variables can be used by all the policies in the policy chain, provided these cases:

  • Within the same phase, if the variable is added in the policy and then used in the following policy after the addition.
  • If a variable is added in a phase, this variable can be used in the next phases.

Following are some examples of variables that the standard 3scale APIcast policy adds to the context:

  • jwt: A parsed JSON payload of the JWT token (for OpenID Connect authentication).
  • credentials: An object that holds the application credentials. Example: "app_id": "972f7b4f", "user_key": "13b668c4d1e10eaebaa5144b4749713f".
  • service: An object that holds the configuration for the service that the current request is handled by. Example: the service ID would be available as {{ service.id }}.

For a full list of objects and values available in the context, see the Section 4.1.11, “Liquid Context Debug”).

The variables are used with the help of Liquid templates. Example: {{ remote_addr }}, {{ headers['Some-Header'] }}, {{ jwt.aud }}. The policies that support variables for the values have a special parameter, usually with the _type suffix (example: value_type, name_type, etc.) that accepts two values: "plain" for plain text and "liquid" for liquid template.

APIcast also supports Liquid filters that can be applied to the variables' values. The filters apply NGINX functions to the value of the Liquid variable.

The filters are placed within the variable output tag {{ }}, following the name of the variable or the literal value by a pipe character | and the name of the filter. Examples:

  • {{ 'username:password' | encode_base64 }}, where username:password is a variable.
  • {{ uri | escape_uri }}.

Some filters do not require parameters, so you can use an empty string instead of the variable. Example: {{ '' | utctime }} will return the current time in UTC time zone.

Filters can be chained as follows: {{ variable | function1 | function2 }}. Example: {{ '' | utctime | escape_uri }}.

Following is the list of the available functions: