Access WSO2 API Manager Devportal/Publisher through a custom proxy path

Courtesy: https://unsplash.com/s/photos/path

Greetings to everyone!! Today I’m going to share with you how to access WSO2 APIM devportal/publisher portals through a custom proxy path. Here I’m using Apache HTTP Server(Apache/2.4.48) as the proxy server.

Let’s say devportal/publisher console apps are hosted in the knnect.lk domain as follows. And “apim” is the “proxy context paths” of API Manager.

https://knnect.lk/apim/devportal/
https://knnect.lk/apim/publisher/

🔯 Steps for WSO2 APIM configuration:

1. Get the latest update level of WSO2 APIM — ex: This feature is available APIM 3.1.0.70 update level onwards.

2. Create a keystore with the CN of the ‘server.hostname’(knnect.lk), import that public key and proxy key(ex: knnect.lk.pem) to the client-truststore.jks file, and configure the same keystore in the deployment.toml as guided below.

🎏 Create a new key store.

keytool -genkey -alias wso2carbon -keyalg RSA -keystore wso2carbon.jks -keyalg RSA -keysize 2048 -validity 9999 -dname "CN=knnect.lk, O=WSO2, L=CL, ST=WP, C=LK, OU=APIM" -ext "SAN=DNS:knnect.lk"

🎏 Export the public key.

keytool -export -alias wso2carbon -keystore wso2carbon.jks -file publickey.pem

🎏 Import the public key to the client-truststore.jks with alias ‘gateway_certificate_alias’

keytool -import -alias gateway_certificate_alias -file publickey.pem -keystore client-truststore.jks -storepass wso2carbon

🎏 If that alias is already available remove that entry first.

keytool -delete -alias gateway_certificate_alias -keystore client-truststore.jks

🎏 Import the key of the Apache server to the client-truststore.jks

keytool -import -alias proxykey -file /usr/local/etc/httpd/certs/knnect.lk.pem -keystore client-truststore.jks -storepass wso2carbon

🎏 Update the deployment.toml file with the details of the newly created key store.

[keystore.primary]
file_name =  "wso2carbon.jks"
type =  "JKS"
password =  "wso2carbon"
alias =  "wso2carbon"
key_password =  "wso2carbon"

Please find the locations of the wso2carbon.jks and client-truststore.jks in WSO2 APIM.

• <APIM-HOME>/repository/resources/security/client-truststore.jks
• <APIM-HOME>/repository/resources/security/wso2carbon.jks

Please refer to the documentation [1] for more details.

3. Additional file-based configurations.

📓<APIM-HOME>/repository/conf/deployment.toml

[server]
hostname = "knnect.lk"
node_ip = "127.0.0.1"
#offset=0
mode = "single" #single or ha
base_path = "${carbon.protocol}://${carbon.host}:${carbon.management.port}/apim"
#discard_empty_caches = false
server_role = "default"
proxy_context_path = "/apim"
[transport.https.properties]
proxyPort = 443
[[apim.gateway.environment]]
...
http_endpoint = "http://knnect.lk:${http.nio.port}"
https_endpoint = "https://knnect.lk:${https.nio.port}"
[apim.devportal]
url = "https://knnect.lk/apim/devportal"
[transport.https.properties]
proxyPort = 443

📓 <APIM-HOME>/repository/resources/conf/templates/repository/conf/tomcat/carbon/WEB-INF/web.xml.j2

<context-param>
      <param-name>contextPath</param-name>
      <param-value>apim</param-value>
    </context-param>

📓 <APIM-HOME>/repository/deployment/server/jaggeryapps/devportal/site/public/theme/settings.js

app: {
        context: '/apim/devportal', 
        proxy_context_path: '/apim',

📓 <APIM-HOME>/repository/deployment/server/jaggeryapps/publisher/site/public/conf/settings.js

app: {
        context: '/apim/publisher', 
        proxy_context_path: '/apim',

🔯 Steps for Apache configuration:

1. Install and start Apache server. Please refer to documentation [3] for more details.

brew install httpd
brew services start httpd

Hope you are already having the certificate key pair for the proxy which needs to be configured under ‘SSLCertificateFile’ and ‘SSLCertificateKeyFile’. If not please follow the below steps to generate a self-signed certificate in https://getgrav.org/blog/macos-monterey-apache-ssl

Install mkcert to serve as our certificate authority (CA), and also nss to ensure firefox can use a certificate authority server.

brew install mkcert nss

Next, we have to install the server and run it (enter your password when prompted):

mkcert -install

Let’s create a appropriate location for the certificates:

cd /opt/homebrew/etc/httpd
mkdir certs && cd certs

Now, all we have to do is generate a certificate for any domain we wish to use. For example, you could create one for “knnect.lk” with:

mkcert knnect.lk

These commands will create .pem and -key.pem files for each domain.

2. Please find the Apache file-based configurations.

📓 httpd-ssl.conf

Listen 443
SSLCipherSuite HIGH:MEDIUM:!MD5:!RC4:!3DES
SSLProxyCipherSuite HIGH:MEDIUM:!MD5:!RC4:!3DES
SSLHonorCipherOrder on 
SSLProtocol all -SSLv3
SSLProxyProtocol all -SSLv3
SSLPassPhraseDialog  builtin
SSLSessionCache        "shmcb:/usr/local/var/run/httpd/ssl_scache(512000)"
SSLSessionCacheTimeout  300

<VirtualHost *:443>
    DocumentRoot "/usr/local/var/www"
    ServerName knnect.lk:443
    ServerAdmin admin@wso2.com
    ErrorLog "/usr/local/var/log/httpd/error_log"
    TransferLog "/usr/local/var/log/httpd/access_log"
    SSLEngine on
    SSLProxyEngine On
    SSLCertificateFile "/usr/local/etc/httpd/certs/knnect.lk.pem"
    SSLCertificateKeyFile "/usr/local/etc/httpd/certs/knnect.lk-key.pem"
    <FilesMatch "\.(cgi|shtml|phtml|php)$">
        SSLOptions +StdEnvVars
    </FilesMatch>
    <Directory "/usr/local/var/www/cgi-bin">
        SSLOptions +StdEnvVars
    </Directory>

    BrowserMatch "MSIE [2-5]" \
            nokeepalive ssl-unclean-shutdown \
            downgrade-1.0 force-response-1.0

    CustomLog "/usr/local/var/log/httpd/ssl_request_log" \
            "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
    ProxyPreserveHost On
    ProxyRequests Off
    ProxyVia Off
    <Proxy *>
         Require all granted
    </Proxy>
    
    ProxyPass "/apim/devportal"  "https://knnect.lk:9443/devportal/"
    ProxyPass "/apim/publisher"  "https://knnect.lk:9443/publisher/"
    ProxyPass "/apim/"  "https://knnect.lk:9443/"
    ProxyPassReverse "/apim/"  "https://knnect.lk:9443/"
    ProxyPass "/authenticationendpoint/"  "https://knnect.lk/apim/authenticationendpoint/"
    ProxyPassReverse "/authenticationendpoint/"  "https://knnect.lk/apim/authenticationendpoint/"
    ProxyPass "/oauth2/"  "https://knnect.lk/apim/oauth2/"
    ProxyPassReverse "/oauth2/"  "https://knnect.lk/apim/oauth2/"
    ProxyPass "/carbon/"  "https://knnect.lk/apim/carbon/"
    ProxyPassReverse "/carbon/"  "https://knnect.lk/apim/carbon/"
    ProxyPass "/commonauth/"  "https://knnect.lk/apim/commonauth/"
    ProxyPassReverse "/commonauth/"  "https://knnect.lk/apim/commonauth/"
    ProxyPass "/commonauth"  "https://knnect.lk/apim/commonauth/"
    ProxyPassReverse "/commonauth"  "https://knnect.lk/apim/commonauth/"
</VirtualHost>

📓 httpd.conf

...
LoadModule xml2enc_module lib/httpd/modules/mod_xml2enc.so
LoadModule proxy_html_module lib/httpd/modules/mod_proxy_html.so
LoadModule proxy_module lib/httpd/modules/mod_proxy.so
LoadModule proxy_connect_module lib/httpd/modules/mod_proxy_connect.so
LoadModule proxy_http_module lib/httpd/modules/mod_proxy_http.so
...
<IfModule proxy_html_module>
Include /usr/local/etc/httpd/extra/proxy-html.conf
</IfModule>
...
Include /usr/local/etc/httpd/extra/httpd-ssl.conf
...

Please refer to documentation [2] for more information.

You can check the syntax (after configuring the aforementioned files) using the below command in MAC OS.

/usr/local/bin/httpd -t

3. Start/Restart the service the effect the configuration changes. Map Your IP address to localhost.

brew services start httpd
brew services restart httpd

To map the IP address to the domain name edit the “/etc/hosts” file accordingly.

127.0.0.1 knnect.lk

4. Start/Restart Apache server

sudo apachectl start
sudo apachectl restart

And, yes that’s it.. 🎉 🎉 We have successfully configured the WSO2 API Manager with Apache HTTP server for a custom proxy path.

Hope you find the blog post useful ❕❕ 🎄 🎄 🎄 Merry Christmas 🎄🎄🎄

References:

[1] https://apim.docs.wso2.com/en/3.2.0/install-and-setup/setup/security/configuring-keystores/configuring-keystores-in-wso2-api-manager/
[2] https://apim.docs.wso2.com/en/3.2.0/install-and-setup/setup/setting-up-proxy-server-and-the-load-balancer/adding-a-custom-proxy-path/
[3] https://getgrav.org/blog/macos-monterey-apache-multiple-php-versions