Wiki source code of Securing a hosted web service with certificates on-premise
Last modified by Martijn Woudstra on 2022/08/30 11:20
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{container}}{{container layoutStyle="columns"}}((( | ||
| 2 | In this microlearning, we will learn how you can secure the (SOAP/REST) web service that you have created in eMagiz and that will be running on-premise. | ||
| 3 | |||
| 4 | Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]]. | ||
| 5 | |||
| 6 | == 1. Prerequisites == | ||
| 7 | |||
| 8 | * Basic knowledge of the eMagiz platform | ||
| 9 | * Basic Understanding of certificates | ||
| 10 | * Flow that hosts the web service is successfully created and deployed to the correct environment | ||
| 11 | |||
| 12 | == 2. Key concepts == | ||
| 13 | |||
| 14 | This microlearning centers around learning how you can secure the (SOAP/REST) web service that you have created in eMagiz and that will be running on-premise. | ||
| 15 | |||
| 16 | By certificates we mean: A trustworthy document that is interchanged between parties to verify that both parties are who they claim to be | ||
| 17 | |||
| 18 | It is a best practice to either secure your web service with the help of OAuth2.0 (note this only works for REST) or with a combination of API-Key and certificate (works for both SOAP as REST). | ||
| 19 | In this microlearning, we will focus on the latter of the two options and focus specifically on the configuration that is needed on the on-premise level to ensure that only clients that can provide a valid certificate are given access to the web service that is running on-premise. | ||
| 20 | |||
| 21 | * Configuration on on-premise runtime level is done on the runtime itself | ||
| 22 | * Certificate is generated via the support department (with or without CSR) | ||
| 23 | * No actions are needed on flow level, only on on-premise runtime level | ||
| 24 | * You need a valid truststore and keystore to make it work | ||
| 25 | |||
| 26 | == 3. Securing a hosted web service with certificates on-premise == | ||
| 27 | |||
| 28 | In this microlearning, we will learn how you can secure the (SOAP/REST) web service that you have created in eMagiz and that will be running on-premise. | ||
| 29 | |||
| 30 | It is a best practice to either secure your web service with the help of OAuth2.0 (note this only works for REST) or with a combination of API-Key and certificate (works for both SOAP as REST). | ||
| 31 | In this microlearning, we will focus on the latter of the two options and focus specifically on the configuration that is needed on the on-premise level to ensure that only clients that can provide a valid certificate are given access to the web service that is running on-premise. | ||
| 32 | |||
| 33 | Important things to remember are: | ||
| 34 | |||
| 35 | * Configuration on on-premise runtime level is done on the runtime itself | ||
| 36 | * Certificate is generated via the support department (with or without CSR) | ||
| 37 | * No actions are needed on flow level, only on on-premise runtime level | ||
| 38 | * You need a valid truststore and keystore to make it work | ||
| 39 | |||
| 40 | Now that we have introduced the topic let us see how to configure the certificate on-premise at the runtime level. The first step is gaining access to the on-premise server on which the runtime is (going to be) running. After you have gained access the first thing you should do is to stop the runtime in question. On a Windows server, you can do this via the services page. On a Linux server, you can do this by entering the correct command via Putty. | ||
| 41 | |||
| 42 | Now that the runtime is stopped we can change the configuration of how the runtime should operate. At first, we navigate to the installation folder of the runtime. In this folder you will see the following folders: | ||
| 43 | |||
| 44 | [[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--folder-structure.png]] | ||
| 45 | |||
| 46 | Because we are storing data on runtime level we need to create another folder called resources. Within this folder, you should store the keystore & truststore that you have created/gotten. After you have done this please navigate to the etc folder and locate the wrapper config file. After you have located the file please open it in Notepad ++ (or something similar). See below for an example. | ||
| 47 | |||
| 48 | [[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--etc-folder-wrapper-config.png]] | ||
| 49 | |||
| 50 | Within this wrapper config file, you need to add the following additional wrapper.java rules. Note that the numbering should be correct otherwise default configurations are wiped in favor of your custom config. | ||
| 51 | |||
| 52 | * wrapper.java.additional.15=-Djavax.net.ssl.keyStore= | ||
| 53 | * wrapper.java.additional.16=-Djavax.net.ssl.keyStorePassword= | ||
| 54 | * wrapper.java.additional.17=-Djavax.net.ssl.trustStore= | ||
| 55 | * wrapper.java.additional.18=-Djavax.net.ssl.trustStorePassword= | ||
| 56 | * wrapper.java.additional.18=-Demagiz.ssl.mappings= | ||
| 57 | |||
| 58 | Subsequently, you need to enter the proper values and Save the wrapper config file. An example of a configuration is shown below | ||
| 59 | |||
| 60 | * wrapper.java.additional.15=-Djavax.net.ssl.keyStore=resources/test-keystore.jks | ||
| 61 | * wrapper.java.additional.16=-Djavax.net.ssl.keyStorePassword=GoedWachtwoord1! | ||
| 62 | * wrapper.java.additional.17=-Djavax.net.ssl.trustStore=resources/test-truststore.jks | ||
| 63 | * wrapper.java.additional.18=-Djavax.net.ssl.trustStorePassword=GoodPassword1! | ||
| 64 | * wrapper.java.additional.18=-Demagiz.ssl.mappings=resources/sslconfig.properties | ||
| 65 | |||
| 66 | Now that we have changed the wrapper config file we need to start the runtime back up again. After this, your web service will be secured with the help of certificates. | ||
| 67 | |||
| 68 | == 4. Assignment == | ||
| 69 | |||
| 70 | Check whether any on-premise runtime is secured with an accompanying certificate within your environment and see if you can reproduce the steps and analyze what someone has configured. | ||
| 71 | |||
| 72 | == 5. Key takeaways == | ||
| 73 | |||
| 74 | * Certificates are all about trust | ||
| 75 | * With custom changes on runtime level you can achieve the desired result on-premises at the eMagiz runtime level | ||
| 76 | * Be aware that this is not an easy task to do so be careful | ||
| 77 | |||
| 78 | == 6. Suggested Additional Readings == | ||
| 79 | |||
| 80 | If you are interested in this topic and want more information on it please read the help texts provided by eMagiz | ||
| 81 | |||
| 82 | == 7. Silent demonstration video == | ||
| 83 | |||
| 84 | As this is a highly specific case that requires a valid certificate and a working on-premise setup to work we have opted to not create a video for this. | ||
| 85 | |||
| 86 | )))((({{toc/}}))){{/container}}{{/container}} |