<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Akila Fernando on Medium]]></title>
        <description><![CDATA[Stories by Akila Fernando on Medium]]></description>
        <link>https://medium.com/@akila95fernando?source=rss-acce4f7d0988------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*LmaZ_t0koVNRUDa9.jpg</url>
            <title>Stories by Akila Fernando on Medium</title>
            <link>https://medium.com/@akila95fernando?source=rss-acce4f7d0988------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 17:31:48 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@akila95fernando/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Enabling XSD validation in WSO2 API Manager 4.5.0]]></title>
            <link>https://medium.com/@akila95fernando/enabling-xsd-validation-in-wso2-api-manager-4-5-0-5bc96ea8700c?source=rss-acce4f7d0988------2</link>
            <guid isPermaLink="false">https://medium.com/p/5bc96ea8700c</guid>
            <category><![CDATA[threat-protection]]></category>
            <category><![CDATA[xml-validation]]></category>
            <category><![CDATA[wso2]]></category>
            <category><![CDATA[dx]]></category>
            <category><![CDATA[wso2-api-manager]]></category>
            <dc:creator><![CDATA[Akila Fernando]]></dc:creator>
            <pubDate>Tue, 06 Jan 2026 06:39:20 GMT</pubDate>
            <atom:updated>2026-01-06T06:39:20.439Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Lrv1S8-rmIpV5nUzx2108A.png" /></figure><p>Hi WSO2 enthusiasts 👋,</p><p>Today, we’re going to explore how to enforce XML payload validation in WSO2 API Manager.</p><p>While JSON Schema validation is fairly straightforward to enable [1], XML validation against a defined XSD can be a bit tricky to implement. But don’t worry — I’ll guide you through the process step by step.</p><p>So, let’s jump right in.</p><p>To demonstrate XML validation, we’ll need the following:</p><p><strong>Step 1 ) A backend server that accepts XML requests and returns a responses</strong></p><p><strong>Step 2 ) An XSD that validates the incoming XML payload</strong></p><p><strong>Step 3 ) An API exposed via WSO2 API Manager that fronts the backend and enforces payload validation using the XSD</strong></p><p>We’ll start by creating a sample Java backend that accepts an XML payload and returns a response. From there, we’ll move on to integrating it with WSO2 API Manager and enabling XML validation.</p><pre>import com.sun.net.httpserver.HttpServer;<br>import com.sun.net.httpserver.HttpExchange;<br>import javax.xml.parsers.DocumentBuilder;<br>import javax.xml.parsers.DocumentBuilderFactory;<br>import org.w3c.dom.Document;<br>import java.io.*;<br>import java.net.InetSocketAddress;<br>import java.nio.charset.StandardCharsets;<br><br>public class SimpleOrderServer {<br><br>    public static void main(String[] args) throws Exception {<br>        HttpServer server = HttpServer.create(new InetSocketAddress(8082), 0);<br>        server.createContext(&quot;/api/orders&quot;, SimpleOrderServer::handleOrder);<br>        server.setExecutor(null);<br>        server.start();<br><br>        System.out.println(&quot;Server started on http://localhost:8082&quot;);<br>    }<br><br>    private static void handleOrder(HttpExchange exchange) throws IOException {<br>        if (!&quot;POST&quot;.equalsIgnoreCase(exchange.getRequestMethod())) {<br>            exchange.sendResponseHeaders(405, -1);<br>            return;<br>        }<br><br>        try {<br>            // Read request body<br>            InputStream is = exchange.getRequestBody();<br>            String xml = new String(is.readAllBytes(), StandardCharsets.UTF_8);<br><br>            // Parse XML<br>            DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();<br>            DocumentBuilder builder = factory.newDocumentBuilder();<br>            Document doc = builder.parse(new ByteArrayInputStream(xml.getBytes()));<br><br>            String id = doc.getElementsByTagName(&quot;id&quot;).item(0).getTextContent();<br>            String item = doc.getElementsByTagName(&quot;item&quot;).item(0).getTextContent();<br>            String quantity = doc.getElementsByTagName(&quot;quantity&quot;).item(0).getTextContent();<br><br>            // Create JSON response<br>            String jsonResponse = &quot;{&quot;<br>                    + &quot;\&quot;id\&quot;:\&quot;&quot; + id + &quot;\&quot;,&quot;<br>                    + &quot;\&quot;item\&quot;:\&quot;&quot; + item + &quot;\&quot;,&quot;<br>                    + &quot;\&quot;quantity\&quot;:&quot; + quantity<br>                    + &quot;}&quot;;<br><br>            // Send response<br>            exchange.getResponseHeaders().add(&quot;Content-Type&quot;, &quot;application/json&quot;);<br>            exchange.sendResponseHeaders(200, jsonResponse.getBytes().length);<br><br>            OutputStream os = exchange.getResponseBody();<br>            os.write(jsonResponse.getBytes());<br>            os.close();<br><br>        } catch (Exception e) {<br>            String error = &quot;{\&quot;error\&quot;:\&quot;Invalid XML\&quot;}&quot;;<br>            exchange.sendResponseHeaders(400, error.getBytes().length);<br>            exchange.getResponseBody().write(error.getBytes());<br>            exchange.getResponseBody().close();<br>        }<br>    }<br>}</pre><p>Compile the above and run it</p><pre>to compile &gt; javac SimpleOrderServer.java<br>to run &gt; java SimpleOrderServer</pre><p>To briefly recap what we’ve done so far: we’ve created a simple backend with a POST endpoint exposed at <strong>/api/orders</strong>. This endpoint accepts an XML payload and responds by converting the XML request into JSON.</p><p>You can test the backend using the following cURL command:</p><pre>curl -X POST http://localhost:8082/api/orders \<br>  -H &quot;Content-Type: application/xml&quot; \<br>  -H &quot;Accept: application/json&quot; \<br>  -d &#39;&lt;order&gt;<br>        &lt;id&gt;123&lt;/id&gt;<br>        &lt;item&gt;Laptop&lt;/item&gt;<br>        &lt;quantity&gt;1&lt;/quantity&gt;<br>      &lt;/order&gt;&#39;</pre><p>Let’s move on to <strong>Step 2</strong>.</p><p>In this step, we’ll create a <strong>simple XSD</strong> that validates the XML payload we used earlier. This XSD will define the structure, data types, and constraints of the incoming XML request, ensuring that only valid payloads are allowed to pass through the API.</p><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;<br>&lt;xs:schema xmlns:xs=&quot;http://www.w3.org/2001/XMLSchema&quot;<br>           elementFormDefault=&quot;qualified&quot;&gt;<br><br>    &lt;!-- Root element --&gt;<br>    &lt;xs:element name=&quot;order&quot;&gt;<br>        &lt;xs:complexType&gt;<br>            &lt;xs:sequence&gt;<br>                &lt;xs:element name=&quot;id&quot; type=&quot;xs:int&quot;/&gt;<br>                &lt;xs:element name=&quot;item&quot; type=&quot;xs:string&quot;/&gt;<br>                &lt;xs:element name=&quot;quantity&quot; type=&quot;xs:int&quot;/&gt;<br>            &lt;/xs:sequence&gt;<br>        &lt;/xs:complexType&gt;<br>    &lt;/xs:element&gt;<br><br>&lt;/xs:schema&gt;</pre><p>The XSD above enforces the following rules:</p><ul><li>A valid XML payload must have <strong>&lt;order&gt; as the root element</strong></li><li>It must contain <strong>exactly three child elements</strong>, in the following order and with the corresponding data types:</li></ul><p>&lt;id&gt; → integer<br>&lt;item&gt; → string<br>&lt;quantity&gt; → integer</p><p>Cool! 🎉 Now we have our XSD in place.</p><p>Next, we need to host the XSD so that WSO2 API Manager can access it and perform request payload validation against it.</p><p>You might be wondering why we can’t validate the request directly against a local XSD file. In fact, we can — and I’ll cover that approach a bit later. For now, we’ll focus on hosting the XSD.</p><p>Below is a sample server that hosts our XSD definition and serves it over HTTP.</p><pre>import com.sun.net.httpserver.HttpServer;<br>import com.sun.net.httpserver.HttpHandler;<br>import com.sun.net.httpserver.HttpExchange;<br>import java.io.IOException;<br>import java.io.OutputStream;<br>import java.net.InetSocketAddress;<br>import java.nio.file.Files;<br>import java.nio.file.Path;<br><br>public class XsdServer {<br><br>    public static void main(String[] args) throws Exception {<br>        int port = 8080;<br>        HttpServer server = HttpServer.create(new InetSocketAddress(port), 0);<br><br>        server.createContext(&quot;/schemas/order.xsd&quot;, new HttpHandler() {<br>            @Override<br>            public void handle(HttpExchange exchange) throws IOException {<br>                Path xsdPath = Path.of(&quot;order.xsd&quot;);<br><br>                byte[] response = Files.readAllBytes(xsdPath);<br><br>                exchange.getResponseHeaders().set(&quot;Content-Type&quot;, &quot;application/xml&quot;);<br>                exchange.sendResponseHeaders(200, response.length);<br><br>                try (OutputStream os = exchange.getResponseBody()) {<br>                    os.write(response);<br>                }<br>            }<br>        });<br><br>        server.setExecutor(null);<br>        server.start();<br><br>        System.out.println(&quot;XSD hosted at http://localhost:&quot; + port + &quot;/schemas/order.xsd&quot;);<br>    }<br>}</pre><p>Compile it and run it! 🚀<br>Make sure that <strong>order.xsd</strong> and <strong>XsdServer.java</strong> are located in the <strong>same directory</strong> before starting the server.</p><p>Once the server is running, you can verify that the XSD is being served correctly by simply <strong>browsing to the hosted URL</strong> in your browser. If everything is set up properly, you should see the contents of the XSD rendered in the response.</p><pre>http://localhost:8080/schemas/order.xsd</pre><p>Now, let’s move on to <strong>Step 3</strong>, where we configure <strong>XSD validation in WSO2 API Manager</strong>.</p><p>First, we’ll create an <strong>API in WSO2 API Manager</strong> that points to our backend service. This API will act as the front-facing layer and will later be enhanced to validate incoming XML payloads against the XSD.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*oZ8L_VgGnDneD73dQvzGOQ.png" /></figure><p>Lets add our POST resource to the created API</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JRqHFzRiXs07YrtvKpeXmQ.png" /></figure><p>In WSO2 API Manager, XSD validation is performed using a <strong>Class Mediator</strong>. To enable this validation, we need to <strong>engage the mediator via a policy</strong>, which can be attached either at the <strong>API level</strong> or the <strong>resource level</strong>.</p><p>Let’s create a policy that engages the <strong>XMLSchemaValidator</strong> mediator. You can use the sample policy shown below.</p><p>A similar example is also available in the <strong>official WSO2 documentation</strong> [2].</p><pre>&lt;sequence xmlns=&quot;http://ws.apache.org/ns/synapse&quot; name=&quot;custom_xml_validator&quot;&gt;<br>    &lt;property name=&quot;xmlValidation&quot; value=&quot;true&quot;/&gt;<br>    &lt;property name=&quot;dtdEnabled&quot; value=&quot;false&quot;/&gt;<br>    &lt;property name=&quot;externalEntitiesEnabled&quot; value=&quot;true&quot;/&gt;<br>    &lt;property name=&quot;maxXMLDepth&quot; value=&quot;100&quot;/&gt;<br>    &lt;property name=&quot;maxElementCount&quot; value=&quot;100&quot;/&gt;<br>    &lt;property name=&quot;maxAttributeCount&quot; value=&quot;100&quot;/&gt;<br>    &lt;property name=&quot;maxAttributeLength&quot; value=&quot;100&quot;/&gt;<br>    &lt;property name=&quot;entityExpansionLimit&quot; value=&quot;100&quot;/&gt;<br>    &lt;property name=&quot;maxChildrenPerElement&quot; value=&quot;100&quot;/&gt;<br>    &lt;property name=&quot;entityExpansionLimit&quot; value=&quot;100&quot;/&gt;<br>    &lt;property name=&quot;schemaValidation&quot; value=&quot;true&quot;/&gt;<br>    &lt;property name=&quot;xsdURL&quot; value=&quot;http://localhost:8080/schemas/order.xsd&quot;/&gt;<br>    &lt;property name=&quot;RequestMessageBufferSize&quot; value=&quot;1024&quot;/&gt;<br>    &lt;class name=&quot;org.wso2.carbon.apimgt.gateway.mediators.XMLSchemaValidator&quot;/&gt;<br>&lt;/sequence&gt;</pre><p>To strengthen the security you can fine tune the above property values . More importantly , the <strong>xsdURL</strong> property is set to our hosted .xsd .</p><p>You can save the above content to a .xml file ( custom_xml_validator.xml ) and create a new policy using that .</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0OMX3TrNUkritrSHCP1e2A.png" /></figure><p>Then it needs to be attached to the POST resource .</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dJyCJh6LNuUeJUt8jO4oSA.png" /></figure><p><strong>Note:</strong> You can attach this policy either at the API level or at the operation (resource) level.<br>API-level policies take precedence over operation-level policies and are applied to all resources/operations defined within the API.</p><p>Now, we have successfully engaged XSD validation for the API. The next step is to deploy the API and publish it to the Developer Portal.</p><p>Let’s validate the functionality by invoking the API.</p><p>First, we’ll invoke the API using an XML payload that is <strong>compatible with</strong> our XSD.</p><pre><strong>Request </strong><br><br>  curl -kX &#39;POST&#39; \<br>  &#39;https://localhost:8243/demo/1.0/api/orders&#39; \<br>  -H &#39;Content-Type: application/xml&#39; \<br>  -H &#39;Authorization: Bearer eyJ4...3SYg&#39; \<br>  -d &#39;&lt;order&gt;&lt;id&gt;123&lt;/id&gt;&lt;item&gt;Laptop&lt;/item&gt;&lt;quantity&gt;1&lt;/quantity&gt;&lt;/order&gt;&#39;<br><br><strong>Response </strong><br><br>&lt; HTTP/1.1 200 OK<br>&lt; {&quot;id&quot;:&quot;123&quot;,&quot;item&quot;:&quot;Laptop&quot;,&quot;quantity&quot;:1}</pre><p>Lets invoke the API with an <strong>incompatible xml payloa</strong>d . Lets pass the quantity value as “two” which expects an integer as per the XSD .</p><pre><strong>Request</strong> <br><br>  curl -kX &#39;POST&#39; \<br>  &#39;https://localhost:8243/demo/1.0/api/orders&#39; \<br>  -H &#39;Content-Type: application/xml&#39; \<br>  -H &#39;Authorization: Bearer eyJ4...3SYg&#39; \<br>  -d &#39;&lt;order&gt;&lt;id&gt;123&lt;/id&gt;&lt;item&gt;Laptop&lt;/item&gt;&lt;quantity&gt;two&lt;/quantity&gt;&lt;/order&gt;&#39;<br><br><strong>Response</strong><br><br>&lt; HTTP/1.1 400 Bad Request<br>&lt; {&quot;code&quot;:&quot;400&quot;,&quot;message&quot;:&quot;Bad Request&quot;,<br>&quot;description&quot;:&quot;Error occurred while parsing XML payload : org.xml.sax.SAXParseException;<br> lineNumber: 1; columnNumber: 63; cvc-datatype-valid.1.2.1: &#39;two&#39; is not a valid value for &#39;integer&#39;.&quot;}</pre><p>Cool !! It breaks the request as expected and returns 400 response . Meaning XSD validation is successful .</p><h4><strong>FAQ</strong></h4><ol><li>Instead of a hosted XSD URL can I do XSD validation against a file definition ?</li></ol><p>Yes. You can provide a <strong>local XSD file path</strong> to the <strong>xsdURL</strong> property in the mediation policy.</p><p>However, note that the file path <strong>must be an absolute path</strong> on the gateway file system. Because of this requirement, this approach does <strong>not scale well</strong> when you have multiple gateway nodes.</p><p>For that reason, using a <strong>hosted XSD</strong> is generally the preferred and more scalable approach in distributed or production deployments.</p><p>Ex :</p><pre>&lt;property name=&quot;xsdURL&quot; value=&quot;file:///Users/akilafdo/Desktop/wso2/order.xsd&quot;/&gt;</pre><p>2. Is there a performance impact turning the XSD validation on ?</p><p>Yes. <strong>XMLSchemaValidator</strong> is a <strong>content-aware mediator</strong>, which means it builds the message at runtime in order to perform validation. As a result, a <strong>performance overhead at the gateway</strong> is expected. This is an important consideration when enabling XSD validation for high-throughput APIs.</p><p>That brings us to the end of this article.</p><p>Thanks for reading, and goodbye for now! 👋<br>Until next time, keep experimenting and keep exploring !!</p><h4><strong>REFERENCES</strong></h4><p>[1] <a href="https://apim.docs.wso2.com/en/4.5.0/manage-apis/design/api-security/api-request-response-schema-validation/json-schema-validator/#json-schema-validator">https://apim.docs.wso2.com/en/4.5.0/manage-apis/design/api-security/api-request-response-schema-validation/json-schema-validator/#json-schema-validator</a></p><p>[2] <a href="https://apim.docs.wso2.com/en/4.5.0/manage-apis/deploy-and-publish/deploy-on-gateway/api-gateway/threat-protectors/xml-threat-protection-for-api-gateway/#xml-threat-protection-for-universal-gateway">https://apim.docs.wso2.com/en/4.5.0/manage-apis/deploy-and-publish/deploy-on-gateway/api-gateway/threat-protectors/xml-threat-protection-for-api-gateway/#xml-threat-protection-for-universal-gateway</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5bc96ea8700c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Troubleshooting API Sync Issues In WSO2 API Manager 4.3.0- Part II]]></title>
            <link>https://medium.com/@akila95fernando/troubleshooting-api-sync-issues-in-wso2-api-manager-4-3-0-part-ii-4471729d5b80?source=rss-acce4f7d0988------2</link>
            <guid isPermaLink="false">https://medium.com/p/4471729d5b80</guid>
            <category><![CDATA[synchronization]]></category>
            <category><![CDATA[wso2-api-manager]]></category>
            <category><![CDATA[404]]></category>
            <category><![CDATA[event-driven-architecture]]></category>
            <category><![CDATA[wso2]]></category>
            <dc:creator><![CDATA[Akila Fernando]]></dc:creator>
            <pubDate>Wed, 28 May 2025 10:56:01 GMT</pubDate>
            <atom:updated>2025-05-28T10:56:01.141Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*X578uOEKaqRpoToKdALNOQ.png" /></figure><p>Hi WSO2 Enthusiasts ,</p><p>Welcome back ! I hope you’re joining from my previous post (Part I). If not, I recommend checking it out [1], as it lays the groundwork for the concepts we’ll explore here.</p><p>In Part I, we looked into the behind-the-scenes processes that occur when you publish and deploy an API via the Publisher Portal along with the configurations in WSO2 API Manager 4.3.0.</p><p>In this post, we’ll dive into how to troubleshoot synchronization issues and pinpoint where things might be going wrong.</p><p>We’ll use the same sequence diagram from Part I — let’s walk through each step and explore how to effectively troubleshoot them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HSh3s98nzgvGa0bcxF2K2g.png" /></figure><p>Once Publisher deploy the API to a target gateway environment , Control-Plane will construct an event including the API metadata and intended gateway environment information.</p><p>The generated binary event will be published to all the control planes in the deployment through the event streams .</p><p>To verify if all the control-planes receive the binary events , We can enable the following DEBUG logs at each <strong>Control-Plane’s log4j2.properties</strong> configurations .</p><pre>logger.WSO2EventAdapterServiceDS.name = org.wso2.carbon.event.input.adapter.wso2event.internal.ds<br>logger.WSO2EventAdapterServiceDS.level = DEBUG</pre><p>The above DEBUG logs will print the binary events captured by the EventReceivers at Control-Plane nodes in respective wso2carbon.log .</p><p>For an example following is a DEBUG log captured at control-plane .</p><pre>[2025-05-27 13:59:21,869] DEBUG - WSO2EventAdapterServiceDS Event received in wso2Event Adapter - <br>Event{<br>  streamId=&#39;org.wso2.apimgt.notification.stream:1.0.0&#39;,<br>  timeStamp=1748334561752,<br>  metaData=null,<br>  correlationData=null,<br>  payloadData=[DEPLOY_API_IN_GATEWAY, 1748334561751, eyJhcGlJZCI6MCwidXVpZCI6ImU1MjE0MzRhLTkwNzEtNDQ1Yi1iZDZmLWU3Y2RkMmVhNGFjNiIsIm5hbWUiOiJUZXN0QVBJIiwidmVyc2lvbiI6IjEuMCIsInByb3ZpZGVyIjoiYWRtaW4iLCJhcGlUeXBlIjoiSFRUUCIsImdhdGV3YXlMYWJlbHMiOlsiRGVmYXVsdCJdLCJhc3NvY2lhdGVkQXBpcyI6W10sImNvbnRleHQiOiIvdGVzdC8xLjAiLCJldmVudElkIjoiYTE4Mjg2YjQtZGFhYi00ZDhhLWI1ODktMDZmNGY0Y2ZjM2FiIiwidGltZVN0YW1wIjoxNzQ4MzM0NTYxNzUxLCJ0eXBlIjoiREVQTE9ZX0FQSV9JTl9HQVRFV0FZIiwidGVuYW50SWQiOjAsInRlbmFudERvbWFpbiI6ImNhcmJvbi5zdXBlciJ9],<br>  arbitraryDataMap={},<br>}</pre><p>The payload data contains the base64 encoded metadata about the API . Lets decode it and see what are the information captured for better understanding .</p><pre>{&quot;apiId&quot;:0,&quot;uuid&quot;:&quot;e521434a-9071-445b-bd6f-e7cdd2ea4ac6&quot;,&quot;name&quot;:&quot;TestAPI&quot;,&quot;version&quot;:&quot;1.0&quot;,&quot;provider&quot;:&quot;admin&quot;,&quot;apiType&quot;:&quot;HTTP&quot;,&quot;gatewayLabels&quot;:[&quot;Default&quot;],&quot;associatedApis&quot;:[],&quot;context&quot;:&quot;/test/1.0&quot;,&quot;eventId&quot;:&quot;a18286b4-daab-4d8a-b589-06f4f4cfc3ab&quot;,&quot;timeStamp&quot;:1748334561751,&quot;type&quot;:&quot;DEPLOY_API_IN_GATEWAY&quot;,&quot;tenantId&quot;:0,&quot;tenantDomain&quot;:&quot;carbon.super&quot;}</pre><p>Once the binary event is captured from EventReceivers , it will be put in to the relevant eventStream .</p><p>Reading from the eventStream, control plane will construct a JMS Event and publish to it’s own broker component via respective Event publishers.</p><p>As we discussed in the previous post , the EventReceiver responsible for the API notification is “<em>notificationsWSO2EventReceiver</em>” and the EventPublisher responsible for API notifications is “<em>notificationJMSPublisher</em>” .</p><p>Hence it is essential that <em>notificationsWSO2EventReceiver</em> and <em>notificationJMSPublisher</em> is successfully deployed at the control-plane startup . In the wso2carbon.log of control-plane startup it would be indicated as follows when the event publisher and event receiver is deployed .</p><pre>[2025-05-27 13:40:22,798]  INFO - EventReceiverDeployer Event Receiver configuration successfully deployed and in active state: notificationsWSO2EventReceiver<br>[2025-05-27 13:40:22,800]  INFO - EventPublisherDeployer Event Publisher configuration successfully deployed and in active state : notificationJMSPublisher</pre><p>To get a better understanding , lets check the configurations of the notificationJMSPublisher . This can be viewed by logging in to the carbon management console ( /carbon ) .</p><p>log in to carbon console with admin credentials and navigate to <strong>Manage &gt; Event &gt; Publishers</strong> and view the <strong>notificationJMSPublisher</strong> .</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MWKz-tPjW5qjPzvytTa0ZA.png" /></figure><p>As you can see <strong>notificationJMSPublisher </strong>is reading from the “<strong>org.wso2.apimgt.notification.stream:1.0.0</strong>” Event stream and publish to the “<strong>notification</strong>” topic of the broker.</p><p>Similarly you can check the <strong>notificationsWSO2EventReceiver</strong> configurations by navigating to <strong>Manage &gt; Event &gt; Receivers</strong></p><p>Now let’s see how we can verify if the <em>org.wso2.apimgt.notification.stream:1.0.0</em> contains the API notification .</p><p>For this we can introduce a new logger Event Publisher , just to read from the <em>org.wso2.apimgt.notification.stream:1.0.0</em> .</p><p>log in to carbon console with admin credentials and navigate to <strong>Manage &gt; Event &gt; Publishers</strong> and <strong>add event publisher</strong> .</p><ul><li>Enter a name ( notificationStreamLogger )</li><li>Under the Event Source, select <strong>org.wso2.apimgt.notification.stream:1.0.0</strong></li><li>Under the <strong>Output Event Adapter Type</strong> select <strong>Logger</strong></li><li>Add an Unique identifier as well ( notificationStreamLogger — → ) So it is easier to isolate the logs.</li><li>And click on <strong>Add Event Publisher</strong> to create the Event Publisher</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*A1OkHk8PaPLesmpidntjXA.png" /></figure><p>When the new logger event publisher is deployed , it will be indicated as follows in the control-plane’s log</p><pre>[2025-05-27 13:53:30,065]  INFO - EventPublisherConfigurationFilesystemInvoker Event Publisher configuration saved in the filesystem : notificationStreamLogger.xml<br>[2025-05-27 13:53:30,066]  INFO - EventJunction WSO2EventConsumer added to the junction. Stream:org.wso2.apimgt.notification.stream:1.0.0<br>[2025-05-27 13:53:30,067]  INFO - EventPublisherDeployer Event Publisher configuration successfully deployed and in active state : notificationStreamLogger</pre><p>Once the logger event publisher is deployed and if <em>org.wso2.apimgt.notification.stream:1.0.0</em> receive an API notification event , you should be able to see that in wso2carbon.log of control-plane as follows .</p><pre>[2025-05-27 13:59:21,869]  INFO - LoggerEventAdapter Unique ID: notificationStreamLogger----&gt;,<br>Event: eventType:DEPLOY_API_IN_GATEWAY,<br>timestamp:1748334561751,<br>event:eyJhcGlJZCI6MCwidXVpZCI6ImU1MjE0MzRhLTkwNzEtNDQ1Yi1iZDZmLWU3Y2RkMmVhNGFjNiIsIm5hbWUiOiJUZXN0QVBJIiwidmVyc2lvbiI6IjEuMCIsInByb3ZpZGVyIjoiYWRtaW4iLCJhcGlUeXBlIjoiSFRUUCIsImdhdGV3YXlMYWJlbHMiOlsiRGVmYXVsdCJdLCJhc3NvY2lhdGVkQXBpcyI6W10sImNvbnRleHQiOiIvdGVzdC8xLjAiLCJldmVudElkIjoiYTE4Mjg2YjQtZGFhYi00ZDhhLWI1ODktMDZmNGY0Y2ZjM2FiIiwidGltZVN0YW1wIjoxNzQ4MzM0NTYxNzUxLCJ0eXBlIjoiREVQTE9ZX0FQSV9JTl9HQVRFV0FZIiwidGVuYW50SWQiOjAsInRlbmFudERvbWFpbiI6ImNhcmJvbi5zdXBlciJ9</pre><p>Cool !! So far we have discussed various points we can track the event flow inside control-plane .</p><p>Lets move on to gateway and check how we can capture the events and troubleshoot further .</p><p>At the gateway startup it subscribes to the JMS topics of the broker component of control-plane . Hence it will receive the events from notification topic .</p><p>We can enable the following DEBUG logs at Gateway through log4j2.properties to log the events received .</p><pre>logger.GatewayJMSMessageListener.name = org.wso2.carbon.apimgt.gateway.listeners.GatewayJMSMessageListener<br>logger.GatewayJMSMessageListener.level = DEBUG</pre><p>You could see a similar DEBUG log as follows from the above</p><pre>[2025-05-27 13:59:23,168] DEBUG - GatewayJMSMessageListener Event received in JMS Event Receiver - Body:<br>{&quot;event&quot;:{&quot;payloadData&quot;:{&quot;eventType&quot;:&quot;DEPLOY_API_IN_GATEWAY&quot;,&quot;timestamp&quot;:1748334561751,&quot;event&quot;:&quot;eyJhcGlJZCI6MCwidXVpZCI6ImU1MjE0MzRhLTkwNzEtNDQ1Yi1iZDZmLWU3Y2RkMmVhNGFjNiIsIm5hbWUiOiJUZXN0QVBJIiwidmVyc2lvbiI6IjEuMCIsInByb3ZpZGVyIjoiYWRtaW4iLCJhcGlUeXBlIjoiSFRUUCIsImdhdGV3YXlMYWJlbHMiOlsiRGVmYXVsdCJdLCJhc3NvY2lhdGVkQXBpcyI6W10sImNvbnRleHQiOiIvdGVzdC8xLjAiLCJldmVudElkIjoiYTE4Mjg2YjQtZGFhYi00ZDhhLWI1ODktMDZmNGY0Y2ZjM2FiIiwidGltZVN0YW1wIjoxNzQ4MzM0NTYxNzUxLCJ0eXBlIjoiREVQTE9ZX0FQSV9JTl9HQVRFV0FZIiwidGVuYW50SWQiOjAsInRlbmFudERvbWFpbiI6ImNhcmJvbi5zdXBlciJ9&quot;}}}<br>JMS Correlation ID: null<br>JMS timestamp: 1748334562123<br>JMS expiration: 0<br>JMS priority: 4<br>JMS delivery mode: 2<br>JMS reply to: null<br>JMS Redelivered: false<br>JMS Destination: topic://amq.topic/notification/?routingkey=&#39;notification&#39;&amp;exclusive=&#39;true&#39;&amp;autodelete=&#39;true&#39;<br>JMS Type: null<br>JMS MessageID: ID:d2fab8ab-4ed8-331f-8452-c246b4ef99db<br>JMS Content-Type: text/plain<br>AMQ message number: 2<br>Properties:<br>        JMS_QPID_DESTTYPE = 2</pre><p>With this DEBUG logs we could verify if the event reached the Gateway .</p><p>Once the JMS event reached the gateway and the if gateway label in the event is matching , gateway will invoke the REST endpoints of control-plane to retrieve the API artefacts that need to be deployed.</p><p>We could trace this REST invocation by adding the following DEBUG logs at Gateway through log4j2.properties file .</p><pre>logger.http-wire.name = org.apache.http.wire<br>logger.http-wire.level = DEBUG</pre><p>From the above DEBUG logs , you can monitor the request and response content .</p><pre>[2025-05-28 13:50:59,877] DEBUG - wire http-outgoing-25 &gt;&gt; &quot;GET /internal/data/v1/runtime-artifacts?apiId=e521434a-9071-445b-bd6f-e7cdd2ea4ac6&amp;gatewayLabel=RGVmYXVsdA&amp;type=Synapse HTTP/1.1[\r][\n]&quot;<br>[2025-05-28 13:50:59,877] DEBUG - wire http-outgoing-25 &gt;&gt; &quot;Authorization: Basic YWRtaW46YWRtaW4=[\r][\n]&quot;<br>[2025-05-28 13:50:59,877] DEBUG - wire http-outgoing-25 &gt;&gt; &quot;xWSO2Tenant: carbon.super[\r][\n]&quot;<br>...<br>[2025-05-28 13:50:59,974] DEBUG - wire http-outgoing-25 &lt;&lt; &quot;HTTP/1.1 200 [\r][\n]&quot;<br>[2025-05-28 13:50:59,974] DEBUG - wire http-outgoing-25 &lt;&lt; &quot;X-WSO2-TraceId: 5ef9dd77-4595-4917-bed3-8d84ec7ea0fe[\r][\n]&quot;<br>[2025-05-28 13:50:59,974] DEBUG - wire http-outgoing-25 &lt;&lt; &quot;Date: Wed, 28 May 2025 08:20:59 GMT[\r][\n]&quot;<br>...</pre><p>The outgoing request can be tracked by ( &gt;&gt; ) logs and the incoming response content by ( &lt;&lt; ) logs .</p><p>Lastly, once the API is successfully deployed in the gateway , it will be indicated by a similar log as follows in the gateway’s wso2carbon.log</p><pre>[2025-05-28 13:51:00,069]  INFO - DependencyTracker Endpoint : TestAPI--v1.0_APIsandboxEndpoint was added to the Synapse configuration successfully<br>[2025-05-28 13:51:00,074]  INFO - DependencyTracker Endpoint : TestAPI--v1.0_APIproductionEndpoint was added to the Synapse configuration successfully<br>[2025-05-28 13:51:00,080]  INFO - API {api:TestAPI:v1.0} Initializing API: TestAPI:v1.0<br>[2025-05-28 13:51:00,080]  INFO - DependencyTracker API : TestAPI:v1.0 was added to the Synapse configuration successfully</pre><p>Alright, that’s a wrap for this blog !</p><p>As your deployment scales, I hope this post helps you understand the underlying configurations, behind-the-scenes processes, and key troubleshooting steps to isolate any API synchronization issues you may encounter.</p><p>Moreover, these troubleshooting steps aren’t limited to API syncing alone. They can also be applied to subscription synchronization issues.</p><p>Additionally, since WSO2 API Manager has adopted an event-driven architecture [2], the concepts discussed in this series are equally relevant for understanding Token Revocation, Throttle Policies, Key Manager deployments, Blocking Conditions, and more. Of course, these involve slight differences in configurations and use different event streams. Maybe we’ll explore those in a future blog post!</p><p>Good bye for now . Until next time, keep experimenting and keep exploring !! 👋 👋</p><p><strong>References :</strong></p><p>[1] <a href="https://medium.com/@akila95fernando/troubleshooting-api-sync-issues-in-wso2-api-manager-4-3-0-part-i-02f0d2e9aeaf">https://medium.com/@akila95fernando/troubleshooting-api-sync-issues-in-wso2-api-manager-4-3-0-part-i-02f0d2e9aeaf</a></p><p>[2] <a href="https://wso2.com/ibrary/articles/wso2-api-manager-embracing-event-driven-architecture/">https://wso2.com/ibrary/articles/wso2-api-manager-embracing-event-driven-architecture/</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4471729d5b80" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Troubleshooting API Sync Issues In WSO2 API Manager 4.3.0-Part I]]></title>
            <link>https://medium.com/@akila95fernando/troubleshooting-api-sync-issues-in-wso2-api-manager-4-3-0-part-i-02f0d2e9aeaf?source=rss-acce4f7d0988------2</link>
            <guid isPermaLink="false">https://medium.com/p/02f0d2e9aeaf</guid>
            <category><![CDATA[event-driven-architecture]]></category>
            <category><![CDATA[wso2-api-manager]]></category>
            <category><![CDATA[jms]]></category>
            <category><![CDATA[404]]></category>
            <category><![CDATA[wso2]]></category>
            <dc:creator><![CDATA[Akila Fernando]]></dc:creator>
            <pubDate>Wed, 28 May 2025 10:48:02 GMT</pubDate>
            <atom:updated>2025-05-28T11:41:47.935Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3swvrdiz_sp5JoZnD22gkg.png" /></figure><p>Hi WSO2 Enthusiasts ,</p><p>Is this a familiar error you see when an invoking a published API ?</p><pre>{&quot;code&quot;:&quot;404&quot;,&quot;type&quot;:&quot;Status report&quot;,&quot;message&quot;:&quot;Not Found&quot;,&quot;description&quot;:&quot;The requested resource is not available.&quot;}</pre><p>It’s a basic error — but a real head-scratcher. You see your API listed as <em>Published</em> in the Publisher Portal, yet when you try to invoke it, you get a 404. Frustrating, right?</p><p>Don’t worry! In this blog series, we’ll dive into what really happens behind the scenes when you publish an API through the WSO2 Publisher Portal.</p><p>Since there’s a lot to unpack, I’ll be breaking it down into two parts. Stay tuned!</p><p>In the series we will be covering,</p><p>1) What happens behind the scenes</p><p>2) Which configurations make it happen</p><p>3) How to troubleshoot and isolate the issues</p><p>First we are going to dive into the internals of API synching in WSO2 API Manager 4.3.0 .</p><p>Lets start with what happens behind the scenes . To get a better understanding , we will consider a distributed deployment of API Manager 4.3.0 which has a separate gateway ( GW ) and separate control-plane ( CP ).</p><p>Following sequence diagram depicts the series of actions executed . Let me walk you through each and every step along with the relevant configurations .</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HSh3s98nzgvGa0bcxF2K2g.png" /></figure><p>In the above diagram EventNotifier and JMSBroker are sub components of the control-plane . I have separated them out for the clarity .</p><p>Step 1)</p><p>Once the API publisher Create/Update an API at the publisher portal which is the control plane , it first updates the relevant database tables to persist the API information . For this control-plane requires the connection to both APIM and Shared DB . The configurations responsible for this is as follows at the control-plane deployment.toml .</p><pre>[database.shared_db]<br>…<br>[database.apim_db]<br>…</pre><p>Step 2)</p><p>Publishing an API will only make the API available at the devportal for subscription .</p><p>To be able to invoke the API it needs to be deployed at the gateway . Since WSO2 API manager caters the feasibility of configuring multiple gateway environments , API publisher need to select which gateway environment he needs to deploy the API .</p><p>You can check the configured gateway environments in the <strong>deployment.toml </strong>of control-plane as follows .</p><p>You can refer the official documentation [1] on configuring multiple gateway environments .</p><pre>[[apim.gateway.environment]]<br>name = &quot;Default&quot;<br>type = &quot;hybrid&quot;<br>display_in_api_console = true<br>description = &quot;This is a hybrid gateway&quot;<br>show_as_token_endpoint_url = true<br>service_url = &quot;https://[api-gateway-LB-host]/services/&quot;<br>ws_endpoint = &quot;ws://[api-gateway-LB-host-or-ip]:9099&quot;<br>wss_endpoint = &quot;wss://[api-gateway-LB-host-or-ip]:8099&quot;<br>http_endpoint = &quot;http://[api-gateway-LB-host]&quot;<br>https_endpoint = &quot;https://[api-gateway-LB-host]&quot;</pre><p>Once you select the gateway environment and deploy, Control-Plane will construct an event including the API metadata and intended gateway environment information .</p><p>The generated events are binary events and will utilize binary event streams to publish to the target endpoints . Lets discuss this at step 3 .</p><p>Step 3)</p><p>The generated binary event will be published to all the control planes in the deployment through the event streams .</p><p>So if you have configured high availability for control-plane, <strong>each</strong> <strong>CP node</strong> should have the configurations as follows in deployment.toml to be able to publish to every control plane in the cluster .</p><pre>[[apim.event_hub.publish.url_group]]<br>urls = [&quot;tcp://control-plane-1-host:9611&quot;]<br>auth_urls = [&quot;ssl://control-plane-1-host:9711&quot;]<br><br>[[apim.event_hub.publish.url_group]]<br>urls = [&quot;tcp://control-plane-2-host:9611&quot;]<br>auth_urls = [&quot;ssl://control-plane-2-host:9711&quot;]</pre><p>So far we have only discussed the execution flow inside the control-plane node . But to be able to invoke the APIs through gateway , gateway component should be informed about the API update .</p><p>For this communication WSO2 API Manager uses a pub-sub model between control-Plane and Gateway .</p><p>Lets dive into this at next steps .</p><p>Step 4)</p><p>Once the binary event is captured from EventReceivers , it will be put in to the relevant eventStream .</p><p>Reading from the eventStream control plane will construct a JMS Event and publish to it’s own broker component via respective Event publishers.</p><p>There are several pre registered Event publishers in WSO2 API-Manager which being deployed at the server startup. Each Event publisher has a event stream they are listening from and a destined topic where they publish the events to. <br>When it comes to the API updates it will be published through the “<strong>notificationJMSPublisher</strong>” . <br>The notificationJMSPublisher is configured to extract data from “<strong>org.wso2.apimgt.notification.stream:1.0.0</strong>” Event stream and publish to the “<strong>notification</strong>” topic of the broker.</p><p>In the part-2 we will look at the underlying event publisher configurations .</p><p>Step 5)</p><p>At the gateway startup, gateways subscribe to the topics of control-plane which allows the gateways to receive JMS events related to the API update events .</p><p>The Gateway will filter out the events by the Gateway label.</p><p>Gateway subscriptions to control plane’s broker is handled by the following configuration at <strong>gateway’s deployment.toml</strong></p><pre>[apim.event_hub]<br>event_listening_endpoints = [&quot;tcp://control-plane-1-host:5672&quot;, &quot;tcp://control-plane-2-host:5672&quot;]</pre><p>In a HA deployment of control-planes the subscription from gateway to control-plane will be a failover subscription .</p><p>In other words , if you have 2 control-planes as in above configurations it will only connect to the <strong>control-plane-1-host</strong> if connection is successful . In case of connection failure only it connects to the <strong>control-plane-2-host</strong> .</p><p>The label configurations of the gateway to filter out the events can be found by following configuration in <strong>gateway’s deployment.toml</strong></p><pre>[apim.sync_runtime_artifacts.gateway]<br>gateway_labels =[&quot;Default&quot;]</pre><p>The gateway_label is evaluated against the <strong>name</strong> under the <strong>[[apim.gateway.environment]] </strong>of control-plane ( refer step 2 ).</p><p>Step 6)</p><p>Now gateway has the information about the API updates made at control-plane .</p><p>By reading the received event metadata ( uuid ) gateway calls the REST API endpoints of the control-plane to retrieve the relevant synapse artefacts and metadata from the control-plane .</p><p>This REST invocation is constructed through the following configuration at the gateway .</p><pre>[apim.event_hub]<br>enable = true<br>username = &quot;$ref{super_admin.username}&quot;<br>password = &quot;$ref{super_admin.password}&quot;<br>service_url = &quot;https://[control-plane-LB-host]/services/&quot;</pre><p>Example :</p><pre>https://localhost:9443/internal/data/v1/runtime-artifacts?apiId=e521434a-9071-445b-bd6f-e7cdd2ea4ac6&amp;gatewayLabel=RGVmYXVsdA&amp;type=Synapse</pre><p>Step 7)</p><p>Control-plane will query the database and respond to the gateway .</p><p>Step 8)</p><p>Gateway will deploy the retrieved synapse artefacts and will be able to serve the API traffic .</p><p>Thats about it regarding the run time API sync in WSO2 API Manager .</p><p>If you are wondering about how APIs are deployed at gateway startup ,</p><p>At the gateway startup it calls the control-plane’s REST endpoints to fetch all the API artefacts from the Database and deploy them at the gateway .</p><p>Example :</p><pre>https://localhost:9443/internal/data/v1/runtime-artifacts?gatewayLabel=RGVmYXVsdA&amp;type=Synapse</pre><p>This is why even when you do not see the API changes reflected in gateway at runtime , but soon after gateway restart it starts to work .</p><p>As you could see , there are several important configurations and internal connections required to have a seamless API syncing in a distributed deployment . When the deployment scales up it is important to have an understanding on what configurations are responsible and make the adjustments.</p><p>You can refer to the configurations against standard deployment patterns in the official WSO2 documentation [2] .</p><p>Hope this post gave you an understanding on the behind scene process . Lets dive into the troubleshooting at each phase in the Part-II . [3]</p><p><strong>References :</strong></p><p>[1] <a href="https://apim.docs.wso2.com/en/4.3.0/deploy-and-publish/deploy-on-gateway/deploy-api/deploy-through-multiple-api-gateways/">https://apim.docs.wso2.com/en/4.3.0/deploy-and-publish/deploy-on-gateway/deploy-api/deploy-through-multiple-api-gateways/</a></p><p>[2] <a href="https://apim.docs.wso2.com/en/4.3.0/install-and-setup/setup/distributed-deployment/understanding-the-distributed-deployment-of-wso2-api-m/">https://apim.docs.wso2.com/en/4.3.0/install-and-setup/setup/distributed-deployment/understanding-the-distributed-deployment-of-wso2-api-m/</a></p><p>[3] <a href="https://medium.com/@akila95fernando/troubleshooting-api-sync-issues-in-wso2-api-manager-4-3-0-part-ii-4471729d5b80">https://medium.com/@akila95fernando/troubleshooting-api-sync-issues-in-wso2-api-manager-4-3-0-part-ii-4471729d5b80</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=02f0d2e9aeaf" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Bulk Update API Visibility Control in WSO2 API Manager 4.x.x]]></title>
            <link>https://medium.com/@akila95fernando/bulk-update-api-visibility-control-in-wso2-api-manager-4-x-x-aef919474670?source=rss-acce4f7d0988------2</link>
            <guid isPermaLink="false">https://medium.com/p/aef919474670</guid>
            <category><![CDATA[user-roles]]></category>
            <category><![CDATA[devportal-visibility]]></category>
            <category><![CDATA[wso2-api-manager]]></category>
            <category><![CDATA[wso2]]></category>
            <category><![CDATA[devportal]]></category>
            <dc:creator><![CDATA[Akila Fernando]]></dc:creator>
            <pubDate>Tue, 26 Nov 2024 11:42:53 GMT</pubDate>
            <atom:updated>2024-11-26T11:42:53.068Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*38IY-Fcx3jd_Tn9MkUKWrA.png" /></figure><p>Hey there ,</p><p>Today we are going to implement a REST client to bulk update the API visibility roles of APIs deployed in WSO2 API Manager .</p><p>This may sound a little too specific use case .</p><p>But , the same implementation can be used to bulk update APIs with any of the attributes you are interested in by altering the logic .</p><p>So, Hang tight !! And read till the end ! 😉😉</p><p>Let me explain the use case a bit more .</p><p>Once you publish an API through the publisher portal it will be visible to all the users who logs in to the devportal .</p><p>There could be scenarios , As an API publisher you want your APIs to be visible to a specific audience .</p><p>In such cases , the best option is to restrict the API visibility based on the Roles assigned to the users . [1]</p><p>While this can be achieved through the publisher portal UI , it could be cumbersome if you have to do it for each and every API .</p><p>Thats where our REST client can save your day . 💪💪💪</p><p>Let’s jump to the implementation now .</p><p>With the Introduction of API REVISIONS feature , the task has become a little complex . The basic flow of the REST client is as follows .</p><pre>Get all APIs<br>For each API <br>├── Get API details by passing ApiId<br>├── if API state is Created<br>│   └── Skip updating the API <br>└── if API state is Published<br>    ├── if API visibility is PUBLIC<br>    │   ├── Update Visibility as RESTRICTED<br>    │   └── Update VisibleRoles ( Remove or Add roles )<br>    ├── if API Visibility is RESTRICTED<br>    │   └── Update VisibleRoles ( Remove or Add roles )<br>    ├── Get List of Revisions for the API<br>    ├── Preserve Deployed GW information ( to handle multiple GW environments )<br>    ├── if ( Revision Count &lt; 5 )<br>    │   ├── Create a new Revision<br>    │   └── Deploy new Revision to all deployed GW environments<br>    └── if ( Revision Count &gt;= 5 )<br>        ├── Delete the oldest and Non-deployed Revision<br>        ├── Create new Revision<br>        └── Deploy new Revision to all deployed GW environments</pre><p>The implementation of the REST client can be found in the below github repo [2] .</p><p>Feel free to Fork and Try Out . All the instructions to run the client are mentioned in the README .</p><p>To summarise , following are the capabilities of the REST Client . This is tested with wso2am-4.1.0 .</p><p>1) Add visibility restriction roles for APIs</p><p>2) Remove visibility restriction roles for APIs</p><p>3) Explicitly update a given set of APIs</p><p>4) Update all APIs while skipping a given set of APIs</p><p>To use the CustomAPIUpdate with other 4.x.x versions makes sure to configure the correct PUBLISHER.REST.URL .</p><p>Voilaa 🎉🎉🎉 That’s it with this article . See you again with another 👋👋👋</p><h3><strong>References</strong></h3><p>[1] <a href="https://apim.docs.wso2.com/en/4.1.0/design/advanced-topics/control-api-visibility-and-subscription-availability-in-developer-portal/#control-api-visibility-in-the-developer-portal">https://apim.docs.wso2.com/en/4.1.0/design/advanced-topics/control-api-visibility-and-subscription-availability-in-developer-portal/#control-api-visibility-in-the-developer-portal</a></p><p>[2] <a href="https://github.com/akila95fernando/CustomAPIUpdater">https://github.com/akila95fernando/CustomAPIUpdater</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=aef919474670" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[CORS capabilities of WSO2 API Manager 4.x.x]]></title>
            <link>https://medium.com/@akila95fernando/cors-capabilitis-of-wso2-api-manager-4-x-x-ef9a9c6b20d2?source=rss-acce4f7d0988------2</link>
            <guid isPermaLink="false">https://medium.com/p/ef9a9c6b20d2</guid>
            <category><![CDATA[oauth]]></category>
            <category><![CDATA[cors]]></category>
            <category><![CDATA[cross-origin-resource]]></category>
            <category><![CDATA[wso2]]></category>
            <category><![CDATA[wso2-api-manager]]></category>
            <dc:creator><![CDATA[Akila Fernando]]></dc:creator>
            <pubDate>Sun, 27 Oct 2024 14:51:25 GMT</pubDate>
            <atom:updated>2024-10-27T15:27:59.534Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*bjDVyF2oWkgWgnNi" /><figcaption>Photo by <a href="https://unsplash.com/@markusspiske?utm_source=medium&amp;utm_medium=referral">Markus Spiske</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>Hey There,</p><p>Today we are going to talk about CORS capabilities of WSO2 API Manager 4.x.x versions .</p><h3><strong>So what does CORS mean ?</strong></h3><p>CORS (Cross-Origin Resource Sharing) is a security feature built into web browsers that controls how web applications can request resources from a different origin (domain, protocol, or port) than the one they’re hosted on.</p><p>From server’s perspective configuring CORS allows the server to control which external websites can access its resources, effectively “lifting” the restrictions of the same-origin policy under specific conditions.</p><p>Lets look into how WSO2 API Manager can be configured to allow CORS to it’s resources</p><p>With this blog we will discuss on applicable CORS configurations for each type of resources deployed in APIM Manager .</p><ul><li><strong>REST APIs published in the Gateway</strong></li><li><strong>Restful APIs provided by API Manager itself</strong> ( ex : Publisher , Devportal REST APIs )</li><li><strong>Oauth related endpoints of API Manager </strong>( Ex : /oauth2/token , /oauth2/userinfo ,… endpoints )</li></ul><p>Now lets see how to apply configurations at each level in detail</p><h3><strong>1. Applying CORS for APIs published in Gateway</strong></h3><p>CORS will be handled by a handler called CORSRequestHandler [1] which engages at each API execution by default .</p><p>We can enable CORS globally for all the APIs or At each API .</p><p>To enable CORS globally we can add the following configurations at deployment.toml file .</p><pre>[apim.cors]<br>enable = true<br>allow_origins = &quot;*&quot;<br>allow_methods = [&quot;GET&quot;,&quot;PUT&quot;,&quot;POST&quot;,&quot;DELETE&quot;,&quot;PATCH&quot;,&quot;OPTIONS&quot;]<br>allow_headers = [&quot;authorization&quot;,&quot;Access-Control-Allow-Origin&quot;,&quot;Content-Type&quot;,&quot;SOAPAction&quot;,&quot;apikey&quot;,&quot;Internal-Key&quot;]<br>allow_credentials = false</pre><p>🛑 <strong><em>Note :</em></strong> CORS configuration is enabled by default. Access control can be done by changing the parameters mentioned above in the <strong>deployment.toml</strong> file.</p><p>To enable CORS at each API level , we can do it at the publisher configurations .</p><p>You can navigate to the <strong>/publisher</strong> portal and select the particular API you want to enforce CORS<br>Then navigate to <strong><em>API Configuration &gt; Runtime &gt; CORS Configuration</em></strong> and add the parameters .</p><p>🛑 <strong><em>Note : </em></strong>To enforce CORS at API level you need to enable the CORS globally first .</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5hpIwTiIgP5UMano7j9-cA.png" /><figcaption>Per API CORS Configurations</figcaption></figure><p>🛑 <strong><em>Note :</em></strong> AllowedOrigins also support the simple Regex .</p><p>For an example if you want both the <a href="https://foo.bar.com/">https://foo.bar.com</a> and <a href="https://abc.bar.com/">https://abc.bar.com</a> to allow, you can set <a href="https://*.bar.com/"><strong><em>https://*.bar.com</em></strong></a> as the allowed origin .</p><h3><strong>2. Applying CORS for RESTFUL APIs provided by API manager</strong></h3><p>By default, each of the Product REST APIs (except Admin v2 REST API) allows requests from all origins.</p><p>However , If you are using custom web portals , built using Internal RESTFUL APIs provided by API Manger there can be use cases you need to restrict specific domains to access the RESTFUL APIs . ( For an example publisher REST APIs [2] )</p><p>To cater this WSO2 API manager provides 2 Methods .</p><p><strong>Method 1 )</strong> — Specify the allowed origins in the deployment.toml file under [system.parameter]</p><p>Following is a sample configuration to be added to the deployment.toml file</p><pre>[system.parameter]<br>&#39;rest.api.publisher.allowed.origins&#39; = &quot;https://abc.com&quot;<br>&#39;rest.api.devportal.allowed.origins&#39; = &quot;https://abc.com,https://xyz.com&quot;<br>&#39;rest.api.gateway.allowed.origins&#39; = &quot;https://abc.com,https://xyz.com&quot;<br>&#39;rest.api.service.catalog.allowed.origins&#39; = &quot;https://abc.com&quot;</pre><p><strong>Method 2 )</strong> — Specify the allowed origins when starting the server</p><p>You can pass the specific Origins via the server startup script . <br>( for an example &lt;AM_HOME&gt;/bin/api-manger.sh for linux servers )</p><p>Following is a sample configuration to be added to the api-manager.sh file</p><pre>-Drest.api.publisher.allowed.origins=https://abc.com \<br>-Drest.api.devportal.allowed.origins=https://abc.com,https://xyz.com \<br>-Drest.api.gateway.allowed.origins=https://abc.com,https://xyz.com \<br>-Drest.api.service.catalog.allowed.origins=https://abc.com</pre><h3><strong>3. Applying CORS for Oauth related endpoints</strong></h3><p>There are several approaches to facilitate this .</p><p>If you have worked with older WSO2 API Manager versions ( wso2am-3.x.x ), all the Oauth related endpoints were exposed via the Gateway as well using proxy APIs . It was exposed as <em>https://&lt;GW_HOST&gt;:8243/token </em>which redirects the traffic to <em>https://&lt;KM_HOST&gt;:9443/oauth2/token</em> internally .</p><p>You could find these proxy APIs at<em> wso2am-3.2.0/repository/deployment/server/synapse-configs/default/api</em> directory .</p><p>Since these are Gateway APIs , we could manually engage the <strong>CORSRequestHandler</strong> as documented at [3] .</p><p>However , from WSO2 API Manager 4.0.0 onwards , the API synapse artifacts are stored at database and you won’t be able to find the proxy API files at the above location . And these endpoints are not exposed via gateway ports by default .</p><p><strong>Approach 1 )</strong> — Creating the proxy APIs for each Oauth2 endpoints .</p><p>Similar to wso2am-3.x.x versions , we can manually create a Proxy API in file system and engage the CORSRequestHandler .</p><p>Following are the steps to do so .</p><ul><li>Navigate to <strong>wso2am-4.0.0/repository/deployment/server/synapse-configs/default/api</strong> directory</li><li>Create the<strong> _TokenAPI.xml</strong> with below content ( I have added sample CORS configuration parameters )</li></ul><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;<br>&lt;api xmlns=&quot;http://ws.apache.org/ns/synapse&quot;<br>     name=&quot;_WSO2AMTokenAPI_&quot;<br>     context=&quot;/token&quot;<br>     binds-to=&quot;default&quot;&gt;<br>   &lt;resource methods=&quot;POST&quot;<br>             binds-to=&quot;default&quot;<br>             url-mapping=&quot;/*&quot;<br>             faultSequence=&quot;_token_fault_&quot;&gt;<br>      &lt;inSequence&gt;<br>         &lt;send&gt;<br>            &lt;endpoint&gt;<br>               &lt;!-- you can change the token endpoint --&gt;<br>               &lt;http uri-template=&quot;https://localhost:9443/oauth2/token&quot;&gt;<br>                  &lt;timeout&gt;<br>                     &lt;duration&gt;60000&lt;/duration&gt;<br>                     &lt;responseAction&gt;fault&lt;/responseAction&gt;<br>                  &lt;/timeout&gt;<br>               &lt;/http&gt;<br>            &lt;/endpoint&gt;<br>         &lt;/send&gt;<br>      &lt;/inSequence&gt;<br>      &lt;outSequence&gt;<br>         &lt;send/&gt;<br>      &lt;/outSequence&gt;<br>   &lt;/resource&gt;<br>   &lt;handlers&gt;<br>      &lt;handler class=&quot;org.wso2.carbon.apimgt.gateway.handlers.security.CORSRequestHandler&quot;&gt;<br>         &lt;property name=&quot;apiImplementationType&quot; value=&quot;ENDPOINT&quot;/&gt;<br>         &lt;property name=&quot;allowHeaders&quot;<br>                   value=&quot;authorization,Access-Control-Allow-Origin,Content-Type,SOAPAction,apikey,testKey&quot;/&gt;<br>         &lt;property name=&quot;allowedOrigins&quot; value=&quot;http://abc.com&quot;/&gt;<br>         &lt;property name=&quot;allowedMethods&quot; value=&quot;POST,PATCH,OPTIONS&quot;/&gt;<br>      &lt;/handler&gt;<br>      &lt;handler class=&quot;org.wso2.carbon.apimgt.gateway.handlers.common.SynapsePropertiesHandler&quot;/&gt;<br>   &lt;/handlers&gt;<br>&lt;/api&gt;</pre><ul><li>Add the following config to <strong>wso2am-4.0.0/repository/conf/deployment.toml</strong></li></ul><pre>[apim.sync_runtime_artifacts.gateway.skip_list]<br>apis = [&quot;_TokenAPI_.xml&quot;] # if you are proxying multiple APIs , add them as a list ( Ex : [&quot;_TokenAPI_.xml&quot;,&quot;_UserInfoAPI_.xml&quot;] )</pre><ul><li>Restart the server</li></ul><p>Now the CORS will be enforce when you invoke the /token endpoint via Gateway<br>Ex : <em>https://&lt;GW_HOST&gt;:8243/token</em></p><p>But not via the actual Oauth endpoint<br>Ex : <em>https://&lt;KM_HOST&gt;:9443/oauth2/token</em></p><p><strong>Approach 2 ) — Publish an API and use the Oauth2 endpoints as the backend .</strong></p><p>If you don’t want the file based APIs as in approach 1 , you can create an API through the publisher portal and redirect the traffic to the <em>/Oauth2</em> endpoints by setting it as the backend .</p><p>Make sure you are disabling the security [4] for each resource of the API .</p><p>With this API , you can enforce the CORS configurations as we have done during enabling CORS at API level .</p><p>However , If you are using multi-tenancy this will not be the most ideal approach as the API context will be different for each tenant .</p><p>Also , with this approach as well , the direct oauth2 endpoint ( Ex : <em>https://&lt;KM_HOST&gt;:9443/oauth2/token</em> ) will not enforce the CORS.</p><p><strong>Approach 3 ) — Modifying the Oauth2 webapp</strong></p><p>If you do not want to proxy the APIs and want to enforce the CORS on direct /oauth2 endpoints , following approach is more suitable .</p><ul><li>Navigate to the <strong><em>&lt;APIM_HOME&gt;/repository/deployment/server/webapps/oauth2/WEB-INF</em></strong> directory and open the <strong><em>web.xml </em></strong>file.</li><li>Add the following content inside <strong><em>&lt;web-app version=”2.5&quot; ……&gt; &lt;/web-app&gt;</em></strong> tags and save the file.</li></ul><pre>&lt;filter&gt;<br>   &lt;filter-name&gt;CORS&lt;/filter-name&gt;<br>   &lt;filter-class&gt;com.thetransactioncompany.cors.CORSFilter&lt;/filter-class&gt;<br>   &lt;init-param&gt;<br>      &lt;param-name&gt;cors.allowOrigin&lt;/param-name&gt;<br>      &lt;param-value&gt;https://abc.com&lt;/param-value&gt;<br>   &lt;/init-param&gt;<br>   &lt;init-param&gt;<br>      &lt;param-name&gt;cors.supportedMethods&lt;/param-name&gt;<br>      &lt;param-value&gt;GET, POST, HEAD, PUT, DELETE, OPTIONS&lt;/param-value&gt;<br>   &lt;/init-param&gt;<br>   &lt;init-param&gt;<br>      &lt;param-name&gt;cors.supportedHeaders&lt;/param-name&gt;<br>      &lt;param-value&gt;authorization,Access-Control-Allow-Origin,Content-Type,SOAPAction,apikey&lt;/param-value&gt;<br>   &lt;/init-param&gt;<br>&lt;/filter&gt;<br>&lt;filter-mapping&gt;<br>   &lt;filter-name&gt;CORS&lt;/filter-name&gt;<br>   &lt;url-pattern&gt;*&lt;/url-pattern&gt;<br>&lt;/filter-mapping&gt;</pre><p>With this approach you can configure CORS for all the <strong>/oauth2 </strong>endpoints such as <strong><em>oauth2/token , oauth2/userinfo … </em></strong>at once .</p><p>Also , this will enforce CORS to the direct /oauth2 endpoints itself .</p><p>Cool !!!</p><p>That’s about it for CORS capabilities of WSO2 API Manager .</p><p>Now lets answer few of the commonly asked questions .</p><h3><strong>FAQ !</strong></h3><p><strong>1) I don’t need API Manger to handle CORS , I would like my backend to handle CORS . How Can I enforce that ? </strong>🤯🤯</p><p>Simple ! All you have to do is to create an <strong>OPTIONS</strong> Resource explicitly .</p><p>Afterwards , once the preflight request reaches the API Gateway , it will just passthrough the request to the backend . Backend can enforce the CORS related headers and send back to client through APIM .</p><p><strong>2) How can I test CORS are applied correctly ? </strong>🤔🤔</p><p>You can manually trigger a preflight request ( OPTIONS ) using a command line tool such as CURL with the required headers and trace the response headers .</p><p>For an example , I have an API called <strong>/abc </strong>deployed in API manager . And I have enforced the CORS at API level and restricted the allowedOrigin as <a href="https://abc.com/"><em>https://abc.com</em></a> .</p><p>Following Is a sample CURL to verify it .</p><pre>curl --location --request OPTIONS &#39;https://localhost:8243/abc/1&#39; \<br>--header &#39;access-control-request-method: GET&#39; --header &#39;Origin : https://abc.com&#39; -kv  <br><br>Response headers <br><br>&lt; HTTP/1.1 200 OK<br>&lt; Origin: https://abc.com<br>&lt; Access-Control-Expose-Headers: <br>&lt; Accept: */*<br><strong>&lt; Access-Control-Allow-Origin: https://abc.com</strong><br>&lt; Access-Control-Allow-Methods: GET<br>&lt; Host: localhost:8243<br>&lt; access-control-request-method: GET<br>&lt; Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Content-Type,SOAPAction,apikey,Internal-Key,Authorization</pre><p>If you sent an invalid domain from the request , the response will contain an empty <strong>Access-Control-Allow-Origin header</strong></p><p><strong>3) How can I troubleshoot the CORS errors ? </strong>🤠🤠</p><p>If you come across a CORS error , enable the browser inspection and check the console tab . It will have some clues on the exact issue .</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AE_D7A4rErtnssNK19huNQ.png" /><figcaption>CORS troubleshooting</figcaption></figure><p>🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐🧐</p><p>I think I have Covered many aspects of CORS in WSO2 APIM .</p><p>Please checkout the WSO2 API Manager Documentation [5] [6] as well .</p><p>Catch you later with a new Blog !</p><p>Adios !! 👋👋👋👋</p><p><strong>References</strong></p><p>[1] <a href="https://github.com/wso2/carbon-apimgt/blob/v9.0.174/components/apimgt/org.wso2.carbon.apimgt.gateway/src/main/java/org/wso2/carbon/apimgt/gateway/handlers/security/CORSRequestHandler.java">https://github.com/wso2/carbon-apimgt/blob/v9.0.174/components/apimgt/org.wso2.carbon.apimgt.gateway/src/main/java/org/wso2/carbon/apimgt/gateway/handlers/security/CORSRequestHandler.java</a></p><p>[2] <a href="https://apim.docs.wso2.com/en/4.0.0/reference/product-apis/publisher-apis/publisher-v2/publisher-v2/">https://apim.docs.wso2.com/en/4.0.0/reference/product-apis/publisher-apis/publisher-v2/publisher-v2/</a></p><p>[3] <a href="https://apim.docs.wso2.com/en/3.2.0/learn/design-api/advanced-topics/enabling-cors-for-apis/#enabling-cors-for-oauth-token-related-apis">https://apim.docs.wso2.com/en/3.2.0/learn/design-api/advanced-topics/enabling-cors-for-apis/#enabling-cors-for-oauth-token-related-apis</a></p><p>[4] <a href="https://apim.docs.wso2.com/en/4.0.0/deploy-and-publish/deploy-on-gateway/choreo-connect/security/api-authentication/disabling-security/">https://apim.docs.wso2.com/en/4.0.0/deploy-and-publish/deploy-on-gateway/choreo-connect/security/api-authentication/disabling-security/</a></p><p>[5] <a href="https://apim.docs.wso2.com/en/4.0.0/design/advanced-topics/enabling-cors-for-apis/#enabling-cors-for-apis">https://apim.docs.wso2.com/en/4.0.0/design/advanced-topics/enabling-cors-for-apis/#enabling-cors-for-apis</a></p><p>[6] <a href="https://apim.docs.wso2.com/en/4.0.0/reference/product-apis/advanced-configurations/#configuring-allowed-origins">https://apim.docs.wso2.com/en/4.0.0/reference/product-apis/advanced-configurations/#configuring-allowed-origins</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ef9a9c6b20d2" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How Endpoint Certificates Are Managed In WSO2 API Manager 4.x.x]]></title>
            <link>https://medium.com/@akila95fernando/how-endpoint-certificates-are-managed-in-wso2-api-manager-4-x-x-dcbf83d73a88?source=rss-acce4f7d0988------2</link>
            <guid isPermaLink="false">https://medium.com/p/dcbf83d73a88</guid>
            <category><![CDATA[self-signed-certificate]]></category>
            <category><![CDATA[ssl]]></category>
            <category><![CDATA[wso2]]></category>
            <category><![CDATA[endpoint-security]]></category>
            <category><![CDATA[wso2-api-manager]]></category>
            <dc:creator><![CDATA[Akila Fernando]]></dc:creator>
            <pubDate>Wed, 24 Apr 2024 21:12:30 GMT</pubDate>
            <atom:updated>2024-04-24T21:12:30.959Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*PbSjPMp_yzuKZnZz" /><figcaption>Photo by <a href="https://unsplash.com/@casparrubin?utm_source=medium&amp;utm_medium=referral">Caspar Camille Rubin</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>Hey There,</p><p>Today we are going to talk about how backend endpoint certificates are managed in WSO2 API Manager 4.x.x versions .</p><p>In this blog we will discuss the below topics</p><ul><li>how backend certificates uploaded via publisher portal sync in to the gateway</li><li>demonstrate the certificate issue and rectify</li><li>How to troubleshot the issues that may occur along with the required debug logs</li><li>Frequently asked questions and resolutions for them</li></ul><p>If your Backend is SSL protected, to establish successful connection via TLS to the backend , Gateway should ensure the public certificate of the server is trusted by the gateway .</p><p>For this , when publishing an API via the publisher UI , WSO2 API Manager provides a UI option to upload the relevant public certificates .</p><p>Lets explore the step-by-step process behind this synchronization when you add an certificate to the API Endpoint via publisher portal .</p><p><em>In this article , I am using WSO2 API Manager 4.0.0 version to demonstrate the behavior .<br>Note that the api manager deployment used here is a distributed deployment which contains 2 nodes . [1]</em></p><ul><li><em>Control Plane Node</em></li><li><em>Gateway Node</em></li></ul><p>Inside the Control Plane node reside the Publisher , Devportal , Traffic Manager and Key Manager components.</p><p>Following diagram mimics the key components and steps involved in the process .</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/766/1*Bj3ZMvd5pmQWC7Rxn2v03w.png" /></figure><ol><li>When the certificate is added via the publisher portal with an alias it get stored in the <strong>AM_CERTIFICATE_METADATA</strong> table of <strong>APIM_DB</strong></li><li>Publisher component publish an event to the TM component ( which acts as the Event Hub ) via the following configuration in <strong>CP node’s deployment.toml</strong></li></ol><pre>[[apim.event_hub.publish.url_group]]<br>urls = [&quot;tcp://control-plane-1-host:9611&quot;]|<br>auth_urls = [&quot;ssl://control-plane-1-host:9711&quot;]</pre><p>3. Gateway nodes subscribing to the TM/Event_HUB retrieve these events . This event listening happens through the following configuration at <strong>GW node’s depolyment.toml</strong></p><pre>[apim.throttling]<br>throttle_decision_endpoints = [&quot;tcp://control-plane-host:5672&quot;]</pre><p>The event contains the endpoint and certificate alias and other metadata . We will log a sample event later in this article . Just keep going for now 🏃</p><p>4. Gateway nodes invoke the following REST API exposed at Control Plane node to get certificate . Control Plane fetch the certificate from database and respond to the gateway .</p><pre>GET /internal/data/v1/endpoint-certificates?alias=&lt;cert_alias&gt;</pre><p>To invoke the above , gateway finds the Control Plane Host from the following configuration at <strong>GW deployment.toml</strong></p><pre>[apim.throttling]<br>service_url = &quot;https://control-plane-host:${mgt.transport.https.port}/services/&quot;</pre><p>5. The returned certificate is added to the <strong>client-truststore-temp.jks </strong>of GW.</p><p>6. Then the certificate is loaded to the https sender transport of gateway</p><p>Alright, let’s roll up our sleeves and dive into some hands-on action to really get a feel for how things work.</p><p><strong>Our first mission?</strong> To reproduce a scenario where the gateway hits a roadblock in establishing a secure connection, all because of a missing certificate.</p><p>Lets create a backend protected by a selfsigned certificate .</p><p>Please follow the below blog [2] , where I have created a mock backend and secured the service using selfsigned certifcate .</p><p><a href="https://medium.com/@akila95fernando/creating-a-secure-mock-backend-using-a-self-signed-certificate-c0c30e7bee37">https://medium.com/@akila95fernando/creating-a-secure-mock-backend-using-a-self-signed-certificate-c0c30e7bee37</a></p><p>We will use the same backend and same public certificate for this</p><p>Expose the backend via an API from publisher portal . <br>Lets not add the public certifcate to the endpoint yet as we are going to mimic an error .</p><p>Publish the API and subscribe it from an application . Generate an access token and invoke the API .</p><p>From the<strong> wso2carbon.log</strong> of Gateway node you will see the following error trace , Complaining about a missing certificate.</p><pre>[2024-04-14 13:24:54,551]  WARN - TargetHandler ERROR_CODE = 101500, STATE_DESCRIPTION = Exception occurred when Server establishing a connection to the backend, INTERNAL_STATE = REQUEST_READY, DIRECTION = REQUEST, CAUSE_OF_ERROR = I/O exception : PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target, TARGET_HOST = 127.0.0.1, TARGET_PORT = 3000, TARGET_CONTEXT = https://www.example.com:3000/abc, HTTP_METHOD = GET, TRIGGER_TYPE = api, TRIGGER_NAME = Demo:v1.0, REMOTE_ADDRESS = www.example.com/127.0.0.1:3000, CORRELATION_ID = 541c2146-080f-4689-8731-11bb88bd64a2, CONNECTION = http-outgoing-2<br>[2024-04-14 13:24:54,552] ERROR - TargetHandler I/O error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target, CORRELATION_ID = 541c2146-080f-4689-8731-11bb88bd64a2<br>javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target<br>...</pre><p>To resolve the issue lets upload the public certificate of backend to the endpoint certificates via the publisher portal .</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*BNoWwHsHnSpmhZdkfnNxcQ.png" /></figure><p>Now if we invoke the API we would get the intended response from backend.</p><p>Alright , Now we know how to overcome the issue . Lets dive into how to troubleshoot the behind the scenes process at each layer .</p><p>First lets see if the certificate is stored in the database by querying thew APIM_DB</p><pre>SELECT * FROM AM_CERTIFICATE_METADATA WHERE ALIAS=&quot;test1&quot; ;<br>...........................................................<br><br>TENANT_ID   ALIAS   END_POINT                      CERTIFICATE<br>-1234       test1   https://www.example.com:3000/  4c5330744c5….</pre><p>Note : certificate is stored as a BLOB . So you will get a Hex string in Certificate column.</p><p>lets enable following DEBUG logs at <strong>gateway</strong> via <strong>log4j2.properties</strong> file to track the receiving events .</p><pre>loggers = http-wire, event_logs, AUDIT_LOG, …<br><br># to check if the events are received by the gateway<br>logger.event_logs.name = org.wso2.carbon.apimgt.gateway<br>logger.event_logs.level = DEBUG<br><br># to track the CP response when GW invoke the REST API<br>logger.http-wire.name = org.apache.http.wire<br>logger.http-wire.level = DEBUG</pre><p>With the above logs enabled , if you upload a certificate from publisher portal , you will see the following logs populated in <strong>wso2carbon.log</strong> of GW .</p><pre><strong># The Event Received</strong><br>DEBUG - GatewayJMSMessageListener Event received in JMS Event Receiver - Body:<br>{&quot;event&quot;:{&quot;payloadData&quot;:{&quot;eventType&quot;:&quot;ENDPOINT_CERTIFICATE_ADD&quot;,&quot;timestamp&quot;:1713985379555,&quot;event&quot;:&quot;eyJhbG...LCJ&quot;}}}<br>JMS Correlation ID: null<br>JMS timestamp: 1713985379578<br>JMS expiration: 0<br>JMS priority: 4<br>JMS delivery mode: 2<br>JMS reply to: null<br>JMS Redelivered: false<br>JMS Destination: topic://amq.topic/notification/?routingkey=&#39;notification&#39;&amp;exclusive=&#39;true&#39;&amp;autodelete=&#39;true&#39;<br>JMS Type: null<br>JMS MessageID: ID:3d484942-1c8f-399e-83b1-f969f2926002<br>JMS Content-Type: text/plain<br>AMQ message number: 3<br>Properties:<br>        JMS_QPID_DESTTYPE = 2<br><br>[2024-04-25 00:33:00,269] DEBUG - GatewayJMSMessageListener Event received from the topic of notification<br><br><strong># The Rest API invocation</strong><br>[2024-04-25 00:33:00,302] DEBUG - wire http-outgoing-21 &gt;&gt; &quot;GET /internal/data/v1/endpoint-certificates?alias=test1 HTTP/1.1[\r][\n]&quot;<br>[2024-04-25 00:33:00,302] DEBUG - wire http-outgoing-21 &gt;&gt; &quot;Authorization: Basic YWRtaW46YWRtaW4=[\r][\n]&quot;<br>...<br>[2024-04-25 00:33:00,307] DEBUG - wire http-outgoing-21 &lt;&lt; &quot;HTTP/1.1 200 [\r][\n]&quot;<br>...<br><br><strong># Adding the certificate to gateway truststore</strong><br>[2024-04-25 00:33:00,320]  INFO - CertificateManagerImpl The Transport Sender will be re-initialized in few minutes.<br>[2024-04-25 00:33:00,320]  INFO - CertificateManagerImpl The certificate with Alias &#39;test1&#39; is successfully added to the Gateway Trust Store.<br><br><strong># Reloading the transport layer with added certificate</strong><br>[2024-04-25 00:38:58,707]  INFO - PassThroughHttpSSLSender PassThroughHttpSender reloading SSL Config..<br>[2024-04-25 00:38:58,722]  INFO - ClientConnFactoryBuilder customSSLProfiles configuration is loaded from path: /xxx/wso2am-4.0.0/repository/resources/security/sslprofiles.xml<br>[2024-04-25 00:38:58,722]  INFO - ClientConnFactoryBuilder HTTPS Loading custom SSL profiles for the HTTPS sender<br>[2024-04-25 00:38:58,730]  INFO - ClientConnFactoryBuilder HTTPS Custom SSL profiles initialized for 1 servers<br>[2024-04-25 00:38:58,731]  INFO - PassThroughHttpSSLSender Pass-through HTTPS Sender updated with Dynamic Configuration Updates ...<br>...</pre><p>From the above DEBUG logs we could troubleshoot if any issues faced during the certificate addition flow .</p><p>If you cannot narrow down the issue via the above debug logs , then here are more tips .</p><ol><li>Getting the public key chain of the backend . <br>You can execute the following command to retrieve the certificate chain of backend . And then compare if the public certificate you have uploaded via portal is a valid one .</li></ol><pre>openssl s_client -showcerts -connect &lt;back_end_host:port&gt;</pre><p>2. Enabling SSL Debug logs at Gateway . <br>As a last resort ,we can enable SSL Debug logs at gateway [3] to track the flow of ssl handshake . This will print all the steps of SSL handshake in detail .</p><p>Now lets move onto Frequently Asked Questions . I think you might have at least one of the following questions in your head . 😉</p><h4>FAQ</h4><h4><strong>1. Do I have to add the public certificate of backend each and every time I deploy an API ?</strong></h4><p>No .</p><p>The WSO2 Api Manager is shipped with a default trust store called <strong>client-truststore.jks</strong> . This keystore includes most of the Root certificates from known CAs . Hence if your backend has a certificate signed by one of the above CA’s you do not have to add the endpoint certificate via the publisher .</p><p>Further , as explained once a certificate is added via the publisher it gets bound to the underlying transport layer . Hence if you deploy another API with the same backend domain , the certificate will be picked from the previously uploaded API.</p><p><strong>2. What is the difference between <em>client-truststore.jks</em> and<em> client-truststore-temp.jks</em></strong></p><p><strong>client-truststore.jks</strong> is the keystore shipped by default including CA certificates .</p><p><strong>client-truststore-temp.jks</strong> is dynamically created during Gateway startup . At each startup existing client-truststore-temp.jks will get destroyed and create a new one . The creation process has 2 steps .</p><ul><li>Copy all the certificates from client-truststore.jks</li><li>Get all the certificates from the AM_CERTIFICATE_METADATA table and append . For this also GW calls the following REST API of CP at startup <br><em>GET /internal/data/v1/endpoint-certificates</em></li></ul><p><strong>3) Can I manually add a certificate to the client-truststore-temp.jks</strong></p><p>No.</p><p>As the <strong>client-truststore-temp.jks</strong> is destroyed at each gateway startup manually added certificates will not persist .</p><p>Hence if there is a requirement to manually add the certificates , you need to add them to the <strong>client-truststore.jks</strong> and <strong>restart the gateway</strong> . <br>Since client-truststore.jks is getting copied to the client-truststore-temp.jks at startup , it will persist the manually added certificate.</p><p>Well , Thats it from this article . we wrap up our journey through the intricacies of backend certificate management in WSO2 API Manager.</p><p>Hope you have learned something and it will help you troubleshoot the issues .</p><p>Thank you and see you soon with another article .</p><p>Until next time, keep experimenting and keep exploring !! 👋 👋</p><p><strong>References :</strong></p><p>[1] <a href="https://apim.docs.wso2.com/en/4.0.0/install-and-setup/setup/distributed-deployment/deploying-wso2-api-m-in-a-distributed-setup/">https://apim.docs.wso2.com/en/4.0.0/install-and-setup/setup/distributed-deployment/deploying-wso2-api-m-in-a-distributed-setup/</a></p><p>[2] <a href="https://medium.com/@akila95fernando/creating-a-secure-mock-backend-using-a-self-signed-certificate-c0c30e7bee37">https://medium.com/@akila95fernando/creating-a-secure-mock-backend-using-a-self-signed-certificate-c0c30e7bee37</a></p><p>[3] <a href="https://dilsichandrasena.medium.com/how-to-enable-ssl-debug-logs-for-wso2-products-6de7276ffe10">https://dilsichandrasena.medium.com/how-to-enable-ssl-debug-logs-for-wso2-products-6de7276ffe10</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=dcbf83d73a88" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Creating a Secure Mock Backend Using a Self Signed Certificate]]></title>
            <link>https://medium.com/@akila95fernando/creating-a-secure-mock-backend-using-a-self-signed-certificate-c0c30e7bee37?source=rss-acce4f7d0988------2</link>
            <guid isPermaLink="false">https://medium.com/p/c0c30e7bee37</guid>
            <category><![CDATA[mockoon]]></category>
            <category><![CDATA[self-signed-certificate]]></category>
            <category><![CDATA[ssl]]></category>
            <dc:creator><![CDATA[Akila Fernando]]></dc:creator>
            <pubDate>Tue, 16 Apr 2024 21:24:23 GMT</pubDate>
            <atom:updated>2024-04-17T04:14:35.931Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*gl5kc0SxFo9LvSuN" /><figcaption>Photo by <a href="https://unsplash.com/@6heinz3r?utm_source=medium&amp;utm_medium=referral">Gabriel Heinzer</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>Hey there!</p><p>Ever found yourself in need of a mock backend, wrapped snugly in SSL, for your testing endeavours? Well, today’s your lucky day because we’re diving headfirst into creating exactly that using <strong>Mockoon</strong>!</p><p>Now, what’s Mockoon, you ask? It’s the superhero of mock API services, a free and open-source tool that’s as easy as pie to use. Plus, it’s cross-platform, so everyone gets a slice of the action.</p><p>Let’s paint the picture:</p><ol><li><strong>Install Mockoon:</strong> First things first, get Mockoon up and running. [1]</li><li><strong>Add a New API:</strong> Just a few clicks and you’re there. [2]</li></ol><p>But hey, don’t take my word for it. The real magic lies in the detailed instructions in Mockoon’s documentation [2]. Trust me, it’s a breeze.</p><p>By default Mockoon serves your API on localhost port 3000 .<br>Since we are going to test the SSL we will change the hostname to a different one .</p><p>For the below test I am setting the hostname as <a href="http://www.example.com/">www.example.com</a> . Which I have mapped to the<strong> 127.0.0.1</strong> IP address using my computer’s <strong>/etc/hosts</strong> file .</p><pre>127.0.0.1      www.example.com</pre><p>Please refer the below screenshots for the API configurations . In here I have created a route/resource named <strong>/abc</strong> . Which will output a json response <strong>{“hello”:”world”}</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wFSg7Ru0L-isjJPy32p5kA.png" /><figcaption>Routes</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QiCP_RNYW4cg5zUA29mV4g.png" /><figcaption>API settings</figcaption></figure><p>Now, just to make sure our service is working fine lets start the service and invoke the API .</p><p>As we have not enabled SSL yet this API will be served over <strong>HTTP </strong>protocol via<strong> </strong><a href="http://www.example.com/"><strong>www.example.com</strong></a> host and <strong>3000 </strong>port by default .</p><p>To verify we will execute the following <strong>curl command</strong> and it should retrun the response as follows.</p><pre><strong>% curl http://www.example.com:3000/abc</strong><br>{&quot;hello&quot;:&quot;world&quot;}</pre><p>Okay , now lets make the same service SSL secured .</p><p>Let me refresh the basics of one way ssl briefly</p><p>In a one-way SSL (Secure Sockets Layer) connection, also known as SSL/TLS (Transport Layer Security), the server presents a digital certificate to the client to establish a secure connection. When the server uses a self-signed certificate, it means that the certificate is not signed by a trusted third-party Certificate Authority (CA). Instead, the server generates its own certificate.</p><p><strong>Here’s how it typically works:</strong></p><p><strong>Client-Server Communication Initiation:</strong> The client initiates a connection to the server using HTTPS (HTTP over SSL/TLS).</p><p><strong>Server Presents Its Certificate:</strong> When the client connects to the server, the server sends its digital certificate to the client. This certificate contains the server’s public key, its identity (such as the domain name), and other information.</p><p><strong>Client Verification:</strong> The client receives the server’s certificate. It checks whether the certificate is valid and trusted. In the case of a self-signed certificate, the client doesn’t recognise the issuer as a trusted CA because it’s not signed by a globally recognized CA.</p><p><strong>Certificate Trust Decision:</strong> If the client trusts the server, it proceeds with the connection.</p><p><strong>Establish secure connection and Exchange Data :</strong></p><p>Now, lets dive into how to create key pair to protect our Mockoon REST service .</p><p>To enable TLS, we must first create a public/private key pair for the API server. Using the <strong>keytool</strong> that comes with the default Java distribution.</p><p>The following command generates a key pair and stores it in<strong> keystore.p12</strong>.</p><pre>keytool -genkeypair -alias tlsdemo -keyalg RSA -keysize 4096 -validity 365 -dname &quot;CN=www.example.com,OU=self,O=example,L=colombo,S=western,C=SL&quot; -keypass changeit -keystore keystore.p12 -storeType PKCS12 -storepass changeit</pre><pre>-genkeypair — Generates a key pair<br>-alias &lt;alias&gt; — Alias name of the entry to process<br>-keyalg &lt;alg&gt; — Key algorithm name<br>-keysize &lt;size&gt; — Key bit size<br>-validity &lt;days&gt; — Validity number of days<br>-dname &lt;dname&gt; — Distinguished name, <br>  CN is CommonName of a person<br>  OU is OrganizationUnit<br>  O is OrganizationName<br>  L is LocalityName<br>  S is StateName<br>  C is CountryName<br>-keypass &lt;arg&gt; — Key Password<br>-keystore &lt;keystore&gt; Keystore name<br>-storeType &lt;type&gt; — Keystore type<br>-storepass &lt;arg&gt; — Keystore password</pre><p>The keystore file will be called <strong>keystore.p12</strong> and protected with the password “<strong>changeit</strong>”.<br>Now we have the keystore file containing public/private key pair .</p><p>Lets head over to Mockoon and configure the keystore for our REST service .</p><p>1.Navigate to <strong>Settings </strong>.<br>2.Check “<strong>Enable Tls</strong>”<br>3.Switch to <strong>PFX</strong> and provide the created keystore.p12 file location to “<strong>PFX or PKCS12 path”<br></strong>4.Provide password as the “C<strong>ert passphrase”</strong> ( changeit )</p><p>Reload the service if running . Sample Configurations here</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_QgkMhzph-HntZmGOyU03w.png" /></figure><p>Now, the service will be exposed over <strong>HTTPS</strong> protocol via <a href="http://www.example.com/"><strong>www.example.com</strong></a> host and <strong>3000 </strong>port .</p><p>This time, we’re curling in verbose mode, but no -k shortcuts here. We’re here to validate.<br>We will get the expected error as follows indicating the error in certificate validation.</p><pre><strong>% curl https://www.example.com:3000/abc -v </strong><br>*   Trying 127.0.0.1:3000...<br>* Connected to www.example.com (127.0.0.1) port 3000 (#0)<br>* ALPN: offers h2,http/1.1<br>* (304) (OUT), TLS handshake, Client hello (1):<br>*  CAfile: /etc/ssl/cert.pem<br>*  CApath: none<br>* (304) (IN), TLS handshake, Server hello (2):<br>* (304) (IN), TLS handshake, Unknown (8):<br>* (304) (IN), TLS handshake, Certificate (11):<br>* SSL certificate problem: self signed certificate<br>* Closing connection 0<br>curl: (60) SSL certificate problem: self signed certificate<br>More details here: https://curl.se/docs/sslcerts.html<br><br>curl failed to verify the legitimacy of the server and therefore could not<br>establish a secure connection to it. To learn more about this situation and<br>how to fix it, please visit the web page mentioned above.</pre><p>Since the server use our selfsigned certificate we need to tell curl to validate it using server’s public certificate .<br>We can parse it using the --<strong>cacert</strong> option in curl .</p><p>To export the public key from the keystore we can use the following command .</p><pre>keytool -export -file tlsdemo.crt -alias tlsdemo -rfc -keystore keystore.p12 -storepass changeit</pre><p>Executing the above will output a file called <strong>tlsdemo.crt</strong> which stores the public key of certificate .<br>Now lets invoke the API using curl parsing the public key in verbose mode .</p><pre> % <strong>curl https://www.example.com:3000/abc --cacert tlsdemo.crt -v</strong><br>*   Trying 127.0.0.1:3000...<br>* Connected to www.example.com (127.0.0.1) port 3000 (#0)<br>* ALPN: offers h2,http/1.1<br>* (304) (OUT), TLS handshake, Client hello (1):<br>*  CAfile: tlsdemo.crt<br>*  CApath: none<br>* (304) (IN), TLS handshake, Server hello (2):<br>* (304) (IN), TLS handshake, Unknown (8):<br>* (304) (IN), TLS handshake, Certificate (11):<br>* (304) (IN), TLS handshake, CERT verify (15):<br>* (304) (IN), TLS handshake, Finished (20):<br>* (304) (OUT), TLS handshake, Finished (20):<br>* SSL connection using TLSv1.3 / AEAD-CHACHA20-POLY1305-SHA256<br>* ALPN: server accepted http/1.1<br>* Server certificate:<br>*  subject: C=SL; ST=western; L=colombo; O=example; OU=self; CN=www.example.com<br>*  start date: Apr 13 17:58:40 2024 GMT<br>*  expire date: Apr 13 17:58:40 2025 GMT<br>*  common name: www.example.com (matched)<br>*  issuer: C=SL; ST=western; L=colombo; O=example; OU=self; CN=www.example.com<br>*  SSL certificate verify ok.<br>* using HTTP/1.1<br>&gt; GET /abc HTTP/1.1<br>&gt; ...<br>&lt; HTTP/1.1 200 OK<br>{&quot;hello&quot;:&quot;world&quot;}</pre><p>As expected we could see the certificate validation getting passed .</p><p>Hope you have learned something and it will help testing your front end applications .</p><p>Stay tuned ⏰ Because we’ll be revisiting this mock API service in our tech stack real soon.<br>Until next time, keep experimenting and keep exploring !!</p><p><strong>References</strong></p><p>[1] <a href="https://mockoon.com/">https://mockoon.com/</a></p><p>[2] <a href="https://mockoon.com/docs/latest/api-endpoints/routing/">https://mockoon.com/docs/latest/api-endpoints/routing/</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c0c30e7bee37" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>