Last modified by Erik Bakker on 2024/08/26 12:58
From version 4.1
edited by Erik Bakker
on 2022/08/22 16:22
Change comment: There is no comment for this version
To version 2.2
edited by Erik Bakker
on 2022/06/12 09:56
Change comment: Update document after refactoring.

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -Sending certificates to a webservice
1 +novice-securing-your-data-traffic-sending-certificates-to-a-webservice
Content
... ... @@ -1,60 +1,111 @@
1 1  {{container}}{{container layoutStyle="columns"}}(((
2 -In this microlearning, we will learn how you can send a certificate to a SOAP web service.
2 +In this microlearning, we will focus on what certificates are and will relate this to how you could use them to secure your data traffic.
3 3  
4 4  Should you have any questions, please contact academy@emagiz.com.
5 5  
6 +* Last update: April 22th, 2021
7 +* Required reading time: 7 minutes
8 +
6 6  == 1. Prerequisites ==
7 7  * Basic knowledge of the eMagiz platform
8 -* Basic Understanding of certificates
9 -* Valid Keystore (and Truststore)
10 10  
11 11  == 2. Key concepts ==
12 -This microlearning centers around learning how to send a client certificate (and potentially trust a client certificate).
13 +This microlearning centers around what are certificates.
13 13  
14 14  By certificates we mean: A trustworthy document that is interchanged between parties to verify that both parties are who they claim to be
15 15  
16 -In most cases when you send a certificate to a web service we talk about sending a client certificate along with the web service call.
17 -In some cases however the endpoint we call is not secured via a certificate chain containing a CA. In those cases, we need to explicitly trust the party to whom we are sending data by placing data in the truststore.
17 +Certificates can be used in many forms. Two distinct forms are:
18 18  
19 -In another microlearning, we will learn how to create the keystore and truststore. The focal point of this microlearning is how you need to configure eMagiz correctly to make this work.
19 +* Authenticate
20 +* Encrypt
20 20  
21 -== 3. Sending certificates to a webservice
22 +Within eMagiz we usually see that configurable certificates are used for authentication:
23 +* eMagiz to an external party
24 +* External party to eMagiz
22 22  
23 -In this microlearning, we will learn how you can send a certificate to a SOAP web service.
24 24  
25 -In most cases when you send a certificate to a web service we talk about sending a client certificate along with the web service call.
26 -In some cases however the endpoint we call is not secured via a certificate chain containing a CA. In those cases, we need to explicitly trust the party to whom we are sending data by placing data in the truststore.
27 +
28 +== 3. What are certificates ==
27 27  
28 -In the remainder of this section, we will step by step navigate you through the required steps that are needed to ensure that the keystore and truststore are properly linked to the flow and the component that is executing the SOAP web service call. The journey starts in the Create phase of eMagiz.
30 +In this microlearning, we will focus on what certificates are and will relate this to how you could use them to secure your data traffic.
29 29  
30 -The first step is to open the flow in which you want to call a SOAP web service. Within the flow enter "Start Editing" mode. The first component you should check for is whether the flow you have just opened already has a web service outbound gateway. This component should be at the end of your flow.
32 +Certificates can be used in many forms. Two distinct forms are:
31 31  
32 -After you have confirmed that such a component is indeed available in your flow please navigate to the Resources tab in the flow. In this tab, you see all Resources that are linked to the flow. For this exercise, we need to upload the key* and truststore via the button Upload New Resource. As a result, the resources overview should look similar as follows:
34 +* Authenticate
35 +* Encrypt
33 33  
34 -[[image:Main.Images.Microlearning.WebHome@novice-securing-your-data-traffic-sending-certificates-to-a-webservice--resource-overview.png]]
37 +Within eMagiz we usually see that configurable certificates are used for authentication:
38 +* eMagiz to an external party
39 +* External party to eMagiz
35 35  
36 -Now that we have uploaded the correct resources we need to download them again. The reason why we need to download them again is that eMagiz gives every document a unique name by adding a prefix to the name. This prefix is crucial to have as you need to use it to refer to the correct resource later on.
41 +The remainder of this section will be spent explaining as well as possible what certificates are. The first question we should ask ourselves to get clarification on the topic is:
37 37  
38 -The next step is to move back to the flow and add the support object called SSL web service message sender. Give the component a name and open it. Subsequently fill in the required fields (keystore path, keystore password, truststore path, truststore password).
43 +* What are certificates used for?
39 39  
40 -[[image:Main.Images.Microlearning.WebHome@novice-securing-your-data-traffic-sending-certificates-to-a-webservice--ssl-web-service-message-sender-filled-in.png]]
45 +=== 3.1 What are certificates used for? ===
41 41  
42 -Note: In case of update validate whether the alias field on the Advanced tab is used. If so verify if the alias still corresponds with what is registered in the keystore.
47 +One application of the use of certificates lies in the authentication. With certificates in this form, you have a method of verifying that the person that claims to be a certain individual is indeed that individual. One application lies in the encryption of data when it is being exchanged between two parties. This ensures that an independent third party cannot see what data is exactly exchanged between these two parties.
43 43  
44 -When you are happy with your configuration close the pop-up and open the web service outbound component. Navigate to the advanced tab in this component and link the SSL web service message sender component to this functional component.
49 +To clarify these concepts in a better way let us consider the following example that takes place in medieval times. Imagine that you needed to bring a treasure to a certain location (castle X, castle Y, etc.). Note that the medieval location could be the URL of today (www.google.com, my.emagiz.com, etc.)
45 45  
46 -This concludes the configuration of the flow. Press "Stop Editing" and create a new version of the flow. The only task remaining is to create properties (per environment) that refer to the paths and the password. The paths should be noted as: “resources/[filename of the key* or truststore]”. The password property should simply refer to the password.
51 +To successfully finish this quest you as a person (or computer) would need to know how that castle looks like, where the castle is exactly located, etc. But what if you do not know those pieces of the puzzle? How can you be sure that you are delivering the treasure to the correct castle? In medieval times we had banners for such identification. Each castle, or group of individuals, was using a distinctive banner. With the help of such a banner, you can identify the correct location. This is in essence the same with certificates. A certificate is in other words an identification document linked to a location.
47 47  
53 +Sounds simple right? But what if an evil warlord creates an identical banner (i.e. certificate)? How can you discern between those two certificates? To guard against these practices you can sign a certificate. In medieval times documents would have been signed with a sigil for example. Nowadays we call that the private key.
54 +
55 +To summarize a certificate contains a public part (that can be distributed freely to all within the realm) and a private part (that you should guard with your life).
56 +
57 +The next step of the complexity lies in the private key. How can you know for sure that the private key is unique and trustworthy? What guarantees do you have when the other party has issued their private key? Such practice is what we call a self-signed certificate.
58 +
59 +To mitigate these practices we have entities in the world called Certificate Authorities (CA). Such a CA will sign the certificate to ensure that the certificates can be trusted by others.
60 +
61 +If you look for example at a server certificate (accessible via the lock icon in your browser) you will see that a certificate is issued to a certain domain, issued by a certain entity (CA), and has a certain expiration date. You can even see the full certificate chain (i.e. a certificate is signed by a certificate that is signed by another certificate). Note that when a certificate higher up in the chain is blacklisted (because of fraudulent practices) all certificates that were signed by that certificate are also automatically blacklisted.
62 +
63 +[[image:Main.Images.Microlearning.WebHome@novice-securing-your-data-traffic-what-are-certificates--server-certificate-chain.png]]
64 +
65 +In other words, certificates resolve all-around trust. As long as the certificate is trusted everything works well, the moment the certificate is not trusted any more communication will stop eventually.
66 +
67 +Above we have talked about you trusting the other party. But what about the other way around? How can the castle to which you are delivering the treasure trust who you are and now that you bring treasure?
68 +To prove that you are who you say you are you can hand them a certificate. We call that a client certificate.
69 +
70 +To recap, you have a server certificate (belonging to the party that receives the request) and you have a client certificate (belonging to the party that executes the request). With the help of a client certificate, a server can limit who can gain access to the server based on the certificate they provide at the door. If a server is publicly accessible but makes use of a certificate we say the connection is secured with the help of one-way SSL (HTTPS traffic). If the server requires a client certificate we talk about two-way SSL.
71 +
72 +=== 3.2 What if I want to use a self-signed certificate? ===
73 +
74 +There is no technical requirement to always use certificates that are signed by a CA. Another approach is to create a self-signed certificate. This way the party that receives the request will look in the so-called truststore. The truststore houses all certificates (public keys) of trusted parties.
75 +
76 +By default, Java has such a truststore that contains all trusted CA's. Which CA's are located in the default Java truststore depends on the Java version you are currently running on. You can verify this by checking the cacerts truststore in the Java installation located in "pathToJava\lib\security\cacerts". In case the server deviates from this you should create your truststore which should include the certificate of the server you want to call.
77 +
78 +Logically when you want to reply (or send something) you want to sign your certificate with something that is only known to you. To store this safely you can use a keystore. In here you store the secret that is only known to you (the private key) for safekeeping.
79 +
80 +The combination of such a private key and a public key is called a key pair.
81 +
82 +=== 3.3 How to get your key signed by a trusted party ===
83 +
84 +In some cases, an external party with whom we do business asks us to manage the certificate but has the requirement that the certificate that we have created and manage needs to be signed by a trusted party before it can be used in the field. To do you need to create a certificate signing request. You can do this with the help of tools such as Keystore Explorer, more on the technical details in a later microlearning.
85 +
86 +When you generate a certificate or a certificate signing request you need to create a key pair. The most crucial part of this process is the common name (CN). For Server certificates, this should contain the URL, for Client certificates this should be a client name or a client id. The best practice is to use the technical name of the runtime in eMagiz (possibly in conjunction with the tenant name in case of multi-tenancy).
87 +
88 +After you have configured this correctly you should secure it via a password and save it. From here on you can create a certificate signing request (CSR). After a while, you will get a response back from the CA. You can link this to your keypair via an Import CA Reply. The result can be seen in Keystore Explorer.
89 +
90 +=== 3.4 Encryption ===
91 +
92 +To ensure encryption the client locks the data with the help of the public key in a format that can only be read by the intended party. At that point, only the party that has the matching private key has the option to decrypt the message and process it.
93 +
94 +
95 +
48 48  == 4. Assignment ==
49 49  
50 -Configure an exit in which you call a SOAP web service and make sure that you send along a keystore and a truststore with the call.
98 +Read up on certificates and how they work in communication with other parties and see if you get what the function of certificates is.
51 51  
52 52  == 5. Key takeaways ==
53 53  
54 54  * Certificates are all about trust
55 -* With the help of the SSL web service message sender you can use certificates when calling a SOAP web service
56 -* Always remember that eMagiz uses prefixes to make resources unique
103 +* When a certificate is trusted by a CA it is natively trusted by others
104 +* In the case of self-signed certificates you need key stores and truststores to keep the private and public info secure
105 +* With the help of a certificate signing request (CSR) you can let a CA sign your certificate
57 57  
107 +
108 +
58 58  == 6. Suggested Additional Readings ==
59 59  
60 60  If you are interested in this topic and want more information on it please read the release notes provided by eMagiz
... ... @@ -61,6 +61,6 @@
61 61  
62 62  == 7. Silent demonstration video ==
63 63  
64 -{{video attachment="novice-securing-your-data-traffic-sending-certificates-to-a-webservice.mp4" reference="Main.Videos.Microlearning.WebHome"/}}
115 +{{video url="https://youtu.be/7TxZGQKXZnQ" attachment="Certificates * The Adventure" videoPoster="http://i.imgur.com/Ot5DWAW.png"/}}
65 65  
66 66  )))((({{toc/}}))){{/container}}{{/container}}