Merge remote-tracking branch 'origin/master'

en/docs/deploy-and-publish/deploy-on-gateway/api-gateway/passing-enduser-attributes-to-the-backend-via-api-gateway.md

@@ -14,6 +14,48 @@ Use the following format to encode the JWT using Base64URL encoding, by adding t
 encoding = "base64url"
 ```
 
+## Validating backend JWT using JWKS endpoint
+
+Backend JWTs can be signed with RSA to ensure their validity when being sent between 2 parties. To verify the JWT on the backend, we need the public certificate of the private key used to sign the JWT at the Gateway. The JWKS endpoint is a way to get this public certificate.
+
+The JWKS endpoint can be accessed via the following URL depending on the tenant.
+
+```url tab="Super Tenant"
+https://<hostname>:8243/jwks
+```
+
+```url tab="Tenant"
+https://<hostname>:8243/t/<tenant domain>/jwks
+```
+
+Refer to the following sample JWKS response.
+
+```
+{
+    "keys": [
+        {
+            "kty": "RSA",
+            "e": "AQAB",
+            "use": "sig",
+            "kid": "Q049bG9jYWxob3N0LCBPVT1XU08yLCBPPVdTTzIsIEw9TW91bnRhaW4gVmlldywgU1Q9Q0EsIEM9VVMjMTY3NzA4OTI4Mw",
+            "alg": "RS256",
+            "n": "zNqjfB4ypY0QkM4QnrtcFlRmFjdJYTzeTEzZj3PaJtNmcOCxVNwomUwbkISogv4O4J0lDVAyq6aapDNY9JzxsoLehosqyuKar3IGSJhm8IM8N7uVfT0mLQ-rho3zXE7_FahS-rwIp-OUPqJvRH8enc2mpfghG8cvBx4qq6VzMS3B72CfNAPyEeFJwi4R4ZgXzslbr_oGMJBHSQDhVEoA8ukQzUsLafbt3sFMDVy0t5KNSazRBLcHSPlx5B0W4JSWf_vv1A_c1v9AJSksxrSsRqRjoaHgp3AzhZw7LDsowfxqHZ5bF0Thxq4OXEOsk_rSPIHvRilk7OP-epTXwZpw4Q"
+        }
+    ]
+}
+```
+
+The above JWKS response contains an array of public keys available from the gateway, where each key is described using the following parameters:
+
+- `"kty"` - Key type identifies the cryptographic family this key belongs to.
+- `"e"` - The exponent value of the public key.
+- `"use"` - This defines the use of the key, whether it is used for signing or encryption.
+- `"kid"` - This is an ID parameter used to match a specific key(s).
+- `"alg"` - This defines the specific algorithm intended for use with the key.
+- `"n"` - The modulus value of the public key.
+
+In order to validate the backend JWT using JWKS, you will need to invoke the JWKS endpoint and retrieve the kid property. Also, you need the extract the kid property from the Header of the decoded JWT. Thus extracted kid values are expected to be identical.
+
 ## Expiry time of the JWT
 
 The JWT expiry time depends directly on whether caching is enabled in the Gateway Manager or Key Manager. The WSO2 API-M Gateway caching is enabled by default. However, if required, you can enable or disable the caching for the Gateway Manager or the Key Manager using the `apim.cache.gateway_token.enable` or `apim.cache.km_token.enable` elements respectively in the `<API-M_HOME>/repository/conf/deployment.toml` file. If caching is enabled for the Gateway Manager or the Key Manager, the JWT expiry time will be the same as the default cache expiry time.
@@ -311,6 +353,11 @@ apim.jwt.binding_federated_user_claims</code></pre></td>
 <td><p>This disables the binding federated user claims to the backend JWT generator.</p></td>
 <td><code>false</code></td>
 </tr>
+<tr class="odd">
+<td><pre><code>apim.jwt.use_kid_property</code></pre></td>
+<td><p>Specifies whether the backend JWT header should include the kid claim</p></td>
+<td><code>true</code></td>
+</tr>
 </tbody>
 </table>
 

en/docs/deploy-and-publish/deploy-on-gateway/choreo-connect/configure-analytics.md

@@ -141,7 +141,7 @@ The following are the two options that are available to retrieve the analytics l
 - <a href="#logtoconsole">Log to console</a>
 - <a href="#logtofile">Log to file</a>
 
-Update the `choreo-connect-1.x.x/docker-compose/choreo-connect(-with-apim)/conf/log4j2.properties` file based on the selected analytics logs retrival method as follows in order to configure the Filebeat agent.
+Update the `choreo-connect-1.x.x/docker-compose/choreo-connect(-with-apim)/conf/log4j2.properties` file based on the selected analytics logs retrieval method as follows in order to configure the Filebeat agent.
 
 <a name="logtoconsole">
 <b>Log to console</b>

en/docs/deploy-and-publish/deploy-on-gateway/choreo-connect/faq.md

@@ -104,7 +104,7 @@ You can write a [custom filter]({{base_path}}/deploy-and-publish/deploy-on-gatew
 
 #### Can I perform API request/response transformations?
 
-Yes, use a separate [interceptor service]({{base_path}}/deploy-and-publish/deploy-on-gateway/choreo-connect/message-transformation/interceptor-microservice/interceptor-microservice/). Also API policies can be used to perform simple transformations like adding/removing headers, rewriting paths, adding query params, changing HTTP methods, etc.
+Yes, use a separate [interceptor service]({{base_path}}/deploy-and-publish/deploy-on-gateway/choreo-connect/message-transformation/interceptor-microservice/interceptor-microservice/). Also, API policies can be used to perform simple transformations like adding/removing headers, rewriting paths, adding query params, changing HTTP methods, etc.
 
 ## Security
 

en/docs/deploy-and-publish/deploy-on-gateway/choreo-connect/git-integration.md

@@ -130,10 +130,10 @@ The following table describes the above configuration.
 <td><code>enabled</code></td>
 <td>Set this to <code>true</code> to enable Git integration for API Artifacts.</td>
 <tr><td><code>pollInterval</code></td>
-<td>The time interval (in seconds) in which the the Adapter should fetch updates from the repository.</td>
+<td>The time interval (in seconds) in which the Adapter should fetch updates from the repository.</td>
 </tr>
 <tr><td><code>retryInterval</code></td>                   
-<td>The time interval (in seconds) in which the the Adapter should retry fetching artifacts from the repository at startup (in case of failure).
+<td>The time interval (in seconds) in which the Adapter should retry fetching artifacts from the repository at startup (in case of failure).
 </td>
 </tr>
 <tr><td><code>maxRetryCount</code> </td>                      
@@ -360,7 +360,7 @@ After the containers are up and running, you can monitor the status of the conta
 
 After the APIs are exposed via WSO2 Choreo Connect, you can invoke an API with a valid token (JWT) or by using a test key.
 
-Let's use WSO2 Choreo Connect's test key endpoint to obtain an test key in order to access the API. For more information, see [Generate a Test JWT]({{base_path}}/deploy-and-publish/deploy-on-gateway/choreo-connect/security/generate-a-test-jwt).
+Let's use WSO2 Choreo Connect's test key endpoint to obtain a test key in order to access the API. For more information, see [Generate a Test JWT]({{base_path}}/deploy-and-publish/deploy-on-gateway/choreo-connect/security/generate-a-test-jwt).
 
 ``` tab="Sample Token"
 TOKEN=$(curl -X POST "https://localhost:9095/testkey" -d "scope=read:pets" -H "Authorization: Basic YWRtaW46YWRtaW4=" -k -v)

