Skip to Content

Wiki source code of WS-Security

Last modified by Martijn Woudstra on 2022/06/10 16:22
Hide last authors
Martijn Woudstra 31.1 1 {{container}}{{container layoutStyle="columns"}}(((
2 Within eMagiz, there are multiple ways of handling security concerning SOAP Webservices. One of these methods is WS-Security. In this guide, we will look at WS-Security from the following viewpoints:
3
4 * What is WS-Security
5 * Calling an external SOAP Webservice that has secured their web service via WS-Security
6 * Securing an eMagiz SOAP Webservice with the help of WS-Security
7
8 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
9
10 * Last update: March 1st, 2021
11 * Required reading time: 8 minutes
12
13 == 1. Prerequisites ==
14
15 * Advanced knowledge of the eMagiz platform
16
17 == 2. Key concepts ==
18
19 Web Services Security (WS Security) is a specification that defines how security measures are implemented in web services to protect them from external attacks.
20 This is done via a set of protocols that ensure the principles of confidentiality, integrity, and authentication via security for SOAP-based messages.
21
22 These aims can be implemented by sending (a set of) WS-Security SOAP Headers along with the SOAP body. Examples of these headers are:
23 * UsernameToken
24 * Timestamp
25 * Encrypt
26 * Signature
27 * NoSecurity
28
29 == 3. WS-Security ==
30
31 Within eMagiz, there are multiple ways of handling security concerning SOAP Webservices. One of these methods is WS-Security. In this guide, we will look at WS-Security from the following viewpoints:
32
33 * What is WS-Security
34 * Calling an external SOAP Webservice that has secured their web service via WS-Security
35 * Securing an eMagiz SOAP Webservice with the help of WS-Security
36
37 === 3.1 What is WS-Security ===
38
39 Web Services Security (WS Security) is a specification that defines how security measures are implemented in web services to protect them from external attacks.
40 This is done via a set of protocols that ensure the principles of confidentiality, integrity, and authentication via security for SOAP-based messages.
41
42 WS-Security aims to ensure that communication between two parties is not interrupted or interpreted by an unauthorized third party.
43 The receiver needs to be assured that the sender indeed sent the message, and the sender should be guaranteed that the receiver cannot deny receiving the message.
44 Finally, an unauthorized source should not alter the data sent during communication.
45
46 These aims can be implemented by sending (a set of) WS-Security SOAP Headers along with the SOAP body. Examples of these headers are:
47 * UsernameToken
48 * Timestamp
49 * Encrypt
50 * Signature
51 * NoSecurity
52
53 For eMagiz hosted SOAP Webservice, we require the Signature option. What an external system needs depends on the requirements made by that system.
54
55 === 3.2 Calling an external SOAP Webservice that has secured its web service via WS-Security ===
56
57 To ensure that eMagiz creates the required SOAP headers on top of your SOAP message, you must add two support objects to the flow where you want to call the external web service (predominantly the exit).
58 These support objects are:
59
60 - Merlin crypto
61 - WSS4J security interceptor
62
63 In the merlin crypto support object, you need to reference the Keystore you need to authenticate yourself with the external party. This Keystore should hold the correct key to access the web service.
64
65 [[image:Main.Images.Microlearning.WebHome@expert-webservice-security-ws-security--ws-security-merlin-crypto-exit.png]]
66
67 The WSS4J support object should be filled based on the specifications delivered by the external party. Below you will find a standard implementation of WS-Security for an external SOAP web service. You need to fill in details on the basic and securement level for this to work.
68
69 [[image:Main.Images.Microlearning.WebHome@expert-webservice-security-ws-security--ws-security-wss4j-crypto-exit-basic.png]]
70
71 [[image:Main.Images.Microlearning.WebHome@expert-webservice-security-ws-security--ws-security-wss4j-crypto-exit-securement.png]]
72
73 To make sure that the actual headers are sent as part of the SOAP web service call eMagiz will execute, you must link the WSS4J security interceptor as interceptor on your web service outbound gateway.
74 If you have done so, your configuration of WS-Security will be correct.
75
76 [[image:Main.Images.Microlearning.WebHome@expert-webservice-security-ws-security--ws-security-wss4j-crypto-exit-interceptor.png]]
77
78 You can test the setup by sending a message via eMagiz towards this SOAP web service to see if you correctly implement the requirements of the external party.
79
80 === 3.3 Securing an eMagiz SOAP Webservice with the help of WS-Security ===
81
82 To ensure that eMagiz can validate the incoming requests for the validity of the correct WS-Security SOAP headers, you need to add one support object and add a wss4j security validating interceptor to the message dispatcher component.
83
84 The support object you need to link to the entry is:
85
86 * Merlin crypto
87
88 In the merlin crypto support object, you need to reference the truststore where you store the public certificate against which the external needs to authenticate themselves.
89
90 [[image:Main.Images.Microlearning.WebHome@expert-webservice-security-ws-security--ws-security-merlin-crypto-entry.png]]
91
92 Next to adding the support object, you must open the message dispatcher support object. Within this component, you select the payload root QName endpoint mapping for which you want to add the WS-Security settings and press Edit.
93 In the following pop-up, you can navigate to the Advanced tab, select the WSS4J security interceptor and configure this component as follows.
94
95 [[image:Main.Images.Microlearning.WebHome@expert-webservice-security-ws-security--ws-security-wss4j-crypto-entry-basic.png]]
96
97 [[image:Main.Images.Microlearning.WebHome@expert-webservice-security-ws-security--ws-security-wss4j-crypto-entry-validation.png]]
98
99 If you have configured this correctly, you will have something like this.
100
101 [[image:Main.Images.Microlearning.WebHome@expert-webservice-security-ws-security--ws-security-wss4j-crypto-entry-result.png]]
102
103 When you are done with the configuration, you can deploy the flow via Releases or straight from the flow if you have a Test environment and ask the external party to send a message towards your endpoint so you can validate the result.
104
105 == 4. Assignment ==
106
107 Define the correct configuration of calling an external web service from an exit flow in eMagiz that requires WS-security to be sent along with the call. You can execute this assignment on the model you have used for the previous lessons.
108
109 == 5. Key takeaways ==
110
111 * Web Services Security (WS Security) is a specification that defines how security measures are implemented in web services to protect them from external attacks.
112 * These information elements can be added via specific components in eMagiz
113 * Which information elements are needed is determined by the external party
114
115 == 6. Suggested Additional Readings ==
116
117 If you are interested in this topic and want more information on it please read the help text provided by eMagiz.
118
119 == 7. Silent demonstration video ==
120
121 This video demonstrates how you could have handled the assignment and gives you some context on what you have just learned.
122
123 {{video attachment="expert-webservice-security-ws-security.mp4" reference="Main.Videos.Microlearning.WebHome"/}}
124
125 )))((({{toc/}}))){{/container}}{{/container}}