Running WSO2 API Manager 2.5.0 on a different hostname

Posted by Rob Blaauboer on 29 Nov, 2018
Find me on:

Running API Manager 2.5.0 on a different hostnameWhen 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:

  1. Downloading and installing WSO2 API Manager;
  2. Creating a new keystore and certificates using a CA created with tinycert
  3. Making changes to the hosts file
  4. Changing the configuration of the API Manager to run on api.blog.yenlo
  5. 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.

Download API Manager 2.5.0

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.

WSO2 APIM 2.5.0 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:

  1. Create a new CA and add that certificate to the browser
  2. 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

Certification Authorities

Create a certificate for api.blog.yenlo

Subsequently create a certificate for the hostname, I use the api.blog.yenlo hostname.

New Certificate API blog

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>

Making changes to the configuration - api 2.5.0 blog

and also change the <KeyAlias> and <KeyPassword> 

change key alias and key password

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

ca certificate - cacert.pem - wso2 apim 2.5.0 blog

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:

Starting WSO2 APIM with wso2server.sh or bat

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.

WSO2 API Publisher - all apis

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!

New Call-to-action

Topics: Technical, WSO2 API, API Management, API, APIs, WSO2

Written by Rob Blaauboer

Rob Blaauboer
Rob is a Senior Business Consultant and Solution Architect with more than twenty years experience. In addition to his work he is an active blogger working on a number of articles on the ‘Internet of Things’ and a WSO2 ‘Getting Started with …’ series (WSO2 tutorial) in which he talks about WSO2 components and their purpose especially aimed at non technical readers. Rob is a WSO2 expert and official WSO2 trainer.

Find me on: