Access WSO2 API Manager Devportal/Publisher through a custom proxy 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:
- 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:
- Install and start Apache server. Please refer to documentation [3] for more details.
brew install httpdbrew 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 alsonss
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 certsNow, 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 443SSLCipherSuite HIGH:MEDIUM:!MD5:!RC4:!3DES
SSLProxyCipherSuite HIGH:MEDIUM:!MD5:!RC4:!3DESSSLHonorCipherOrder on SSLProtocol all -SSLv3
SSLProxyProtocol all -SSLv3SSLPassPhraseDialog builtinSSLSessionCache "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