diff --git a/en/docs/assets/img/api-policies/add-header-policy.png b/en/docs/assets/img/api-policies/add-header-policy.png new file mode 100644 index 000000000..f1a2fce78 Binary files /dev/null and b/en/docs/assets/img/api-policies/add-header-policy.png differ diff --git a/en/docs/assets/img/api-policies/api-level-policies.png b/en/docs/assets/img/api-policies/api-level-policies.png new file mode 100644 index 000000000..65573eb5a Binary files /dev/null and b/en/docs/assets/img/api-policies/api-level-policies.png differ diff --git a/en/docs/assets/img/api-policies/attached-add-header.png b/en/docs/assets/img/api-policies/attached-add-header.png new file mode 100644 index 000000000..fcd21a9c9 Binary files /dev/null and b/en/docs/assets/img/api-policies/attached-add-header.png differ diff --git a/en/docs/assets/img/api-policies/backend-jwt.png b/en/docs/assets/img/api-policies/backend-jwt.png new file mode 100644 index 000000000..1c65c3317 Binary files /dev/null and b/en/docs/assets/img/api-policies/backend-jwt.png differ diff --git a/en/docs/assets/img/api-policies/interceptor-policy.png b/en/docs/assets/img/api-policies/interceptor-policy.png new file mode 100644 index 000000000..3db604934 Binary files /dev/null and b/en/docs/assets/img/api-policies/interceptor-policy.png differ diff --git a/en/docs/assets/img/api-policies/mirror-request.png b/en/docs/assets/img/api-policies/mirror-request.png new file mode 100644 index 000000000..58b4142e8 Binary files /dev/null and b/en/docs/assets/img/api-policies/mirror-request.png differ diff --git a/en/docs/assets/img/api-policies/operation-level-policy-view.png b/en/docs/assets/img/api-policies/operation-level-policy-view.png new file mode 100644 index 000000000..6053431f6 Binary files /dev/null and b/en/docs/assets/img/api-policies/operation-level-policy-view.png differ diff --git a/en/docs/assets/img/api-policies/redirect-request-response.png b/en/docs/assets/img/api-policies/redirect-request-response.png new file mode 100644 index 000000000..f990bb673 Binary files /dev/null and b/en/docs/assets/img/api-policies/redirect-request-response.png differ diff --git a/en/docs/assets/img/api-policies/redirect-request.png b/en/docs/assets/img/api-policies/redirect-request.png new file mode 100644 index 000000000..ecb25aaa6 Binary files /dev/null and b/en/docs/assets/img/api-policies/redirect-request.png differ diff --git a/en/docs/assets/img/api-policies/remove-header.png b/en/docs/assets/img/api-policies/remove-header.png new file mode 100644 index 000000000..27aa163ff Binary files /dev/null and b/en/docs/assets/img/api-policies/remove-header.png differ diff --git a/en/docs/control-plane/api-management/api-policies/add-header.md b/en/docs/control-plane/api-management/api-policies/add-header.md new file mode 100644 index 000000000..652909915 --- /dev/null +++ b/en/docs/control-plane/api-management/api-policies/add-header.md @@ -0,0 +1,8 @@ +The header modification functionality allows the addition, modification, and removal of headers in both requests and responses. This capability is useful for enhancing control and flexibility in API interactions, ensuring that specific requirements for incoming requests and outgoing responses are consistently met. This functionality is configured using the HTTPRoute filters `RequestHeaderModifier` and `ResponseHeaderModifier` filters, which specify how headers should be manipulated at various stages of the request and response lifecycle. + +To add headers to requests or responses for an API or an API operation, add the name of the header and the value you require as properties in the header policy, as shown below. + +[![Add Header](../../../assets/img/api-policies/add-header-policy.png)](../../../assets/img/api-policies/add-header-policy.png) + +!!! note + While interceptors can be used for header modification as well, it is recommended to use the Add Header and Remove Header policies for that scenario, and use Interceptor policies for more advanced use cases. diff --git a/en/docs/control-plane/api-management/api-policies/api-policies-overview.md b/en/docs/control-plane/api-management/api-policies/api-policies-overview.md new file mode 100644 index 000000000..d5c598896 --- /dev/null +++ b/en/docs/control-plane/api-management/api-policies/api-policies-overview.md @@ -0,0 +1,19 @@ +# Add API Policy to API in API Manager + +Policies generally enforce some business logic that needs to be executed on the Request or Response flow of an API invocation. A policy is a collection of rules that will be executed at the API Gateway. Using policies we can make API invocations undergo slight behavioural modifications before reaching the backend. In a similar manner, we can modify the API response a client receives. + +API Manager ships a default set of policies that cover most of the common use cases that you will need. You can attach policies to the API in the [API Manager publisher portal](https://am.wso2.com/publisher){:target="_blank"}. + +The list of supported policies are as follows. + +1. Request flow: + - [Add Header](./add-header.md){:target="_blank"} + - [Remove Header](./remove-header.md){:target="_blank"} + - [Call Interceptor Service](./interceptor-service.md){:target="_blank"} + - [Mirror Request](./mirror-request.md){:target="_blank"} + - [Redirect Request](./redirect-request.md){:target="_blank"} + - [Backend JWT](./backend-jwt.md){:target="_blank"} +2. Response flow: + - [Add Header](./add-header.md){:target="_blank"} + - [Remove Header](./remove-header.md){:target="_blank"} + - [Call Interceptor Service](./interceptor-service.md){:target="_blank"} \ No newline at end of file diff --git a/en/docs/control-plane/api-management/api-policies/attaching-api-policies.md b/en/docs/control-plane/api-management/api-policies/attaching-api-policies.md new file mode 100644 index 000000000..ebd3da66b --- /dev/null +++ b/en/docs/control-plane/api-management/api-policies/attaching-api-policies.md @@ -0,0 +1,44 @@ +## Attaching Policies + +Follow the instructions below to attach one or more default policies to an existing API. + +1. Sign in to the WSO2 API Publisher at [https://am.wso2.com/publisher](https://am.wso2.com/publisher){:target="_blank"}. + +2. Click on the API for which you want to attach policies to. Navigate to **API Configurations** → **Policies**. + +3. First let us consider the **API Level Policies** tab. You can attach any number of policies by dragging and dropping from the policy list to the dropzone appearing under the desired flow (i.e. request or response). Since these policies are attached to the API level, upon API invocation these policies are engaged regardless of the resource that was invoked. + + + !!! Note + API level policies will execute before operation level policies. + +[![API Policies](../../../assets/img/api-policies/api-level-policies.png)](../../../assets/img/api-policies/api-level-policies.png) + +4. Now let us consider the **Operation Level Policies** tab. Pick out the desired operation and flow to which you want to attach policies. Once that is decided, you can expand that API operation. At this point you will notice that by default the UI will open up the first API operation on initial page visit. + +5. Let’s attach a policy to the operation. Scroll down through the left side column of the UI and click on the operation. You should be able to see the below screen when the API operation is expanded. + +[![Operation Policies](../../../assets/img/api-policies/operation-level-policy-view.png)](../../../assets/img/api-policies/operation-level-policy-view.png) + + +6. Drag the **Add Header** policy from the **Request** tab of the **Policy List** and drop that to the **Request Flow** dropzone of the first operation. You will notice a side panel appearing from the right hand side. Fill the required details using the values provided below. Then, click **Save**. + +| Field | Sample Value | +| ------------ | ------------ | +| Header Name | Foo | +| Header Value | Bar | + +!!! Note + You can optionally use the **Apply to all** resources option to attach the same policy to all the resources. This will attach the same policy to all the API operations along with the values you entered to configure the policy (if any). It is important to note that if the policy was applied to the Request Flow, it will only be applied to all the request flows of all operations. + +7. Now that we have saved the dropped policy, you should be able to see the attached **Add Header** policy (depicted with the initials `AH`). + +[![Add Header](../../../assets/img/api-policies/attached-add-header.png)](../../../assets/img/api-policies/attached-add-header.png) + +8. If you click on this newly attached **AH** (i.e. Add Header) policy, you should still be able to view/edit values that you entered initially. + +[![Add Header](../../../assets/img/api-policies/add-header-policy.png)](../../../assets/img/api-policies/add-header-policy.png) + +You can attach as many policies as you want for the operation. + +9. Finally, when you are satisfied with the dragged and dropped policies, you can go ahead and click on the **Save** button at the bottom of the page. Note that if you do not click on save, none of the dropped policies will be saved to the API. \ No newline at end of file diff --git a/en/docs/control-plane/api-management/api-policies/backend-jwt.md b/en/docs/control-plane/api-management/api-policies/backend-jwt.md new file mode 100644 index 000000000..e8703e4b7 --- /dev/null +++ b/en/docs/control-plane/api-management/api-policies/backend-jwt.md @@ -0,0 +1,28 @@ +# Passing End User Attributes to the Backend + +There can be scenarios where a backend service needs to make different decisions or respond with different data, depending on the application end-user that consumes an API. To achieve this the backend service needs to have access to the respective end-user's data at the time an API call takes place. + +This can be facilitated by the Gateway by sending the end user attributes that are defined in the respective user store, in a JWT via an HTTP header, to the backend service when the API call is being forwarded. + +## How does it work? + +The backend JSON Web Token (JWT) contains the claims that are transferred between two parties, such as the end-user and the backend. A claim is an attribute of the user that is mapped to the underlying user store. A set of claims is referred to as a dialect (e.g., http://wso2.org/claims). + +If you enable backend JWT generation in the Gateway, each API request will carry a digitally signed JWT, which is in the following format to the backend service. + +`{token header}.{claims list}.{signature}` + +When the request goes through the Gateway, the backend JWT is appended as a transport header to the outgoing message. The backend service fetches the JWT and retrieves the required information about the user, application, or token. + +To enable backend JWT for an API or an operation, you can add a policy as follows. + +[![Backend JWT](../../../assets/img/api-policies/backend-jwt.png)](../../../assets/img/api-policies/backend-jwt.png) + +The following values need to be added to the policy. + +| Field | Description | +| ----------------- | ----------------------------------------------------------------------------------------- | +| Encoding | The encoding mechanism used to encode the Backend JWT. | +| Signing Algorithm | The signing algorithm used to sign the Backend JWT. | +| Header Name | The name of the HTTP header to which the Backend JWT is attached and sent to the backend. | +| Token TTL | The expiry time of the Backend JWT. | \ No newline at end of file diff --git a/en/docs/control-plane/api-management/api-policies/interceptor-service.md b/en/docs/control-plane/api-management/api-policies/interceptor-service.md new file mode 100644 index 000000000..e8a93b808 --- /dev/null +++ b/en/docs/control-plane/api-management/api-policies/interceptor-service.md @@ -0,0 +1,26 @@ + +You can use interceptors to carry out transformations and mediation on the requests and responses. Request interceptor gets triggered before sending the request to the backend. Response interceptor gets triggered before responding to the client. Here, an interceptor is a separate microservice that handles the request, response, or both request and response transformations. + +When you have attached an Interceptor `APIPolicy` like above example to your `API`, then the request flow (`1`, `2`, `3`, and `4` numbered circles) and response flow (`5`, `6`, `7`, and `8` numbered circles) can be depicted as below. + +![Interceptors](../../../assets/img/api-management/api-policies/interceptors/interceptors-light.png#only-light) +![Interceptors](../../../assets/img/api-management/api-policies/interceptors/interceptors-dark.png#only-dark) + +If you are an API developer, you can write a custom request/response interceptor microservice in any programming language of your choice by following [the Interceptor OpenAPI Definition](https://github.com/wso2/apk/blob/main/developer/resources/interceptor-service-open-api-v1.yaml){:target="_blank"}. Then you can provide the endpoint of the microservice to the Interceptor policy and then save and redeploy the API. + +## Configuring Interceptors + +Configuring an interceptor requires the following two steps. + +1. [Implement an interceptor microservice adhering to the Interceptor OpenAPI Definition](https://apim.docs.wso2.com/en/4.2.0/deploy-and-publish/deploy-on-gateway/choreo-connect/message-transformation/interceptor-microservice/interceptor-microservice/){:target="_blank"} +For reference, a sample interceptor service for data conversion between application/json and application/xml data types with interceptor policy CRs can be found here: [request-response-mediation-interceptors](https://github.com/wso2/apk/tree/main/samples/request-response-mediation-interceptors){:target="_blank"} + +2. Create the Interceptor Policy from the APIM Publisher window as follows. +[![Interceptor Policy](../../../assets/img/api-policies/interceptor-policy.png)](../../../assets/img/api-policies/interceptor-policy.png) + +The following fields need to added. + +| Field Name | Description | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Service URL | The endpoint of the interceptor microservice | +| Includes to payload | The content of the payload that must be sent to the interceptor. Possible values include: request_headers, request_body, request_trailer, response_headers, response_body, response_trailer, invocation_context | diff --git a/en/docs/control-plane/api-management/api-policies/mirror-request.md b/en/docs/control-plane/api-management/api-policies/mirror-request.md new file mode 100644 index 000000000..da6d90a32 --- /dev/null +++ b/en/docs/control-plane/api-management/api-policies/mirror-request.md @@ -0,0 +1,9 @@ +Request mirroring allows traffic to be duplicated and sent to additional backends for testing and monitoring purposes. This feature is particularly useful for scenarios where you want to test changes or monitor the behavior of your application under different conditions without affecting the primary production or sandbox environment. The Request Mirror filter can mirror requests to different backends apart from the primary backend defined in the production or sandbox endpoints. + +The current implementation operates in a “fire and forget” manner, and only the response from the primary endpoint will be returned. This allows for the assessment of changes in a real-world environment without impacting the actual user experience. This method ensures that the production environment remains stable while providing insights into how updates or modifications would perform under actual load conditions. + +For request mirroring, add the URL you want the request to be mirrored to in the Mirror Request Policy as shown below. + +[![Mirror Request](../../../assets/img/api-policies/mirror-request.png)](../../../assets/img/api-policies/mirror-request.png) + +When this operation is invoked, the request will then be sent to the URL added in the policy and the backend URL. \ No newline at end of file diff --git a/en/docs/control-plane/api-management/api-policies/redirect-request.md b/en/docs/control-plane/api-management/api-policies/redirect-request.md new file mode 100644 index 000000000..63ea6a27b --- /dev/null +++ b/en/docs/control-plane/api-management/api-policies/redirect-request.md @@ -0,0 +1,17 @@ + +Request redirection allows you to send clients to a different URL. This can be useful for changing old URLs to new ones or directing traffic based on specific conditions. Request redirection can be configured via the apk-conf file as follows. + +The redirect request policy requires two values: + +1. The URL to be shown in the location header in the response +2. The status code to be shown in the response + +These values can be provided in the redirect request policy as follows. + +[![Redirect Request](../../../assets/img/api-policies/redirect-request.png)](../../../assets/img/api-policies/redirect-request.png) + +Once you have saved the above policy and redeployed the API, when you invoke the operation you added the redirect policy to, you will get a response similar to the following. + +[![Redirect Request Response](../../../assets/img/api-policies/redirect-request-response.png)](../../../assets/img/api-policies/redirect-request-response.png) + +The location header and the status code contain the values that were specified in the request redirect policy. \ No newline at end of file diff --git a/en/docs/control-plane/api-management/api-policies/remove-header.md b/en/docs/control-plane/api-management/api-policies/remove-header.md new file mode 100644 index 000000000..1b68ae498 --- /dev/null +++ b/en/docs/control-plane/api-management/api-policies/remove-header.md @@ -0,0 +1,12 @@ +Web services may contain response headers with sensitive information. This header can be used to remove HTTP request headers from the responses for security reasons. + +To remove headers from requests or responses for an API or an API operation, add the name of the header to be removed as a property in the header policy, as shown below. + +[![Remove Header](../../../assets/img/api-policies/remove-header.png)](../../../assets/img/api-policies/remove-header.png) + +If the remove header policy is applied to the Request flow, the header will be removed from the request body and sent to the backend. + +If the remove header policy is applied to the Response flow, the header will be removed from the response body and sent back to the client. + +!!! note + While interceptors can be used for header modification as well, it is recommended to use the Add Header and Remove Header policies for that scenario, and use Interceptor policies for more advanced use cases. \ No newline at end of file diff --git a/en/docs/control-plane/api-management/control-plane-api-policies.md b/en/docs/control-plane/api-management/control-plane-api-policies.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/en/docs/create-api/create-and-attach-api-policies/api-policies-overview.md b/en/docs/create-api/create-and-attach-api-policies/api-policies-overview.md index 1fb9b1773..3f23c6926 100644 --- a/en/docs/create-api/create-and-attach-api-policies/api-policies-overview.md +++ b/en/docs/create-api/create-and-attach-api-policies/api-policies-overview.md @@ -14,7 +14,6 @@ There are a few levels where a Policy attachment can happen in APK resources. Attaching a policy to a specific level is descibed under each policy. - ## Policy Execution Order When you have multiple policies attached in different levels policies, you need to be aware of in which order they are executed in runtime. The following table describes the execution order. The top one is executed first, and the bottom one is executed last. @@ -47,9 +46,27 @@ Keep in mind that you cannot attach an API policy at two separate levels simulta When you attach a policy at the API-level, it will be applied globally to all the operations that correspond to the API. However, when you attach a policy at an operation level, it will only be applicable locally to a specific operation. +## Supported API Policies + +The following API policies are supported in APK. + +- Interceptor Services +- Backend JWT +- CORS +- Header Modification +- Request Redirection +- Request Mirroring + +For more complex requirements that go beyond default policies, consider using **interceptor services**. These services enable you to: + +- Implement custom logic for request and response processing. +- Apply transformations, validations, or enhancements based on specific use cases. + ## What's Next? -- [Learn to attach API Policies for Interceptor Services](./interceptors/interceptors-overview.md) -- [Learn to attach API Policies for Backend JWT Token Manipulation](./backend-jwt-token-manipulation/overview.md) -- [Learn to attach API Policies for CORS](./cors/enable-cors-via-rest-api.md) - +- [Learn to attach API Policies for Interceptor Services](./interceptors/interceptors-overview.md){:target="_blank"} +- [Learn to attach API Policies for Backend JWT Token Manipulation](./backend-jwt-token-manipulation/overview.md){:target="_blank"} +- [Learn to attach API Policies for CORS](./cors/enable-cors-via-rest-api.md){:target="_blank"} +- [Learn to attach API Policies for Header Modification](./header-modifier-filters/overview.md){:target="_blank"} +- [Learn to attach API Policies for Request Redirection](./redirect-request-filters/redirect-request-via-rest-api.md){:target="_blank"} +- [Learn to attach API Policies for Request Mirroring](./mirror-request-filters/overview.md){:target="_blank"} \ No newline at end of file diff --git a/en/docs/create-api/create-and-attach-api-policies/backend-jwt-token-manipulation/overview.md b/en/docs/create-api/create-and-attach-api-policies/backend-jwt-token-manipulation/overview.md index a2135e13a..d649b4618 100644 --- a/en/docs/create-api/create-and-attach-api-policies/backend-jwt-token-manipulation/overview.md +++ b/en/docs/create-api/create-and-attach-api-policies/backend-jwt-token-manipulation/overview.md @@ -1,6 +1,5 @@ # Passing End User Attributes to the Backend - There can be scenarios where a backend service needs to make different decisions or respond with different data, depending on the application end-user that consumes an API. To achieve this the backend service needs to have access to the respective end-user's data at the time an API call takes place. This can be facilitated by the Gateway by sending the end user attributes that are defined in the respective user store, in a JWT via an HTTP header, to the backend service when the API call is being forwarded. @@ -15,41 +14,6 @@ If you enable backend JWT generation in the Gateway, each API request will carry When the request goes through the Gateway, the backend JWT is appended as a transport header to the outgoing message. The backend service fetches the JWT and retrieves the required information about the user, application, or token. -## Sample JWT - -The following is an example of a JWT: - -``` java -{ - "typ":"JWT", - "alg":"NONE" - }{ - "iss":"wso2.org/products/am", - "exp":1345183492181, - "http://wso2.org/claims/subscriber":"admin", - "http://wso2.org/claims/applicationname":"app2", - "http://wso2.org/claims/apicontext":"/placeFinder", - "http://wso2.org/claims/version":"1.0.0", - "http://wso2.org/claims/tier":"Silver", - "http://wso2.org/claims/enduser":"sumedha" - } -``` - -The above JSON Web Token (JWT) contains the following information. - -**JWT Header :** The header section declares that the encoded object is a JWT access token and the JWT is in plain text, that is not signed using any encryption algorithm. - -**JWT Claims set :** - -- `"iss"` - The issuer of the JWT -- `"exp"` - The token expiration time -- `"http://wso2.org/claims/subscriber"` - Subscriber to the API, usually the app developer -- `" http://wso2.org/claims/applicationname"` - Application through which API invocation is done -- `" http://wso2.org/claims/apicontext"` - Context of the API -- `" http://wso2.org/claims/version "` - API version -- `" http://wso2.org/claims/tier"` - Tier/price band for the subscription -- `" http://wso2.org/claims/enduser"` - End-user of the app who's action invoked the API - You can configure backend JWT in two ways. 1. Using the APK Conf file diff --git a/en/docs/create-api/create-and-attach-api-policies/mirror-request-filters/overview.md b/en/docs/create-api/create-and-attach-api-policies/mirror-request-filters/overview.md index 838e3de12..d3611d7b0 100644 --- a/en/docs/create-api/create-and-attach-api-policies/mirror-request-filters/overview.md +++ b/en/docs/create-api/create-and-attach-api-policies/mirror-request-filters/overview.md @@ -6,5 +6,5 @@ The current implementation operates in a “fire and forget” manner, and only Request mirroring can be done in one of two ways. -1. Via REST API (using the APK-Conf file). -2. Via CRs. +1. [Via REST API (using the APK-Conf file)](./mirror-request-via-rest-api.md){:target="_blank"}. +2. [Via CRs](./mirror-request-via-crs.md){:target="_blank"}. diff --git a/en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-crs.md b/en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-crs.md index fb5f2c692..36094d4ad 100644 --- a/en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-crs.md +++ b/en/docs/create-api/create-and-attach-api-policies/redirect-request-filters/redirect-request-via-crs.md @@ -1,4 +1,4 @@ -# Request Redirection via REST API +# Request Redirection via CRs Request redirection allows you to send clients to a different URL. This can be useful for changing old URLs to new ones or directing traffic based on specific conditions. Request redirection can be configured via Kubernetes CRs as follows. diff --git a/en/mkdocs.yml b/en/mkdocs.yml index 143ffe686..17b0345f4 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -213,6 +213,16 @@ nav: - Create REST APIs: control-plane/apk-as-gateway-in-apim/api-management/control-plane-create-and-deploy-rest-apis.md - Create GraphQL APIs: control-plane/apk-as-gateway-in-apim/api-management/control-plane-create-and-deploy-graphql-apis.md - Create AI APIs: control-plane/apk-as-gateway-in-apim/api-management/control-plane-create-and-deploy-ai-apis.md + - Add API Policies: + - API Policies Overview: control-plane/api-management/api-policies/api-policies-overview.md + - Attach Policies: control-plane/api-management/api-policies/attaching-api-policies.md + - Default Policies: + - Add Specific Headers to Request/Response: control-plane/api-management/api-policies/add-header.md + - Remove Specific Headers from Request/Response: control-plane/api-management/api-policies/remove-header.md + - Message Transformation using Interceptor APIPolicy: control-plane/api-management/api-policies/interceptor-service.md + - Request Mirroring: control-plane/api-management/api-policies/mirror-request.md + - Request Redirection: control-plane/api-management/api-policies/redirect-request.md + - Backend JWT: control-plane/api-management/api-policies/backend-jwt.md - Add APK Gateway: control-plane/apk-as-gateway-in-apim/api-management/control-plane-add-apk-gateway.md - Create Application and Subscribe: control-plane/apk-as-gateway-in-apim/api-management/control-plane-create-application-and-subscription.md - Advanced Configuration: