Securing a hosted web service with certificates on-premise
In this microlearning, we will learn how to secure the (SOAP/REST) web service you created in eMagiz, which will run on-premise. We will discuss three distinct configuration options. We first look at changing the endpoint from HTTP to HTTPS (SSL). The second option will define setting up the configuration in case a client certificate is mandatory. The third one will look at determining the allowed TLS versions.
Should you have any questions, please contact academy@emagiz.com.
1. Prerequisites
- Basic knowledge of the eMagiz platform
- Basic understanding of certificates
- The flow that hosts the web service is successfully created and about to be deployed to the correct environment
2. Key concepts
This microlearning centers around learning how to secure the (SOAP/REST) web service you created in eMagiz, which will run on-premise.
By certificates, we mean: A trustworthy document that is interchanged between parties to verify that both parties are who they claim to be.
It is a best practice to secure your web service with OAuth2.0 (note that this only works for REST) or with a combination of API key and a certificate (works for both SOAP and REST). Furthermore, you can opt to define an HTTPS endpoint on-premise and enforce specific TLS versions.
This microlearning will focus on the certificate part, including HTTPS and TLS, which can be configured for web services running on-premise.
- Configuration of the SSL configuration (HTTPS, TLS, and client certificates) is done in Deploy -> Architecture
- Certificate is generated via the support department (with or without CSR) or the client
- No actions are needed on the flow level, only in the Deploy Architecture
- You need a valid truststore and keystore to make it work
3. Securing a hosted web service with certificates on-premise
To secure a web service that runs on-premise with the help of certificates, we need to navigate to Deploy -> Architecture. Here, we have the "Runtime settings" option that allows us to configure SSL options, such as HTTPS, TLS, and client certificates).
After checking that the HTTP enabled option is set to "Yes", which is the default when you have configured a hosted soap or rest endpoint, you will see a second tab called "HTTP".
In this tab, you have generic configuration options, specifically the port and whether to enable SSL. In the rest of this microlearning, we care about the SSL configuration.
As a result, we will toggle the "SSL enabled" option to "Yes." Two new tabs will then be shown to the user.
In this overview, you can now select "SSL Client Authentication". There are three separate options available: "Disabled" (default), "Allowed," and "Mandatory." For now, we leave this option on the default to first focus on the SSL and TLS part. Later in this microlearning, we will return to this option to discuss the effect of the other options.
3.1 Protocol (TLS) configuration
Under the SSL tab, you can define this web service's (enabled) protocols. This concerns the (allowed) TLS versions on this endpoint. For example, when you want to define only TLS 1.3 as an enabled protocol version, you need to fill in TLSv1.3.
Once done, you have defined that your endpoint only supports communication via the TLS v1.3 protocol.
3.2 HTTPS configuration
Under the Keystore tab, you need to define the keystore used to grant the endpoint the HTTPS status (instead of) HTTP.
This keystore needs to contain a keypair defining the server certificate-related information. In most cases, this keystore will be a JKS for which the store password and the key password are the same. We also need to define the type of keystore we upload here.
Once done, you have configured your endpoint as an HTTPS endpoint.
3.3 Client certificate
As stated before, there is an option on the HTTP tab that allows you to specify whether a client certificate is needed. For example, by selecting the option "Mandatory," a new tab called "Trust store" appears.
In this tab, you need to upload the truststore containing all CA-level trusted certificates (that were used to issue the client certificates). You also need to define the type and password of the truststore.
Once configuring your endpoint, clients must provide a client certificate to exchange data.
3.4 Deployment
To update your configuration, you need to create a new release and deploy it to actualize the changes made for TLS, HTTPS, and client certificate configuration.
3.5 Recap
Important things to remember are:
- Configuration of the SSL configuration (HTTPS, TLS, and client certificates) is done in Deploy -> Architecture
- Certificate is generated via the support department (with or without CSR) or the client
- No actions are needed on the flow level, only in the Deploy Architecture
- You need a valid truststore and keystore to make it work
4. Key takeaways
- Certificates are all about trust
- With custom changes on the runtime level, in Deploy -> Architecture, you can achieve the desired result on-premises at the eMagiz runtime level
- Be aware that this is not an easy task to do, so be careful
5. Suggested Additional Readings
If you are interested in this topic and want more information, please read the help texts provided by eMagiz and check out the following microlearning and exercise.