en/docs/deploy-and-publish/deploy-on-gateway/choreo-connect/http-2.md

@@ -6,7 +6,7 @@ There are few cases to consider as discussed below.
 
 ### HTTP/2 clear text connection with h2c upgrade call
 
-The HTTP/2 client can request the server to upgrade to HTTP/2 by using a HTTP/1.1 call with some special headers as you can see in the below snippet called `Connection`, `Upgrade` (h2c means HTTP/2 with clear text), and `HTTP2-Settings` headers in the request. If the server is able to upgrade, it sends a response again with HTTP/1.1 call with `connection: upgrade` and `upgrade: h2c` headers and again responds to the initial actual request using HTTP/2.
+The HTTP/2 client can request the server to upgrade to HTTP/2 by using an HTTP/1.1 call with some special headers as you can see in the below snippet called `Connection`, `Upgrade` (h2c means HTTP/2 with clear text), and `HTTP2-Settings` headers in the request. If the server is able to upgrade, it sends a response again with HTTP/1.1 call with `connection: upgrade` and `upgrade: h2c` headers and again responds to the initial actual request using HTTP/2.
 
 ```yaml
 $ curl --http2 http://localhost:2350/hello -v
@@ -115,11 +115,11 @@ Clients can initiate HTTP connections with Choreo Connect Router using HTTP/1.1
 [router]
   listenerCodecType = "HTTP2"
 ```
