Configuring SSL in Microservices

An important prerequisites for a secure communication between the web browser (end user) and the web server is to use Secure Sockets Layer (SSL) certificate. Adeptia Connect microservices also adheres to this requirement. To achieve this, you need to configure SSL in the Gateway microservice after you've deployed Adeptia Connect.

You can configure the SSL certificate following either of the two methods based on whether you're using any Kubernetes ingress controller, or the Gateway itself as a front-end for communication.

Configuring SSL in Kubernetes Ingress

If you're using any Kubernetes ingress controller as a front-end for gateway microservice, you need to configure SSL through Kubernetes ingress object. 

You can secure an Ingress by specifying a Secret that contains a TLS private key and certificate. The Ingress resource only supports a single TLS port, 443, and assumes TLS termination at the ingress point (traffic to the Service and its Pods is in plaintext). If the TLS configuration section in an Ingress specifies different hosts, they are multiplexed on the same port according to the hostname specified through the SNI TLS extension (provided the Ingress controller supports SNI).

The TLS secret must contain keys named tls.crt and tls.key that contain the certificate and private key to use for TLS. For example:

Referencing this secret in an Ingress tells the Ingress controller to secure the channel from the client to the load balancer using TLS. You need to make sure the TLS secret you created came from a certificate that contains a Common Name (CN), also known as a Fully Qualified Domain Name (FQDN), for example, dummy.adeptia.com.

Note: There is a gap between TLS features supported by various Ingress controllers. Please refer to documentation on nginx, GCE, or any other platform specific Ingress controller to understand how TLS works in your environment.

For more details, refer the Kubernetes official documentation.

After you've configured ingress, you've to follow the steps below in the same sequence.

• Exporting the public key
• Importing the certificate  

Configuring SSL in Gateway microservice

In case you're not using any Kubernetes ingress controller, you need to configure SSL certificate in gateway microservice that will be running on any LoadBalancer type Kubernetes service. To achieve this, follow the steps given below in the same order.

Generating SSL certificate

1. Open Terminal.

2. Run the following Keytool command to create a Keystore for Jetty with a self-signed certificate or CA signed certificate. In case Keytool is not installed on your system, install it by referring to the tool documentation. 

    For self-signed certificate

   To generate SSL certificate for Jetty with a self-signed certificate:

   keytool -genkey -keyalg <keyalg> -alias <alias_name> -keystore <keystore_name> -storepass <password> -validity <days> -keysize <keysize> -ext SAN=ip:<FQDN/IP of the Gateway>,dns:<domain_name>

   Where,

   <keyalg> specifies the algorithm to be used to generate a key pair.

   <alias_name> is a unique string to identify the Keystore.

   <keystore_name> is the location and filename where you want to store the generated key.

   <password> is the password to protect the private key of the generated key pair, default is changeit.

   <days> are the number of days certificate will expire.

   <keysize> specifies the size of each key to be generated.

   <FQDN/IP of the Gateway> is the IP address or FQDN of the Gateway.

   <domain_name> is the name of the domain you are using. It is not necessary to use the domain name in the command above. However, for easy identification, it is recommended to use the domain name.

   For example,

   keytool -genkey -keyalg RSA -alias selfsigncert -keystore certs.jks -storepass changeit -validity 365 -keysize 2048 -ext san=ip:10.44.2.59

   keytool -genkey -keyalg RSA -alias selfsigncert -keystore certs.jks -storepass changeit -validity 365 -keysize 2048 -ext san=dns:localhost

    For CA signed certificate

   To generate SSL certificate for Jetty with a CA signed certificate:

   1. Generate Keystore

      keytool -genkey -keyalg <keyalg> -alias <alias_name> -keystore <keystore_name> -storepass <password> -validity <days> -keysize <keysize>

      Where,           

      <keyalg> specifies the algorithm to be used to generate a key pair.

      <alias_name> is a unique string to identify the Keystore.

      <keystore_name> is the location and filename where you want to store the generated key.

      <password> is the password to protect the private key of the generated key pair, default is changeit.

      <days> are the number of days certificate will expire.

      <keysize> specifies the size of each key to be generated.

      For example,

      keytool -genkey -keyalg RSA -alias server -keystore certs.jks -storepass changeit -validity 365 -keysize 2048

      If you are using multiple domain names for the same certificate then you need to use SAN (Subject Alternative Name) while generating Keystore.

      keytool -genkey -keyalg <keyalg> -alias <alias_name> -keystore <keystore_name> -storepass <password> -validity <days> -keysize <keysize>
      -ext SAN=ip:<FQDN/IP of the Gateway>

      Where, <FQDN/IP of the Gateway> is the IP address or FQDN of the Gateway.
      

   2. Generate CSR from the generated Keystore
      Run the following Keytool command to create a Certificate Signing Request (CSR).

      keytool -certreq -alias <alias_name> -file <domainname>.csr -keystore <keystore_name>.jks -storepass <password>

      This command will generate a <domainname>.csr file to sign from CA.

   3. If you are using multiple domain names for the same certificate then you need to use SAN (Subject Alternative Name) while generating CSR for the Keystore.
      
      

      keytool -certreq -alias server -file <domainname>.csr -keystore <keystore_name>.jks -storepass password -ext san=ip:<IP_Address_of_Connect_Server_machine>

      
      Send this CSR to your CA to generate SSL certificate. After your SSL certificate is generated, you need to import the certficate in the Java Keystore.

   4. Import CA Signed SSL Certificate into Java Keystore.   

      You might get multiple SSL certificates from your CA. You need to import all these SSL certificates into your Keystore. Ensure that you use the same Keystore that is used in generating CSR while importing SSL certificates.

      1. Import Trusted Root certificate into Java Keystore.

         keytool -import -trustcacerts -alias root -file <certificate_name>.crt -keystore <domain_name>.jks

      2. Import Intermediate certificate into Java Keystore. 

         keytool -import -trustcacerts -alias intermediate -file <certificate_name>.crt -keystore <domain_name>.jks

      3. Import domain certificate into Java Keystore

         keytool -import -trustcacerts -alias server -file <certificate_name>.crt -keystore <domain_name>.jks

         Where,

         <certificate_name> is the name of the CA certificate.

         <domain_name> is the name of the domain you are using.

   While executing the command, you will be prompted to provide other details. The default password is password. You can change the password. Note the Keystore password for future references.

