Securing a hosted web service with certificates on-premise

{{container}}{{container layoutStyle="columns"}}(((

Note that the functionality mentioned in this microlearning only applies to the [[current runtime>>doc:Main.eMagiz Academy.Fundamentals.fundamental-runtime-generation3||target="blank"]] architecture.

4

5

6

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.

7

8

Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].

9

10

== 1. Prerequisites ==

11

12

* Basic knowledge of the eMagiz platform

13

* Basic understanding of certificates

14

* The flow that hosts the web service is successfully created and about to be deployed to the correct environment

15

16

== 2. Key concepts ==

17

18

This microlearning centers around learning how to secure the (SOAP/REST) web service you created in eMagiz, which will run on-premise.

19

* By certificates, we mean: A trustworthy document that is interchanged between parties to verify that both parties are who they claim to be.

20

21

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.

22

23

This microlearning will focus on the certificate part, including HTTPS and TLS, which can be configured for web services running on-premise.

24

25

* Configuration of the SSL configuration (HTTPS, TLS, and client certificates) is done in Deploy -> Architecture

26

* Certificate is generated via the support department (with or without CSR) or the client

27

* No actions are needed on the flow level, only in the Deploy Architecture

28

* You need a valid truststore and keystore to make it work

29

30

== 3. Securing a hosted web service with certificates on-premise ==

31

32

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).

33

34

[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--runtime-settings.png]]

35

36

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".

37

38

[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--http-enabled.png]]

39

40

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.

41

42

[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--http-settings.png]]

43

44

As a result, we will toggle the "SSL enabled" option to "Yes." Two new tabs will then be shown to the user.

45

46

[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--ssl-enabled.png]]

47

48

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.

49

50

=== 3.1 Protocol (TLS) configuration ===

51

52

Under the SSL tab, you can define this web service's (enabled) protocols. This concerns the (allowed) [[TLS>>https://www.internetsociety.org/deploy360/tls/basics/||target="blank"]] 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.

53

54

[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--tls-protocol.png]]

55

56

Once done, you have defined that your endpoint only supports communication via the TLS v1.3 protocol.

57

58

{{info}}Note that the following options are allowed to be filled in for both the protocol and the enabled protocols option:

* TLSv1.2

* TLSv1.3{{/info}}

=== 3.2 HTTPS configuration ===

63

64

Under the Keystore tab, you need to define the keystore used to grant the endpoint the HTTPS status (instead of) HTTP.

65

66

[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--keystore-config-empty.png]]

67

68

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.

69

70

[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--keystore-config.png]]

71

72

Once done, you have configured your endpoint as an HTTPS endpoint.

73

74

{{info}}As a best practice, we advise using a keystore containing only **one** keypair to avoid confusion while updating entries in the Keystore. {{/info}}

75

76

=== 3.3 Client certificate ===

77

78

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.

79

80

[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--client-certificate-config.png]]

81

82

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.

83

84

[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--truststore-config.png]]

85

86

Once configuring your endpoint, clients must provide a client certificate to exchange data.

87

88

=== 3.4 Deployment ===

89

90

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:

95

96

* Configuration of the SSL configuration (HTTPS, TLS, and client certificates) is done in Deploy -> Architecture

97

* Certificate is generated via the support department (with or without CSR) or the client

98

* No actions are needed on the flow level, only in the Deploy Architecture

99

* You need a valid truststore and keystore to make it work

100

101

== 4. Key takeaways ==

102

103

* Certificates are essential for establishing and verifying trust between parties in web services.

104

* Use the Deploy -> Architecture section to set up SSL configurations, including HTTPS, TLS, and client certificates for your on-premise eMagiz runtime.

105

* Securing web services can be a complex task to do, so take care with configurations and verify each step to ensure proper security.

106

107

== 5. Suggested Additional Readings ==

108

109

If you are interested in this topic and want more information, please read the help text provided by eMagiz and see the following links:

110

111

* [[Novice Level (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Novice.WebHome||target="blank"]]

112

** [[SOAP Web Service Connectivity (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Novice.SOAP Web service Connectivity.WebHome||target="blank"]]

113

*** [[Securing your SOAP Webservice (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Novice.SOAP Web service Connectivity.novice-soap-webservice-connectivity-securing-your-soap-webservice||target="blank"]]

114

* [[Intermediate Level (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.WebHome||target="blank"]]

115

** [[eMagiz Cloud Management (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.eMagiz Cloud Management.WebHome||target="blank"]]

116

*** [[Certificates (Explanation)>>Main.eMagiz Academy.Microlearnings.Intermediate Level.eMagiz Cloud Management.intermediate-emagiz-cloud-management-certificates||target="blank"]]

117

** [[Securing Data Traffic (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Securing Data Traffic.WebHome||target="blank"]]

118

*** [[Creating a JKS (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Securing Data Traffic.intermediate-securing-your-data-traffic-creating-a-jks||target="blank"]]

119

** [[REST Connectivity (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.REST Connectivity.WebHome||target="blank"]]

120

*** [[Configuration REST web service (Explanation)>>Main.eMagiz Academy.Microlearnings.Intermediate Level.REST Connectivity.intermediate-rest-webservice-connectivity-configuration-gen3.WebHome||target="blank"]]

121

* [[Securing a hosted web service (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=%22securing+a+hosted+web+service%22||target="blank"]]

122

123

)))((({{toc/}}))){{/container}}{{/container}}

author	version	line-number	content
		1	{{container}}{{container layoutStyle="columns"}}(((
		2	{{warning}}
		3	Note that the functionality mentioned in this microlearning only applies to the [[current runtime>>doc:Main.eMagiz Academy.Fundamentals.fundamental-runtime-generation3\|\|target="blank"]] architecture.
		4	{{/warning}}
		5
		6	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.
		7
		8	Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
		9
		10	== 1. Prerequisites ==
		11
		12	* Basic knowledge of the eMagiz platform
		13	* Basic understanding of certificates
		14	* The flow that hosts the web service is successfully created and about to be deployed to the correct environment
		15
		16	== 2. Key concepts ==
		17
		18	This microlearning centers around learning how to secure the (SOAP/REST) web service you created in eMagiz, which will run on-premise.
		19	* By certificates, we mean: A trustworthy document that is interchanged between parties to verify that both parties are who they claim to be.
		20
		21	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.
		22
		23	This microlearning will focus on the certificate part, including HTTPS and TLS, which can be configured for web services running on-premise.
		24
		25	* Configuration of the SSL configuration (HTTPS, TLS, and client certificates) is done in Deploy -> Architecture
		26	* Certificate is generated via the support department (with or without CSR) or the client
		27	* No actions are needed on the flow level, only in the Deploy Architecture
		28	* You need a valid truststore and keystore to make it work
		29
		30	== 3. Securing a hosted web service with certificates on-premise ==
		31
		32	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).
		33
		34	[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--runtime-settings.png]]
		35
		36	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".
		37
		38	[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--http-enabled.png]]
		39
		40	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.
		41
		42	[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--http-settings.png]]
		43
		44	As a result, we will toggle the "SSL enabled" option to "Yes." Two new tabs will then be shown to the user.
		45
		46	[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--ssl-enabled.png]]
		47
		48	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.
		49
		50	=== 3.1 Protocol (TLS) configuration ===
		51
		52	Under the SSL tab, you can define this web service's (enabled) protocols. This concerns the (allowed) [[TLS>>https://www.internetsociety.org/deploy360/tls/basics/\|\|target="blank"]] 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.
		53
		54	[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--tls-protocol.png]]
		55
		56	Once done, you have defined that your endpoint only supports communication via the TLS v1.3 protocol.
		57
		58	{{info}}Note that the following options are allowed to be filled in for both the protocol and the enabled protocols option:
		59	* TLSv1.2
		60	* TLSv1.3{{/info}}
		61
		62	=== 3.2 HTTPS configuration ===
		63
		64	Under the Keystore tab, you need to define the keystore used to grant the endpoint the HTTPS status (instead of) HTTP.
		65
		66	[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--keystore-config-empty.png]]
		67
		68	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.
		69
		70	[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--keystore-config.png]]
		71
		72	Once done, you have configured your endpoint as an HTTPS endpoint.
		73
		74	{{info}}As a best practice, we advise using a keystore containing only one keypair to avoid confusion while updating entries in the Keystore. {{/info}}
		75
		76	=== 3.3 Client certificate ===
		77
		78	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.
		79
		80	[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--client-certificate-config.png]]
		81
		82	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.
		83
		84	[[image:Main.Images.Microlearning.WebHome@intermediate-securing-your-data-traffic-securing-a-hosted-webservice-with-certificates-on-premise--truststore-config.png]]
		85
		86	Once configuring your endpoint, clients must provide a client certificate to exchange data.
		87
		88	=== 3.4 Deployment ===
		89
		90	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.
		91
		92	=== 3.5 Recap ===
		93
		94	Important things to remember are:
		95
		96	* Configuration of the SSL configuration (HTTPS, TLS, and client certificates) is done in Deploy -> Architecture
		97	* Certificate is generated via the support department (with or without CSR) or the client
		98	* No actions are needed on the flow level, only in the Deploy Architecture
		99	* You need a valid truststore and keystore to make it work
		100
		101	== 4. Key takeaways ==
		102
		103	* Certificates are essential for establishing and verifying trust between parties in web services.
		104	* Use the Deploy -> Architecture section to set up SSL configurations, including HTTPS, TLS, and client certificates for your on-premise eMagiz runtime.
		105	* Securing web services can be a complex task to do, so take care with configurations and verify each step to ensure proper security.
		106
		107	== 5. Suggested Additional Readings ==
		108
		109	If you are interested in this topic and want more information, please read the help text provided by eMagiz and see the following links:
		110
		111	* [[Novice Level (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Novice.WebHome\|\|target="blank"]]
		112	** [[SOAP Web Service Connectivity (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Novice.SOAP Web service Connectivity.WebHome\|\|target="blank"]]
		113	*** [[Securing your SOAP Webservice (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Novice.SOAP Web service Connectivity.novice-soap-webservice-connectivity-securing-your-soap-webservice\|\|target="blank"]]
		114	* [[Intermediate Level (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.WebHome\|\|target="blank"]]
		115	** [[eMagiz Cloud Management (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.eMagiz Cloud Management.WebHome\|\|target="blank"]]
		116	*** [[Certificates (Explanation)>>Main.eMagiz Academy.Microlearnings.Intermediate Level.eMagiz Cloud Management.intermediate-emagiz-cloud-management-certificates\|\|target="blank"]]
		117	** [[Securing Data Traffic (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Securing Data Traffic.WebHome\|\|target="blank"]]
		118	*** [[Creating a JKS (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Securing Data Traffic.intermediate-securing-your-data-traffic-creating-a-jks\|\|target="blank"]]
		119	** [[REST Connectivity (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.REST Connectivity.WebHome\|\|target="blank"]]
		120	*** [[Configuration REST web service (Explanation)>>Main.eMagiz Academy.Microlearnings.Intermediate Level.REST Connectivity.intermediate-rest-webservice-connectivity-configuration-gen3.WebHome\|\|target="blank"]]
		121	* [[Securing a hosted web service (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=%22securing+a+hosted+web+service%22\|\|target="blank"]]
		122
		123	)))((({{toc/}}))){{/container}}{{/container}}

Wiki source code of Securing a hosted web service with certificates on-premise

Navigation