When you download WSO2 API Manager and deploy it, it is set to localhost as the hostname. This means you run the API Manager locally (localhost is mapped to the 127.0.0.1). This is perfectly fine if you just want to see what the API Manager does. When you want to go beyond that, for instance doing a Proof of Concept, you will want to install on a server, either locally or even in the cloud. In this blog we will describe the steps you need to take in order to run the API Manager on a different hostname, in this case we will use the api.blog.yenlo hostname and run on an Amazon Instance.
This is a Centos 7 environment with Gnome Desktop accessed using NoMachine. The /opt/wso2 directory is the main directory that we will use.
The high-level steps are:
- Downloading and installing WSO2 API Manager;
- Creating a new keystore and certificates using a CA created with tinycert
- Making changes to the hosts file
- Changing the configuration of the API Manager to run on api.blog.yenlo
- Testing the API Manager, creating and deploying an API, subscribing to the API and invoking it
Step 1 Downloading and installing WSO2 API Manager
The first step is easy. Just download the API Manager from the website of WSO2 or use the WSO2 Update Manager to download. Because we are using a Centos Linux environment on AWS for this blog, we download the specific RPM for Centos, the middle of the three boxes on the top line.
I’ve chosen the Downloader without updates, this is the open source version of the product that you can use without incurring cost. The benefit of the RPM package is that you can open it with the software installer.
The installer installs the product to the /usr/lib64/wso2/wso2am/2.5.0 location. This is not relocatable according to the rpm information
Relocations : (not relocatable).To check this type
rpm -qpi wso2am-linux-installer-x64-2.5.0.rpm
If you want to install it somewhere else you can use the binary download option which downloads a zip file. This can easily be installed anywhere.
We create a symlink to the directory on the desktop using
ln -s /usr/lib64/wso2/wso2am/2.5.0 /opt/wso2/Desktop/AM
in order to make changing the files easy.
We will not start the product but rather make the changes.
Step 2 Creating a new keystore and certificates
When you run the API Manager from another hostname than localhost you will get an error because of the mismatch between the certificate and the name in use. Self-signed certificates are not trusted by the browser, this is the reason why you need to add a security exception in the browser in order to access the site.
So, we are going to do two things:
- Create a new CA and add that certificate to the browser
- Create a new keystore and certicate
Creating a new keystore and certificates is something that takes a little work. We will not create a self-signed certificate using the Java keytool but rather use the services of tinycert.org.
Go to tinycert and sign-up with your email account. Special care is required for the passphrase that is needed since you need it to generate certificates and it cannot be recovered if you have forgotten it. If you want to have as little problems as possible keep the passphrase
wso2carbon, like the default setting of WSO2 products out of the box (OOTB).
Create a new Certificate Authority., something along the lines as below.
Create a CA
We are first going to create a Certificate Authority. This will allow us to easy create a new keystore signed by this CA. By adding the certificate of the CA to the browser the connection is trusted. Click on Download and download the CAcertificate
Create a certificate for api.blog.yenlo
Subsequently create a certificate for the hostname, I use the api.blog.yenlo hostname.
Click on the Certificate and download the PKCS#12. Store it in a safe location.
Making changes to the configuration
We now need to make changes to the API manager. Go to the
[APIM-HOME]/repository/conf/carbon.xml and edit it. Change the <HostName>, <MgtHostName>
and also change the <KeyAlias> and <KeyPassword>
We keep the alias as is, as well as the password. When creating the new keystore (with the exact name as the old one) we make sure that the password and alias are changed / added.
Go to the
APIM-HOME]/repository/resources/security and rename the existing
wso2carbon.jks to _wso2carbon.jks and import the
CAcert.pem into the truststore using this command:
keytool -import -alias blog -file cacert.pem -keystore client-truststore.jks -storepass wso2carbon
Create a new keystore from the pks12 with this command, this combines the alias creation:
keytool -importkeystore -srckeystore cert.pfx -destkeystore wso2carbon.jks -srcstoretype pkcs12 -deststoretype JKS -srcalias 1 -destalias wso2carbon
You will need to enter the password for the pkcs12 file and give the new password for the keystore. Keep this at wso2carbon to make life easier. The password is defined in the carbon.xml configuration file.
Miscellaneous keytool commands
Working with the certificates is a bit of a puzzle, with regards to the passphrases, aliases and so on.
If the alias in the keystore is still on 1 (default) change it to wso2carbon with the following command:
keytool -changealias -keystore /opt/wso2/Desktop/wso2carbon.jks -alias 1
To change the keypassphrase you can use this command:
keytool -keypasswd -keystore .\wso2carbon.jks -alias wso2carbon
Adding the certificate
We add the CA certificate to the browser. For the Firefox version, I was using I had to go to Preferences – Advanced – Certificates – View Certificates – Import. Select the cacert.pem
Starting WSO2 API Manager
We start the API Manager with the regular wso2server.sh or bat (depending on your environment).
You will see the following info on screen:
Right Click on the publisher link and open the link. In Windows, open your browser and type in the url:
You will get a screen like this and you will notice that there is no security exception thrown due to a self-signed certificate.
We have an API Manager running on a different hostname. The new certificates and keystore allow to access the API Manager on the new hostname and the added CA certificate makes sure the browser trusts the certificate that we generated with tinycert.
If you have any questions regarding this blog, don't hesitate to leave a comment!