Secure API’s with Mutual SSL in WSO2 API Manager 3.1.0
What is Mutual SSL
Mutual SSL or the 2 way SSL is referred to as both client and server is authenticated by verifying the digital certificates. In this case, the client will authenticate itself to the server and the server will authenticate itself to the client to establish a secure connection between 2 parties. The following diagram will give a brief idea about the mutual SSL flow.
When to use Mutual SSL to secure API’s
It depends on your use-case, As an example, we could think of a scenario like this.
You have an application that is automatically triggering a scheduled task periodically and calling an API. There is no user interaction since this is automatically triggering. In such situations, we can use the mutual SSL based API authentication rather than use never-ending (Which is not a good practice) access or implementing a token regeneration flow.
Let’s Start
For this, I have used Mokoon to create a mock API. It is a very simple and very convenient tool to create mock backends.
Let’s Start
Generate client’s certificate
As i explained earlier, It is necessary to have a client side certificate to authenticate client’s identity in server (Step 4 in Fig-1). You can use the following openssl command to generate a certificate and a private key in a single call. You can refer this for more common openssl related commands.
openssl req -newkey rsa:2048 -nodes -keyout domain.key -x509 -days 365 -out domain.crt
Create An API with Mutual SSL enabled
- Log into the wso2 API manager publisher and create a new API.
- Then go to the Runtime configurations and expand the Transport level security section.
- Then there is a checkbox to enable Mutual SSL. Check on that and then you get the option to upload the client certificate.
In there you have to select the subscription tear with the uploaded certificate. Since the Application subscription is not permitted for APIs that are only protected with Mutual SSL. The selected throttling policy will be applied to the client has this certificate. If you have multiple clients intended to use this API with mutual SSL, You can upload their certificates as well.
After uploading all the certificates, You can go ahead, save and publish the API. Not it’s all ready to invoke it.
Invoking the API
As this is secured with mutual SSL, It is necessary for your clients to have the server certificate with them. There are 2 simple options you can use to extract the server certificate.
- Save certificate using the web browser.
- Export with keytool command.
Save certificate using the web browser
You can go to the API gateway URL (in a local setup is is https://localhost:8243) from a browser, Then explore the certificate and save it.
Export with keytool command.
The primary keystore (Reside in <APIM_HOME>/repository/resources/security folder) dose contains the public certificate of the WSO2 server. You can use the following keytool command to export the public cert from keystore.
keytool -export -keystore wso2carbon.jks -alias wso2carbon -file mutualSSLHostCert.crt
Invoke with CURL
You could use any of the clients to test this out. But the simplest is to use the curl.
If you invoke the API using the curl without specifying the certificate, you will get a output like below.
But to invoke the API you have to provide the following parameters to curl request.
--cacert : certificate from the server
--cert: certificate of the client
--key : private key used to genarate client certificateAnd the curl will look like belowcurl -vk -X GET "https://localhost:8243/hello/1.0.0/world" -H "accept: applicaition/json" --cacert localhost.pem --key mutualSSLDemo-key.key --cert mutualSSLDemo-cert.crt
After a successful API invocation, You will get the results as below.
Hope you have learnt something, Cheers…!
