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

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -novice-securing-your-data-traffic-sending-certificates-to-a-webservice
1 +Sending certificates to a webservice
Content
... ... @@ -1,117 +1,69 @@
1 1  {{container}}{{container layoutStyle="columns"}}(((
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.
2 +In this microlearning, we’ll focus on how to send a client certificate to a SOAP web service and how to configure eMagiz to trust these certificates. Certificates are essential for verifying identities and ensuring secure communication. We’ll guide you through the steps needed to properly set up your keystore and truststore, link them to your flow, and use them for secure SOAP web service calls. By the end, you'll know how to configure these settings in eMagiz to establish trust and secure your data exchanges.
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 -
9 9  == 1. Prerequisites ==
10 10  * Basic knowledge of the eMagiz platform
8 +* Basic Understanding of certificates
9 +* Valid Keystore (and Truststore)
11 11  
12 12  == 2. Key concepts ==
13 -This microlearning centers around what are certificates.
12 +This microlearning centers around learning how to send a client certificate (and potentially trust a client certificate).
14 14  
15 15  By certificates we mean: A trustworthy document that is interchanged between parties to verify that both parties are who they claim to be
16 16  
17 -Certificates can be used in many forms. Two distinct forms are:
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.
18 18  
19 -* Authenticate
20 -* Encrypt
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.
21 21  
22 -Within eMagiz we usually see that configurable certificates are used for authentication:
23 -* eMagiz to an external party
24 -* External party to eMagiz
21 +== 3. Sending certificates to a webservice
25 25  
23 +In this microlearning, we will learn how you can send a certificate to a SOAP web service.
26 26  
27 -
28 -== 3. What are certificates ==
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.
29 29  
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.
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.
31 31  
32 -Certificates can be used in many forms. Two distinct forms are:
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.
33 33  
34 -* Authenticate
35 -* Encrypt
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:
36 36  
37 -Within eMagiz we usually see that configurable certificates are used for authentication:
38 -* eMagiz to an external party
39 -* External party to eMagiz
34 +[[image:Main.Images.Microlearning.WebHome@novice-securing-your-data-traffic-sending-certificates-to-a-webservice--resource-overview.png]]
40 40  
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:
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.
42 42  
43 -* What are certificates used for?
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).
44 44  
45 -=== 3.1 What are certificates used for? ===
40 +[[image:Main.Images.Microlearning.WebHome@novice-securing-your-data-traffic-sending-certificates-to-a-webservice--ssl-web-service-message-sender-filled-in.png]]
46 46  
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.
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.
48 48  
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.)
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.
50 50  
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.
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.
52 52  
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.
48 +== 4. Key takeaways ==
54 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 -
96 -== 4. Assignment ==
97 -
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.
99 -
100 -== 5. Key takeaways ==
101 -
102 102  * Certificates are all about trust
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
51 +* With the help of the SSL web service message sender you can use certificates when calling a SOAP web service
52 +* Always remember that eMagiz uses prefixes to make resources unique
106 106  
54 +== 5. Suggested Additional Readings ==
107 107  
56 +* [[Novice (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Novice.WebHome||target="blank"]]
57 +** [[Securing Data Traffic (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Novice.Securing Data Traffic.WebHome||target="blank"]]
58 +*** [[What are certificates (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Novice.Securing Data Traffic.novice-securing-your-data-traffic-what-are-certificates.WebHome||target="blank"]]
59 +* [[Intermediate (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.WebHome||target="blank"]]
60 +** [[eMagiz Cloud Management (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.eMagiz Cloud Management.WebHome||target="blank"]]
61 +*** [[Certificates (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.eMagiz Cloud Management.intermediate-emagiz-cloud-management-certificates||target="blank"]]
62 +** [[REST Connectivity (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.REST Connectivity.WebHome||target="blank"]]
63 +*** [[Sending certificates to a REST web service (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.REST Connectivity.intermediate-rest-webservice-connectivity-certificates-when-calling-a-rest-webservice||target="blank"]]
64 +* [[RCA Knowledge Base (Menu)>>doc:Main.eMagiz Support.RCA Knowledge Base.WebHome||target="blank"]]
65 +** [[Runtime Issues (Navigation)>>doc:Main.eMagiz Support.RCA Knowledge Base.rca-knowledgebase-runtime-issues.WebHome||target="blank"]]
66 +*** [[Expiring Certificates (Explanation)>>doc:Main.eMagiz Support.RCA Knowledge Base.rca-knowledgebase-runtime-issues.rca-knowledgebase-expiring-certificates.WebHome||target="blank"]]
67 +* [[Certificate (Search Result)>>url:https://docs.emagiz.com/bin/view/Main/Search?sort=score&sortOrder=desc&highlight=true&facet=true&r=1&f_space_facet=0%2FMain.&f_type=DOCUMENT&f_locale=en&f_locale=&f_locale=en&text=%22certificate%22||target="blank"]]
108 108  
109 -== 6. Suggested Additional Readings ==
110 -
111 -If you are interested in this topic and want more information on it please read the release notes provided by eMagiz
112 -
113 -== 7. Silent demonstration video ==
114 -
115 -{{video url="https://youtu.be/7TxZGQKXZnQ" attachment="Certificates * The Adventure" videoPoster="http://i.imgur.com/Ot5DWAW.png"/}}
116 -
117 117  )))((({{toc/}}))){{/container}}{{/container}}