-You can set this confuration to `AUTO`, `HTTP1`, or `HTTP2`.
+You can set this configuration to `AUTO`, `HTTP1`, or `HTTP2`.
 
 ## Upstream configuration
 
-Currently the upstream connections by default works with HTTP/1.1 version. To use HTTP/2 communications with endpoints, you need to set the following Swagger extension configuration for the API you deploy to the Gateway.
+Currently, the upstream connections by default works with HTTP/1.1 version. To use HTTP/2 communications with endpoints, you need to set the following Swagger extension configuration for the API you deploy to the Gateway.
 
 ```yaml
 x-wso2-http2-backend-enabled: true
@@ -158,7 +158,7 @@ x-wso2-http2-backend-enabled: true
 ```
 
 
-#### The client does not support HTTP/2 but the backend suppports HTTP 2.0
+#### The client does not support HTTP/2 but the backend supports HTTP 2.0
 
 [![Choreo h1 h2 connection]({{base_path}}/assets/img/deploy/http2/choreo-h1-h2-connection.png)]({{base_path}}/assets/img/deploy/http2/choreo-h1-h2-connection.png)
 

en/docs/deploy-and-publish/deploy-on-gateway/choreo-connect/migration-guide-from-ballerina-api-microgateway.md

@@ -51,7 +51,7 @@ The API Microgateway is intended to function as an immutable API gateway, where
 ### Choreo Connect v1.2.0
 Choreo Connect is designed to be a mutable API gateway that publishes API modifications in real time. If necessary, it additionally supports the Immutable API gateway, which loads the API projects only during Adapter startup if they are located in `/home/wso2/artifacts/apis`. The workflow can be created in the following manner.
 
-1. Commit the API projects to the source version control (eg: Github)
+1. Commit the API projects to the source version control (eg: GitHub)
 2. This triggers the CI pipeline such as Jenkins.
 3. It creates the Adapter Docker image placing the API projects in  `/home/wso2/artifacts/` apis location.
 4. Once the Docker image creation is done, it rolls out the Adapter deployment.
@@ -96,7 +96,7 @@ x-wso2-production-endpoints:
 ```
 
 - **`retryConfig`** given under prod or sandbox endpoint only has `count` and `statusCode`. 
-- Envoy uses a fully jittered exponential back-off algorithm for retries. Therefore the interval between the retries is always a random number. More information available in [here](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#x-envoy-max-retries).
+- Envoy uses a fully jittered exponential back-off algorithm for retries. Therefore, the interval between the retries is always a random number. More information available in [here](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#x-envoy-max-retries).
 - A param called **`backOffFactor`** does not exist in the envoy’s retry interval equation, therefore is not expected in the config. 
 - **`intervalInMillis`** can only be configured via envoy route configs (not configurable via header) which is common to both prod and sandbox. Thus, we have made **`intervalInMillis`** configurable via a parameter **`BaseIntervalInMillis`** in the `config.toml` which is the base interval for the Envoy's exponential retry back off algorithm.
 - An upper bound can be set for the retry count taken from all API definitions. It can be set via **`MaxRetryCount`** set in `config.toml`. When the configured retry count in the API definition is larger than the `MaxRetryCount`, `MaxRetryCount` will be assigned as the count.
@@ -118,7 +118,7 @@ Step by step guide includes in [here]({{base_path}}/deploy-and-publish/deploy-on
 
 ### Choreo Connect with WSO2 API Manager 4.2.0
 
-Choreo Connect v4.2.0 is only compatible with WSO2 API Manager 4.2.0. Hence you need to upgrade to 4.2.0.
+Choreo Connect v4.2.0 is only compatible with WSO2 API Manager 4.2.0. Hence, you need to upgrade to 4.2.0.
 
 1. Upgrade WSO2 API Manager version to 4.2.0. 
 

en/docs/deploy-and-publish/deploy-on-gateway/choreo-connect/passing-enduser-attributes-to-the-backend-via-choreo-connect.md

@@ -221,7 +221,7 @@ The JWKS endpoint is:
 "https://localhost:9095/.wellknown/jwks"
 ```
 
