This is a Centos 7 environment with Gnome Desktop. 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.
Using Keytool
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:
https;//api.blog.yenlo:9443/publisher
You will get a screen like this and you will notice that there is no security exception thrown due to a self-signed certificate.
Results
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!
