Certificate Based Authentication - Mutual SSL

Certificate based authentication on the microgateway is authenticating a request based on a digital certificate, before granting access to the backend. By way of certificate based authentication the microgateway supports mutual SSL. In mutual SSL, both parties the client and the server identifies themselves in order to create a successful SSL connection. Mutual SSL allows a client to make a request without a username and password, provided that the server is aware of the client's certificate.

Enabling Certificate Based Authentication on WSO2 Microgateway

1.  Lets create a microgateway project/

   1. Navigate to a preferred workspace folder using the command line. (This location is used to run the Microgateway commands and to generate Microgateway artifacts.)
   2. Create a project using the command given below
      

      
      

      Format

      micro-gw init <project_name> 
      

      Example

      micro-gw init petstore  
      Project 'petstore' is initialized successfully.

2. Now lets add the API(open API definition) to the project. Navigate to the /petstore/api_definitions directory. Add the API definition(s) to this directory. A sample open API definition can be found here.

3. Build the microgateway distribution for the project using the following command:

   Format

   micro-gw build <project_name>

   Example

   $ micro-gw build petstore
    
   Build successful  for the project - petstore

   Once the above command is executed, An executable file (/petstore/target/petstore.balx) is created to expose the API via WSO2 API Microgateway

4. Navigate to the <MGW-Toolkit-HOME>/resources /conf folder and open the “micro-gw.conf" file.
5. Locate the "sslVerifyClient" property and change the value to "required". This will enable mutual SSL.

6. Configure the truststore.Change “trustStore.path” property and “trustStore.password” property under “[listenerConfig]” instance ID. The trustore should have the certificate which is used to create SSL connections. 

   In this tutorial, a self signed certificate is added into the already available ballerina truststore.

7. Now lets run the micro gateway dokcer runtime mouting executabel file(petstore.balx) and the config file (micro-gw.conf).

   Format

   docker run -d -v <project_target_path>:/home/exec/ -v <micro-gw.conf_directory_path>:/home/ballerina/conf -p <host-HTTPS-port>:<container-HTTPS-port> -p <host-HTTP-port>:<container-HTTP-port> -e project="<MGW-project-name>" <MGW-Docker-image-name>

   Example

   docker run -d -v /wso2am-micro-gw-toolkit-3.0.1/bin/petstore/target:/home/exec/ -v /wso2am-micro-gw-toolkit-3.0.1/resources/conf/:/home/ballerina/conf -p 9095:9095 -p 9090:9090 -e project="petstore"  wso2/wso2micro-gw:3.0.1
   
   

Invoking an API using certificate based authentication

When invoking an API, you can pass the certificate to the API Microgateway as follows.

1.  Navigate to the browsers certificate management section. on Firefox, navigate to Preferences > Privacy & Security > Certificates
   
   
2.  Add the certificate used for the SSL connection.
   
3.  Invoke the REST API using a REST API client from the browser.
   
4. The browser will present a user identification request, to select a certificate in order to use for the SSL connection. Select the certificate you added and click OK.