-The public keys can be recieved from this endpoint with a <code>GET</code> or <code>POST</code> request.
+The public keys can be received from this endpoint with a <code>GET</code> or <code>POST</code> request.
 
 
 ### Sample JWKS response

en/docs/deploy-and-publish/deploy-on-gateway/choreo-connect/production-deployment-guideline.md

@@ -440,7 +440,7 @@ Please follow the document about [Deploying Choreo Connect on Kubernetes With WS
 ### Deploy APIs as Immutable Gateway
 
 The API Controller `apictl` can be used to deploy APIs in the standalone mode. Those APIs deployed with `apictl` will be lost if the Adapter container restarts for any reason.
-Hence, in a production deployment with the Standalone deployment option, it is recommand to create a custom docker image of Adapter by including the `apictl projects`.
+Hence, in a production deployment with the Standalone deployment option, it is recommend to create a custom docker image of Adapter by including the `apictl projects`.
 
 #### Step 1: Create Projects
 
@@ -551,7 +551,7 @@ Follow the document on [Deploying Choreo Connect as a Standalone Gateway on Kube
 
 ### Applying config changes into a running instance of Choreo Connect 
 
-When you have to deploy a config change to the Choreo Connect running on production environment, we recommand you to complete the following steps in order.
+When you have to deploy a config change to the Choreo Connect running on production environment, we recommend you to complete the following steps in order.
 
 !!! Attention
     You must follow this, if the config change is related to the **Enforcer** as the `enforcer` fetches configs from the Adapter only at the startup.

en/docs/design/api-security/oauth2/oauth2-scopes/fine-grained-access-control-with-oauth-scopes.md

@@ -237,7 +237,7 @@ When a scope is attached to an API resource, access to it gets restricted based
 
 !!! info
 
-     If you first create a local scope and then create a shared scope with same scope name before attaching the local scope to any API resource, the local scope will removed from local scope UI. However, it will not be reflected in the API Definition, unless you save the API. This is an identified limitation in supporting both local and shared scopes. Hence, we recommend you to use Shared Scopes only from 3.2 onwards. Local scopes are deprecated and will be removed in future release.
+     If you first create a local scope and then create a shared scope with same scope name before attaching the local scope to any API resource, the local scope will removed from local scope UI. However, it will not be reflected in the API Definition, unless you save the API. This is an identified limitation in supporting both local and shared scopes.
 
 
 

en/docs/get-started/integration-quick-start-guide.md

@@ -4,8 +4,11 @@ Let's get started with WSO2 Micro Integrator by running a simple integration use
 
 ## Before you begin...
 
-1. Install [Oracle Java SE Development Kit (JDK)](http://java.sun.com/javase/downloads/index.jsp) version 11 and set the `JAVA_HOME` environment variable.
-   For more information on setting the `JAVA_HOME` environment variable for different operating systems, see [Setup and Install]({{base_path}}/install-and-setup/install/installing-the-product/installing-api-m-runtime/).
+1. Install Java SE Development Kit (JDK) version 11 and set the `JAVA_HOME` environment variable.
+
+    !!! Info
+        For information on the compatible JDK types and setting the `JAVA_HOME` environment variable for different operating systems, see [Setup and Install]({{base_path}}/install-and-setup/install/installing-the-product/installing-api-m-runtime/).
+
 2. Go to the [WSO2 Micro Integrator web page](https://wso2.com/integration/micro-integrator/#), click **Download**, and then click **Zip Archive** to download the Micro Integrator distribution as a ZIP file.
 3. Optionally, navigate to the [API Manager Tooling web page](https://wso2.com/api-management/tooling/), and download WSO2 Integration Studio.
 

en/docs/includes/deploy/backend-jwt-intro.md

@@ -13,15 +13,18 @@ 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
+## Sample backend JWT
 
-The following is an example of a JWT:
+The following is an example of a backend JWT:
 
-``` java
+``` json
+{
+    "typ": "JWT",
+    "alg": "RS256",
+    "x5t": "ODE3Y2ZhMTBjMDM4ZTBmMjAyYzliYTI2YjRhYTZlOGIyZmUxNWE3YQ==",
+    "kid": "Q049bG9jYWxob3N0LCBPVT1XU08yLCBPPVdTTzIsIEw9TW91bnRhaW4gVmlldywgU1Q9Q0EsIEM9VVMjMTY3NzA4OTI4Mw"
+}
 {
-    "typ":"JWT",
-    "alg":"NONE"
-    }{
     "iss":"wso2.org/products/am",
     "exp":1345183492181,
     "http://wso2.org/claims/subscriber":"admin",
@@ -30,12 +33,17 @@ The following is an example of a JWT:
     "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 Header :** 
+
+- `"typ"` - Declares that the encoded object is a JWT access token
+- `"alg"` - This defines the specific algorithm intended for use with the key
+- `"x5t"` - Thumbprint of the x.509 cert (SHA-1 thumbprint)
+- `"kid"` - Key ID parameter is a unique identifier used to match a specific key
 
 **JWT Claims set :**
 

en/docs/includes/design/deploy-revision.md

@@ -15,6 +15,9 @@ Follow the instructions below to deploy a new revision for an API:
 
       [![Deploy new revision option](https://apim.docs.wso2.com/en/4.1.0/assets/img/design/revision/deploy-new-revision.png)](https://apim.docs.wso2.com/en/4.1.0/assets/img/design/revision/deploy-new-revision.png)
 
+    !!! note
+        The **Information icon** will appear only if you have added a product revision description. You can view the description when you hover over the information icon.
+
 3. Click **Deploy New Revision**.
 
     !!! note

en/docs/install-and-setup/setup/deployment-best-practices/security-guidelines-for-production-deployment.md

@@ -252,7 +252,7 @@ been removed from Hotspot JVM.</p>
 <td><p>Defining callback URL regular expression</p>
 <p><br />
 </p></td>
-<td><p>For password recovery, you can define a regular expression to validate the callback URL. The default configuration allows any callback URL. Note that if you are using the recovery option, it is highly recommended to define the regular expression that validates and only allows access to specific callback URLs.</p>
+<td><p>For password recovery, you can define a regular expression to validate the callback URL. The default configuration allows any callback URL. Note that if you are using the recovery option, it is highly recommended to define the regular expression that validates and only allows access to specific callback URLs.</p><p>See the <a href="https://is.docs.wso2.com/en/6.1.0/deploy/security/product-level-security-guidelines/#callback-url-regular-expressions">Callback URL Regular Expressions</a> documentation for details.</p>
 </td>
 </tr>
 </tr>

en/docs/install-and-setup/setup/setting-up-proxy-server-and-the-load-balancer/adding-a-custom-proxy-path.md

@@ -181,39 +181,26 @@ proxyPort = 443
     2. base_path has a suffix of "/apim" which is the proxy_context_path
     3. proxy_context_path is set to "/apim"
 
-### Step 4: Update the API Manager configuration - web.xml.j2
-
-Open the following file.
-`repository/resources/conf/templates/repository/conf/tomcat/carbon/WEB-INF/web.xml.j2`
-
-Add the configuration below with the same level as other `<context-param>` nodes.
-```xml
-<context-param>
-      <param-name>contextPath</param-name>
-      <param-value>apim</param-value>
-</context-param>
-```
-
-### Step 5: Update the API Manager web app configurations
+### Step 4: Update the API Manager web app configurations
 
 Add the following configuration to each web application.
 
-**devportal/site/public/theme/settings.js**
-```js
-context: '/apim/devportal', 
-proxy_context_path: '/apim',
+**devportal/site/public/theme/settings.json**
+```json
+"context": "/apim/devportal", 
+"proxy_context_path": "/apim",
 ```
 
-**publisher/site/public/conf/settings.js**
-```js
-context: '/apim/publisher', 
-proxy_context_path: '/apim',
+**publisher/site/public/conf/settings.json**
+```json
+"context": "/apim/publisher", 
+"proxy_context_path": "/apim",
 ```
 
-**admin/site/public/conf/settings.js**
-```js
-context: '/apim/admin', 
-proxy_context_path: '/apim',
+**admin/site/public/conf/settings.json**
+```json
+"context": "/apim/admin", 
+"proxy_context_path": "/apim",
 ```
 
 Now start/restart the API Manager server