Skip to content

Latest commit

 

History

History
236 lines (151 loc) · 13.6 KB

configure-general-proxy-settings.md

File metadata and controls

236 lines (151 loc) · 13.6 KB
Raw
description
This article focuses on how to configure the General Proxy settings for an API, which includes Entrypoints, CORS, Deployments, and Response Templates configurations.

Configure General Proxy Settings

Introduction

In Gravitee, there is a General subsection of the Proxy section. In the General section, you can configure the following settings per API:

  • Entrypoints
  • CORS
  • Deployments
  • Response Templates

This article walks through how to configure each of the above.

Configure Entrypoints

To configure Entrypoints, follow the below interactive tutorial, or, follow the numbered steps below.

{% @arcade/embed flowId="4353kgHZvdMRtEEL5xy9" url="https://app.arcade.software/share/4353kgHZvdMRtEEL5xy9" %}

If you prefer to use a written list of steps, follow these steps:

Log in to the Gravitee API Management Console. In the APIs menu, select the API for whom you want to configure Entrypoints.

Select the Edit API icon.

Find the Proxy section in the left-hand nav. Select General.

The Entrypoints tab is automatically selected.

Define your Context path. This is the URL location of your API. So if your URL is [https://apim-master-gateway.team-apim.gravitee.dev/myAPI], then [/myAPI] is the context path.

{% hint style="info" %} This is the path where your API is exposed. It must start with a '/' and can only contain any letter, capitalized letter, number, dash, or underscore. {% endhint %}

{% hint style="success" %} Select Save. You've now configured your Entrypoints. {% endhint %}

Configure CORS

CORS is a mechanism that allows resources on a web page to be requested from another domain. For background information on CORS, take a look at the CORS specification. This article will focus on how to configure CORS for your API.

To configure CORS for an API, follow these steps:

Log in to your Gravitee API Management Console. Select the APIs menu. Find the API for which you want to configure CORS.

Select the Edit API icon.

In the Proxy section, select General.

Select the CORS tab.

Toggle Enable CORS ON.

If you want to allow origins, enter * in the Allow Origins field. This will define the one or multiple origins that can access the resource.

{% hint style="danger" %} We do not recommend this configuration for production environments. By allowing cross-origin requests, a server may inadvertently expose sensitive information to unauthorized parties. For example, if a server includes sensitive data in a response that is accessible via CORS, an attacker could use a malicious website to extract that data. {% endhint %}

In the Access-Control-Allow-Methods field, define the method or methods allowed to access the resource. This is used in response to a preflight request.

In the Access-Control-Request-Headers drop down, define which headers will be allowed in your requests. Typically, your request header will include Access-Control-Request-Headers, which relies on the CORS configuration to allow its values.

If you want to allow the response to the request to be exposed when the credentials flag is true, toggle Access-Control-Allow-Credentials ON.

In the Access-Control-Allow-Max-Age field, define how long the results of preflight requests can be cached. This is optional, and -1 will be the value if this is disabled.

In the Access-Control-Expose-Headers field, you can define a list of headers that browsers are allowed to access.

If you want the API Gateway to execute policies for preflight-requests, toggle Run policies for preflight requests ON. By default, this is not enabled.

{% hint style="success" %} You've configured your CORS settings for your API. When you are done, select Save.. {% endhint %}

{% hint style="info" %} Troubleshooting CORS

All requests rejected because of CORS issues will generate logs that you can view in the Analytics section of your API logs.

{% endhint %}

Configure Deployments

The Deployments tab is where you can choose to use sharding tags to control where your API is deployed. Sharding tags are configured at the Organization level in Gravitee. For more information on sharding tags, what they are useful for, and how to configure them, refer to this article.

To choose sharding tags, follow the below interactive tutorial, or, follow the steps below.

{% @arcade/embed flowId="d6TOgaGsnGu4ycqJ4PUr" url="https://app.arcade.software/share/d6TOgaGsnGu4ycqJ4PUr" %}

Log in to the API Management Console. Select the APIs menu.

Select the API for which you want to configure Deployments.

Select the Edit API icon.

Under Proxy, select General.

Select the Deployments tab.

Select the Sharding tags drop down menu.

Choose the sharding tag that you want to assign to the API. This will dictate where it is deployed.

{% hint style="success" %} Select Save. You will have successfully configured your API deployment settings via choosing a sharding tag. {% endhint %}

Configure Response Templates

{% @arcade/embed flowId="5v4I7T6RoqgUFaQpk7gL" url="https://app.arcade.software/share/5v4I7T6RoqgUFaQpk7gL" %}

You can use response templates to override the default values sent in response to consumer calls to an API. Response template overrides are triggered by error keys, which are specific to policies. Each response template defines the new values to be returned for one or more status codes when the template is triggered. Because Response templates are dependent on policies, you will need to know the following before attempting to define Response templates:

  • Which policies have been applied to the API. This can be viewed in the API's plan.
  • Which error keys you can override per policy associated with your API. Refer to the table below to see the Policy error keys that you can override by configuring Response templates.

Policy error keys that you can override

Key Policy
API_KEY_MISSING API key
API_KEY_INVALID API key
QUOTA_TOO_MANY_REQUESTS Rate limiting
RATE_LIMIT_TOO_MANY_REQUESTS Rate limiting
REQUEST_CONTENT_LIMIT_TOO_LARGE Request content limit
REQUEST_CONTENT_LIMIT_LENGTH_REQUIRED Request content limit
REQUEST_TIMEOUT Mock, Callout HTTP, Request validation
REQUEST_VALIDATION_INVALID Request validation
RESOURCE_FILTERING_METHOD_NOT_ALLOWED Resource filtering
RBAC_INVALID_USER_ROLES Role-based access control
RESOURCE_FILTERING_FORBIDDEN Resource filtering
RBAC_FORBIDDEN Role-based access control
RBAC_NO_USER_ROLE Role-based access control
OAUTH2_MISSING_SERVER OAuth2
OAUTH2_MISSING_HEADER OAuth2
OAUTH2_MISSING_ACCESS_TOKEN OAuth2
OAUTH2_INVALID_ACCESS_TOKEN OAuth2
OAUTH2_INSUFFICIENT_SCOPE OAuth2
OAUTH2_INVALID_SERVER_RESPONSE OAuth2
OAUTH2_SERVER_UNAVAILABLE OAuth2
HTTP_SIGNATURE_INVALID_SIGNATURE HTTP Signature
JWT_MISSING_TOKEN JWT
JWT_INVALID_TOKEN JWT
JSON_INVALID_PAYLOAD JSON validation
JSON_INVALID_FORMAT JSON validation
JSON_INVALID_RESPONSE_PAYLOAD JSON validation
JSON_INVALID_RESPONSE_FORMAT JSON validation
GATEWAY_INVALID_REQUEST All
GATEWAY_INVALID_RESPONSE All
GATEWAY_OAUTH2_ACCESS_DENIED All
GATEWAY_OAUTH2_SERVER_ERROR All
GATEWAY_OAUTH2_INVALID_CLIENT All
GATEWAY_MISSING_SECURITY_PROVIDER All
GATEWAY_PLAN_UNRESOLVABLE All
GATEWAY_POLICY_INTERNAL_ERROR All

Response templates are configured in an API's General Proxy settings. You'll find the Response templates tab. Here, you can define:

  • Multiple templates for one API (for multiple policies and/or multiple error keys sent by the same policy)
  • Multiple template definitions for the same error key in a single template (for different content types or status codes)

To configure Response templates, follow these few steps:

  1. Choose the template key by using the Template key drop-down.
  2. Choose the requests header that should trigger your response template to be used. By default, the value is */*. However, if you want to send the template override values only for JSON or XML requests, specify JSON or XML.
  3. Specify the status code that you want to send to the API consumer using Status code drop-down.
  4. Specify the override values to send to the API consumer. These can either be:
    • One or more HTTP headers to include in the response
    • A response template body

Configure Response templates

{% hint style="success" %} Success!

From here, you can either finish up or add more Response templates by following the above steps. {% endhint %}