3. Run the following Kubectl command to copy the certificate to the PVC or shared storage volume for any available Gateway pod.

   Kubectl --namespace <namepace_name> cp <local_path_for_SSL_certificate> <pod_name>:shared/keystore/<Keystore_File_name> 

4. Edit the Kubernetes deployment object of Gateway microservice to update the below environment variables as per your Keystore path and password.
   SSL_KEYSTORE_PATH
   SSL_KEYSTORE_PASSWORD
   
   Once you've updated the Kubernetes deployment object of Gateway microservice, the pods corresponding to the Gateway microservice will be redeployed automatically. 

Exporting the public key of Gateway/Ingress controller 

The steps for exporting the public key of the Gateway/Ingress controller external URL (external FQDN, for example, dummy.adeptia.com) vary from browser to browser. It is recommended that you export the key using DER encoded binary format X.509 (.CER). Following are the steps to export the public key in Google Chrome browser.

1. Enter the Adeptia Connect application URL (client-specific according to client domain) in the browser.
   The login page opens.
2. Click  > More tools > Developer tools.
3. Click Security tab. 
4. Click View Certificate.
   
   
   
   
5. On the Certificate window, on the Details tab, click Copy to File.
   
   
   
   
6. Click Next to start exporting the certificate.
   
   
   
   
7. Choose DER encoded binary X.509 (.CER) and click Next.
   
   
   
   
8. Specify the location to save the exported file and click Next.
   
   
   
   
9. Click Finish to export.
10. Click OK to exit from the wizard.

Importing the Gateway/Ingress controller certificate 

This section helps you to import SSL certificate in the microservices Truststore.

Following the steps given below, you'd be able to import the SSL certificate in the Gateway microservice Truststore with an alias name adeptia.

1. Run the following Kubectl command to copy the certificate to the PVC or shared storage volume for the Gateway pod.

   Kubectl --namespace <namepace_name> cp <local_path_for_SSL_certificate> <pod_name>:shared/truststore/<SSL_certificate_name> 

2. Navigate to the Microservice pod (Eg. Webrunner) by running the following command.

   Kubectl --namespace <namespace_name> exec -it <pod_name> -- sh 

3. Run the following Keytool command to import the certificate.

   keytool -import -trustcacerts -file <Path_of_SSL_Certificate> -alias <alias_name> -keystore <Path of cacerts file>

   Where,

             <Path_of_SSL_Certificate> is the path of SSL certificate.

             <Path of cacerts file> is the path of Truststore.

   For example,

   keytool -import -trustcacerts -file shared/truststore/ssl-certs.cer -alias adeptia -keystore shared/truststore/cacerts

   You'll be prompted to enter a password. Enter the default password changeit.

4. Run the exit command to exit from the pod shell.
5. Restart all the Microservices to bring the changes into effect.

Configuring Gateway/LoadBalancer FQDN/IP

You need to configure gateway/LoadBalancer FQDN/IP (Domain name assigned to Gateway Kubernetes service) environment variable in other microservices.

Edit the Kubernetes deployment object of Event, Portal, and Webrunner microservices to update the below environment variables as per your gateway domain name. The image below is an example showing the environment variable and a dummy gateway URL as a value for this variable.

Verifying SSL

To verify if the SSL certificate is configured in Adeptia Connect:

1. Open the browser and hit the Gateway URL, for example, https://dummy.adeptia.com, to access Adeptia Connect using https protocol.
2. Adeptia Connect login page appears. Verify your certificate by checking https protocol color in the address bar. If you have used CA signed certificate then https protocol will be green in color  () . In case you've used self-signed certificate, the https protocol will be red in color ().