Enportal/5.5/admin/ssl configuration - Revision history

imported>Jason.nicholls at 09:19, 20 March 2015

2015-03-20T09:19:03Z

← Older revision		Revision as of 09:19, 20 March 2015
Line 1:		Line 1:
			{{DISPLAYTITLE:SSL Configuration}}
	[[Category:enPortal 5.5]]		[[Category:enPortal 5.5]]
	~~{{DISPLAYTITLE:SSL Configuration}}~~
	== Overview ==		== Overview ==
	For security reasons it's recommended to run enPortal over SSL (Secure Socket Layer). This will ensure all communications between clients (browsers) and the enPortal server are encrypted.		For security reasons it's recommended to run enPortal over SSL (Secure Socket Layer). This will ensure all communications between clients (browsers) and the enPortal server are encrypted.

imported>Jason.nicholls at 09:18, 20 March 2015

2015-03-20T09:18:43Z

← Older revision		Revision as of 09:18, 20 March 2015
Line 2:		Line 2:
	{{DISPLAYTITLE:SSL Configuration}}		{{DISPLAYTITLE:SSL Configuration}}
	== Overview ==		== Overview ==

	For security reasons it's recommended to run enPortal over SSL (Secure Socket Layer). This will ensure all communications between clients (browsers) and the enPortal server are encrypted.		For security reasons it's recommended to run enPortal over SSL (Secure Socket Layer). This will ensure all communications between clients (browsers) and the enPortal server are encrypted.

imported>Jason.nicholls at 09:15, 20 March 2015

2015-03-20T09:15:23Z

← Older revision		Revision as of 09:15, 20 March 2015
Line 1:		Line 1:
	[[Category:enPortal 5.5]]		[[Category:enPortal 5.5]]
	{{DISPLAYTITLE:SSL Configuration}}		{{DISPLAYTITLE:SSL Configuration}}

	== Overview ==		== Overview ==

	For security reasons it's recommended to run ~~AppBoard~~ over SSL (Secure Socket Layer). This will ensure all communications between clients (browsers) and the ~~AppBoard~~ server are encrypted.		For security reasons it's recommended to run enPortal over SSL (Secure Socket Layer). This will ensure all communications between clients (browsers) and the enPortal server are encrypted.

	By default enPortal is configured with SSL disabled, but it does ship with a self-signed server certificate and can easily be enabled. In production environments this certificate should be replaced with one issued by a known Certificate Authority (CA) or one signed by a trusted root certificate within the organization.		By default enPortal is configured with SSL disabled, but it does ship with a self-signed server certificate and can easily be enabled. In production environments this certificate should be replaced with one issued by a known Certificate Authority (CA) or one signed by a trusted root certificate within the organization.
Line 10:		Line 9:
	== Configuring enPortal for SSL ==		== Configuring enPortal for SSL ==

	~~To enable HTTPS (HTTP over SSL) mode use the <tt>HTTP_SSL</tt> runtime option and set it to <tt>true</tt>. In addition you may want to also change~~:		The overall process involves:

	* <tt>HTTP_PORT</tt>: HTTPS is typically served on port 443
	* <tt>KEYSTORE_FILE</tt>: if using your own certificate
	* <tt>KEYSTORE_PASS</tt>: if using your own certificate
	* <tt>KEYSTORE_TYPE</tt>: if using your own certificate

	See the [[enportal/5.5/admin/enPortal_installation/installation/runtime_options\|Runtime Options]] page for more information on these settings and how to configure them. After making any changes then restart the enPortal service.

	~~{{Warning\|Do not configure SSL by editing~~ the ~~enPortal server~~.~~xml file~~ as ~~this is~~ a ~~system file~~ and ~~replaced~~ on ~~upgrade~~. ~~The correct way~~ is ~~to edit~~ the ~~runtime options~~.}}		# Obtaining a signed certificate:
			## Pick a Certificate Authority, this may be in-house if the organization has a Standard Operating Environment with their own root certificate installed on all systems. Otherwise this would be a commercial CA such as VeriSign, Thawte, or Go Daddy.
			## Create a private key and Certificate Signing Request (CSR)
			## Have the CA sign the request
			## Download the signed certificate from the CA. Depending on the CA a variety of formats may be on offer. Choose an appropriate format for Tomcat - which the CA may explicitly list as an option, otherwise choose PKCS#7 format. Other formats may require additional conversion steps before Tomcat can make use of it.
			# Alternatively create a self-signed certificate. However, end-users will be presented with certificate errors and warnings as the certificate is not signed by a trusted authority.
			# Create a Java KeyStore (JKS) from the private key, signed certificate, and any intermediate certificates from the CA.
			# Install they keystore file on the enPortal server.

	~~=== Process Overview ===~~		{{Note\|Due to the large variety of certificate authorities and key/certificate formats, this documentation does not cover all possibilities. If following instructions found elsewhere make sure to install the resulting keystore correctly for enPortal (see the ''Enable SSL & Install the Keystore'' section).}}

	~~The basic process is:~~		=== Certificate & Keystore ===

	~~# pick~~ a ~~Certificate Authority, this may be in-house if~~ the ~~organization has a Standard Operating Environment with their own root certificate installed on all systems. Otherwise this would be a commercial CA such as VeriSign~~, ~~Thawte, or Go Daddy.~~		For SSL Tomcat requires a Java keystore containing the private key, signed certificate, and any intermediate certificates from the CA. To create and work with a keystore it is necessary to have Java installed and be able to run the <tt>keytool</tt> command.
	~~# create a Certificate Signing Request (CSR)~~
	~~# have the CA sign the request~~
	~~# download the~~ signed certificate from the CA. ~~Depending on the CA~~ a variety of formats may be on offer. Choose an appropriate format for Tomcat - which the CA may explicitly list as an option, otherwise choose PKCS#7 format. Other formats may require additional conversion steps before Tomcat can make use of it.
	~~# create a~~ Java ~~KeyStore (JKS) file for Tomcat~~ and ~~install on~~ the ~~enPortal server~~.

	Another option is to generate a self-signed certificate to replace the self-signed certificate Edge ships with enPortal. However, end-users will still be presented with certificate errors and warnings.		==== New Certificates ====
			The recommended approach is to use <tt>keytool</tt> to create the private key, CSR, and keystore. The CA with then sign and provide a signed certificate along with their own certificate chain which can be imported into the keystore. Most CAs have this process well documented for popular web server platforms. Just follow the instructions for Tomcat such as these from VeriSign - and remember to refer back to this documentation on installing the keystore:
	=== ~~Creating Certificate & Keystore~~ ===

	For SSL Tomcat requires a Java KeyStore (JKS). The keystore needs to contain the private key, the signed certificate, and any intermediate certificates from the CA. To create and work with a keystore it is necessary to have Java installed and be able to run the <tt>keytool</tt> command.

	The recommended approach is to use <tt>keytool</tt> to create the private key ~~and~~ CSR and keystore ~~all in one go,~~ then ~~have the CA~~ sign, and ~~then import the~~ signed certificate ~~directly~~ into the keystore. Most CAs ~~will~~ have ~~documented~~ this process ~~which can be followed~~ such as these from VeriSign:

	# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&id=AR227 creating a CSR and submitting for signing] (using keytool and creating a keystore in the process).		# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&id=AR227 creating a CSR and submitting for signing] (using keytool and creating a keystore in the process).
	# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&actp=CROSSLINK&id=AR153 importing the signed certificate into a JKS keystore] (in PKCS#7 / .p7b format)		# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&actp=CROSSLINK&id=AR153 importing the signed certificate into a JKS keystore] (in PKCS#7 / .p7b format)
	# Then follow the instructions below on Installing the Keystore.		# Then follow the instructions below on ''Enable SSL & Installing the Keystore''


			==== Existing Keys & Certificates ====
	A limitation of keytool is that existing private keys cannot be imported. So for situations with an '''existing private key''', and regardless of the certificate format then it will be necessary to use <tt>openssl</tt> to do conversion.		A limitation of keytool is that existing private keys cannot be imported. So for situations with an '''existing private key''', and regardless of the certificate format then it will be necessary to use <tt>openssl</tt> to do conversion.

Line 54:		Line 44:
	#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype PCKS12 -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>		#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype PCKS12 -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>
	#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).		#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).
	# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below on Installing the Keystore.		# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below to ''Enable SSL & Installing the Keystore''.

	For existing private key with signed certificate and intermediate certificates in PKCS#7 (.p7b) format follow these steps:		For existing private key with signed certificate and intermediate certificates in PKCS#7 (.p7b) format follow these steps:
Line 65:		Line 55:
	#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype PCKS12 -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>		#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype PCKS12 -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>
	#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).		#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).
	# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below on Installing the Keystore.		# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below to ''Enable SSL & Installing the Keystore''.

	=== ~~Installing~~ the Keystore ===		=== Enable SSL & Install the Keystore ===

	Once a valid keystore has been created it can be installed on the enPortal server:		Once a valid keystore has been created it can be installed on the enPortal server:

	# copy to the <tt>[INSTALL_HOME]/server/conf/ssl.crt/</tt> directory. By default files in this directory are automatically included in full archives.		# copy to the <tt>[INSTALL_HOME]/server/conf/ssl.crt/</tt> directory. By default files in this directory are automatically included in full archives.
	# Edit <tt>setenv-custom.sh\|.bat</tt> and update the <tt>KEYSTORE_FILE</tt>, <tt>KEYSTORE_PASS~~</tt>, and <tt>KEYSTORE_TYPE~~</tt> as required~~. If using the instructions above then the type should not need to be changed~~. Please note the keystore file path is relative to <tt>[INSTALL_HOME]/server/</tt>		# Edit <tt>setenv-custom.sh\|.bat</tt> and:
	# ~~As noted previously also make sure~~ the <tt>HTTP_SSL</tt> option ~~is set~~ to <tt>true</tt>.		## update the <tt>KEYSTORE_FILE</tt> and <tt>KEYSTORE_PASS</tt> as required. Please note the keystore file path is relative to <tt>[INSTALL_HOME]/server/</tt>
			## update the <tt>KEYSTORE_TYPE</tt> if using something other than Java KeyStore (JKS) format.
			## set the <tt>HTTP_SSL</tt> option to <tt>true</tt>.
			## (optionally) set the <tt>HTTP_PORT</tt> to the desired port.
	# Restart the enPortal server.		# Restart the enPortal server.

			See the [[enportal/5.5/admin/enPortal_installation/installation/runtime_options\|Runtime Options]] page for complete information on all runtime options.

	== Redirecting HTTP traffic ==		== Redirecting HTTP traffic ==

imported>Jason.nicholls: /* Creating Certificate & Keystore */

2015-03-20T08:58:01Z

Creating Certificate & Keystore

← Older revision		Revision as of 08:58, 20 March 2015
Line 50:		Line 50:
	# Convert the private key (''private.key''), signed certificate (''server_signed.crt''), and intermediate certificates (''ca.crt'') into PKCS#12 format:		# Convert the private key (''private.key''), signed certificate (''server_signed.crt''), and intermediate certificates (''ca.crt'') into PKCS#12 format:
	#: <tt>openssl pkcs12 -export -in ''server_signed.crt'' -inkey ''private.key'' -CAfile ''ca.crt'' -caname root -chain -out combined.p12 -name ''your-alias''</tt>		#: <tt>openssl pkcs12 -export -in ''server_signed.crt'' -inkey ''private.key'' -CAfile ''ca.crt'' -caname root -chain -out combined.p12 -name ''your-alias''</tt>
	#: You will be prompted to ~~enter~~ a password, ~~make sure you~~ set ~~a password (~~do not leave blank). If you do not have any intermediate certificates then leave out the <tt>-CAfile</tt>, <tt>-caname</tt>, and <tt>-chain</tt> options.		#: You will be prompted to set a password, this '''must''' be set - do not leave blank. If you do not have any intermediate certificates then leave out the <tt>-CAfile</tt>, <tt>-caname</tt>, and <tt>-chain</tt> options.
	# Create a JKS from the <tt>combined.p12</tt> file generated above:		# Create a JKS from the <tt>combined.p12</tt> file generated above:
	#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype PCKS12 -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>		#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype PCKS12 -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>
Line 58:		Line 58:
	For existing private key with signed certificate and intermediate certificates in PKCS#7 (.p7b) format follow these steps:		For existing private key with signed certificate and intermediate certificates in PKCS#7 (.p7b) format follow these steps:
	# Convert the PKCS7 file (''certs.p7b'') to PEM encoded certificates:		# Convert the PKCS7 file (''certs.p7b'') to PEM encoded certificates:
	#: <tt>openssl pkcs7 -in ''certs.p7b'' -inform DER -print_certs -out ''certs.crt''		#: <tt>openssl pkcs7 -in ''certs.p7b'' -inform DER -print_certs -out ''certs.crt''</tt>
			# Convert the private key (''private.key'') and certificates (''certs.crt'' from above):
			#: <tt>openssl pkcs12 -export -in ''certs.crt'' -inkey ''private.key'' -out combined.p12 -name ''your-alias''</tt>
			#: You will be prompted to set a password, this '''must''' be set - do not leave blank.
			# Create a JKS from the <tt>combined.p12</tt> file generated above:
			#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype PCKS12 -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>
			#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).
			# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below on Installing the Keystore.

	=== Installing the Keystore ===		=== Installing the Keystore ===

imported>Jason.nicholls: /* Creating Certificate & Keystore */

2015-03-20T08:46:46Z

Creating Certificate & Keystore

← Older revision		Revision as of 08:46, 20 March 2015
Line 37:		Line 37:
	For SSL Tomcat requires a Java KeyStore (JKS). The keystore needs to contain the private key, the signed certificate, and any intermediate certificates from the CA. To create and work with a keystore it is necessary to have Java installed and be able to run the <tt>keytool</tt> command.		For SSL Tomcat requires a Java KeyStore (JKS). The keystore needs to contain the private key, the signed certificate, and any intermediate certificates from the CA. To create and work with a keystore it is necessary to have Java installed and be able to run the <tt>keytool</tt> command.

	The recommended approach is to use <tt>keytool</tt> to create the private key and CSR and keystore all in one go, then have the CA sign, and then import the signed certificate ~~using PKCS#7 format~~ directly into the keystore. ~~This~~ process ~~is well outlined in the~~ VeriSign ~~documentation below~~:		The recommended approach is to use <tt>keytool</tt> to create the private key and CSR and keystore all in one go, then have the CA sign, and then import the signed certificate directly into the keystore. Most CAs will have documented this process which can be followed such as these from VeriSign:

	# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&id=AR227 creating a CSR and submitting for signing] (using keytool and creating a keystore in the process).		# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&id=AR227 creating a CSR and submitting for signing] (using keytool and creating a keystore in the process).
Line 44:		Line 44:


	A limitation of keytool is that existing private keys cannot be imported. So for situations with an existing private key, and regardless of the certificate format then it will be necessary to use <tt>openssl</tt> to do conversion.		A limitation of keytool is that existing private keys cannot be imported. So for situations with an '''existing private key''', and regardless of the certificate format then it will be necessary to use <tt>openssl</tt> to do conversion.

	For existing private key with signed certificate and intermediate certificates in X.509 format follow these steps:		For existing private key with signed certificate and intermediate certificates in X.509 format follow these steps:
Line 57:		Line 57:

	For existing private key with signed certificate and intermediate certificates in PKCS#7 (.p7b) format follow these steps:		For existing private key with signed certificate and intermediate certificates in PKCS#7 (.p7b) format follow these steps:
			# Convert the PKCS7 file (''certs.p7b'') to PEM encoded certificates:
			#: <tt>openssl pkcs7 -in ''certs.p7b'' -inform DER -print_certs -out ''certs.crt''

	=== Installing the Keystore ===		=== Installing the Keystore ===

imported>Jason.nicholls: /* Creating Certificate & Keystore */

2015-03-20T08:35:59Z

Creating Certificate & Keystore

← Older revision		Revision as of 08:35, 20 March 2015
Line 43:		Line 43:
	# Then follow the instructions below on Installing the Keystore.		# Then follow the instructions below on Installing the Keystore.

	~~However, if you already have~~ an existing private key, ~~signed~~ certificate~~, and intermediate certificates in X.509~~ format then ~~some conversion is required before importing into a JKS. This process~~ will ~~require~~ <tt>openssl</tt>.
			A limitation of keytool is that existing private keys cannot be imported. So for situations with an existing private key, and regardless of the certificate format then it will be necessary to use <tt>openssl</tt> to do conversion.

			For existing private key with signed certificate and intermediate certificates in X.509 format follow these steps:

	# Convert the private key (''private.key''), signed certificate (''server_signed.crt''), and intermediate certificates (''ca.crt'') into PKCS#12 format:		# Convert the private key (''private.key''), signed certificate (''server_signed.crt''), and intermediate certificates (''ca.crt'') into PKCS#12 format:
Line 52:		Line 55:
	#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).		#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).
	# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below on Installing the Keystore.		# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below on Installing the Keystore.

			For existing private key with signed certificate and intermediate certificates in PKCS#7 (.p7b) format follow these steps:

	=== Installing the Keystore ===		=== Installing the Keystore ===

imported>Jason.nicholls at 07:45, 20 March 2015

2015-03-20T07:45:59Z

← Older revision		Revision as of 07:45, 20 March 2015
Line 1:		Line 1:
	[[Category:enPortal 5.5]]		[[Category:enPortal 5.5]]
	{{DISPLAYTITLE:SSL Configuration}}		{{DISPLAYTITLE:SSL Configuration}}
	For security reasons it's recommended to run ~~enPortal~~ over SSL (Secure Socket Layer). This will ensure all communications between clients (browsers) and the ~~enPortal~~ server are encrypted.
			== Overview ==

			For security reasons it's recommended to run AppBoard over SSL (Secure Socket Layer). This will ensure all communications between clients (browsers) and the AppBoard server are encrypted.

	By default enPortal is configured with SSL disabled, but it does ship with a self-signed server certificate and can easily be enabled. In production environments this certificate should be replaced with one issued by a known Certificate Authority (CA) or one signed by a trusted root certificate within the organization.		By default enPortal is configured with SSL disabled, but it does ship with a self-signed server certificate and can easily be enabled. In production environments this certificate should be replaced with one issued by a known Certificate Authority (CA) or one signed by a trusted root certificate within the organization.
Line 18:		Line 21:
	{{Warning\|Do not configure SSL by editing the enPortal server.xml file as this is a system file and replaced on upgrade. The correct way is to edit the runtime options.}}		{{Warning\|Do not configure SSL by editing the enPortal server.xml file as this is a system file and replaced on upgrade. The correct way is to edit the runtime options.}}

	== ~~Creating a Certificate~~ ==		=== Process Overview ===

	The basic process is:		The basic process is:

	# ~~Pick~~ a Certificate Authority~~. This~~ may be in-house if the organization has a Standard Operating Environment with their own root certificate installed on all systems. Otherwise this would be a commercial CA such as VeriSign, Thawte, or Go Daddy.		# pick a Certificate Authority, this may be in-house if the organization has a Standard Operating Environment with their own root certificate installed on all systems. Otherwise this would be a commercial CA such as VeriSign, Thawte, or Go Daddy.
	# ~~Create~~ a Certificate Signing Request (CSR)		# create a Certificate Signing Request (CSR)
	# ~~Have~~ the CA sign the request		# have the CA sign the request
	# ~~Download~~ the signed certificate on the ~~enPortal server~~. Depending on the CA ~~there should~~ be ~~instructions and options~~ for the format of the signed certificate~~; ensure an appropriate format is downloaded for use~~ with Tomcat. ~~It's then~~ necessary to import ~~this~~ certificate into a keystore file, ~~replace~~ the ~~one shipped with~~ enPortal, and update the ~~keystore pass~~ and type ~~options~~.		# download the signed certificate from the CA. Depending on the CA a variety of formats may be on offer. Choose an appropriate format for Tomcat - which the CA may explicitly list as an option, otherwise choose PKCS#7 format. Other formats may require additional conversion steps before Tomcat can make use of it.
			# create a Java KeyStore (JKS) file for Tomcat and install on the enPortal server.

			Another option is to generate a self-signed certificate to replace the self-signed certificate Edge ships with enPortal. However, end-users will still be presented with certificate errors and warnings.

			=== Creating Certificate & Keystore ===

			For SSL Tomcat requires a Java KeyStore (JKS). The keystore needs to contain the private key, the signed certificate, and any intermediate certificates from the CA. To create and work with a keystore it is necessary to have Java installed and be able to run the <tt>keytool</tt> command.

			The recommended approach is to use <tt>keytool</tt> to create the private key and CSR and keystore all in one go, then have the CA sign, and then import the signed certificate using PKCS#7 format directly into the keystore. This process is well outlined in the VeriSign documentation below:

			# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&id=AR227 creating a CSR and submitting for signing] (using keytool and creating a keystore in the process).
			# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&actp=CROSSLINK&id=AR153 importing the signed certificate into a JKS keystore] (in PKCS#7 / .p7b format)
			# Then follow the instructions below on Installing the Keystore.

			However, if you already have an existing private key, signed certificate, and intermediate certificates in X.509 format then some conversion is required before importing into a JKS. This process will require <tt>openssl</tt>.

			# Convert the private key (''private.key''), signed certificate (''server_signed.crt''), and intermediate certificates (''ca.crt'') into PKCS#12 format:
			#: <tt>openssl pkcs12 -export -in ''server_signed.crt'' -inkey ''private.key'' -CAfile ''ca.crt'' -caname root -chain -out combined.p12 -name ''your-alias''</tt>
			#: You will be prompted to enter a password, make sure you set a password (do not leave blank). If you do not have any intermediate certificates then leave out the <tt>-CAfile</tt>, <tt>-caname</tt>, and <tt>-chain</tt> options.
			# Create a JKS from the <tt>combined.p12</tt> file generated above:
			#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype PCKS12 -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>
			#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).
			# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below on Installing the Keystore.

			=== Installing the Keystore ===

			Once a valid keystore has been created it can be installed on the enPortal server:

			# copy to the <tt>[INSTALL_HOME]/server/conf/ssl.crt/</tt> directory. By default files in this directory are automatically included in full archives.
			# Edit <tt>setenv-custom.sh\|.bat</tt> and update the <tt>KEYSTORE_FILE</tt>, <tt>KEYSTORE_PASS</tt>, and <tt>KEYSTORE_TYPE</tt> as required. If using the instructions above then the type should not need to be changed. Please note the keystore file path is relative to <tt>[INSTALL_HOME]/server/</tt>
			# As noted previously also make sure the <tt>HTTP_SSL</tt> option is set to <tt>true</tt>.
			# Restart the enPortal server.

	Another option is to generate a self-signed certificate to replace the self-signed certificate Edge ships with enPortal. However, to end-users they will still be presented with certificate errors and warnings.

	~~As an example, VeriSign have documented the process for Tomcat as follows:~~		== Redirecting HTTP traffic ==

	~~# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&id=AR227 creating a CSR and submitting~~ for ~~signing].~~		There are two recommended approaches for redirecting standard HTTP traffic to HTTPS:
	~~# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&actp=CROSSLINK&id=AR153 importing the signed certificate into a JKS keystore]. NOTE~~: ~~as mentioned previously do not edit server.xml directly. Use the runtime options as documented above.~~

	~~Additionally, a legacy enPortal's SSL certificate will need to be converted into Tomcat's certificate format~~ to ~~be used in enPortal 5. See~~ the ~~link below:~~		# Use an external tool to redirect the traffic such as a load balancer or a full featured HTTP server like [http://httpd.apache.org/ Apache]. For many this will be the preferred option as since no configuration changes to enPortal are necessary.
	# [http://~~www~~.~~brandonchecketts~~.~~com~~/~~archives/convert-and-openssl-apache-ssl-certificate-to-a-pkcs12-tomcat Convert an OpenSSL (~~Apache~~) SSL Certificate~~ to ~~a PKCS12 (Tomcat)]~~

			# Modify <tt>server/conf/server.xml</tt> and <tt>server/webapps/enportal/WEB-INF/web.xml</tt> to define an extra non-SSL connector that will redirect to the HTTPS port. This approach is [https://www.google.com/search?q=tomcat+web.xml+http+connector+forward+https&oq=tomcat+web.xml+http+connector+forward+https&aqs=chrome..69i57.12323j0j7&sourceid=chrome&es_sm=91&ie=UTF-8#q=tomcat+redirect+http+to+https&safe=active well documented by the Tomcat user community].

	~~<!--~~ == Additional Topics ==		== Additional Topics ==

	* [[appboard/2.5/admin/client_certificates\|Client Certificates / Client Authentication]] ~~-->~~		* [[appboard/2.5/admin/untrusted_ssl_ios\|Untrusted Certificates on iOS mobile devices]]
			* [[appboard/2.5/admin/client_certificates\|Client Certificates / Client Authentication]]

imported>Jason.nicholls: 1 revision

2014-07-10T05:08:56Z

1 revision

← Older revision	Revision as of 05:08, 10 July 2014
(No difference)

imported>Jason.nicholls: 1 revision

2013-12-19T15:17:44Z

1 revision

New page

[[Category:enPortal 5.5]]
{{DISPLAYTITLE:SSL Configuration}}
For security reasons it's recommended to run enPortal over SSL (Secure Socket Layer). This will ensure all communications between clients (browsers) and the enPortal server are encrypted.

By default enPortal is configured with SSL disabled, but it does ship with a self-signed server certificate and can easily be enabled. In production environments this certificate should be replaced with one issued by a known Certificate Authority (CA) or one signed by a trusted root certificate within the organization.

== Configuring enPortal for SSL ==

To enable HTTPS (HTTP over SSL) mode use the <tt>HTTP_SSL</tt> runtime option and set it to <tt>true</tt>. In addition you may want to also change:

* <tt>HTTP_PORT</tt>: HTTPS is typically served on port 443
* <tt>KEYSTORE_FILE</tt>: if using your own certificate
* <tt>KEYSTORE_PASS</tt>: if using your own certificate
* <tt>KEYSTORE_TYPE</tt>: if using your own certificate

See the [[enportal/5.5/admin/enPortal_installation/installation/runtime_options|Runtime Options]] page for more information on these settings and how to configure them. After making any changes then restart the enPortal service.

{{Warning|Do not configure SSL by editing the enPortal server.xml file as this is a system file and replaced on upgrade. The correct way is to edit the runtime options.}}

== Creating a Certificate ==

The basic process is:

# Pick a Certificate Authority. This may be in-house if the organization has a Standard Operating Environment with their own root certificate installed on all systems. Otherwise this would be a commercial CA such as VeriSign, Thawte, or Go Daddy.
# Create a Certificate Signing Request (CSR)
# Have the CA sign the request
# Download the signed certificate on the enPortal server. Depending on the CA there should be instructions and options for the format of the signed certificate; ensure an appropriate format is downloaded for use with Tomcat. It's then necessary to import this certificate into a keystore file, replace the one shipped with enPortal, and update the keystore pass and type options.

Another option is to generate a self-signed certificate to replace the self-signed certificate Edge ships with enPortal. However, to end-users they will still be presented with certificate errors and warnings.

As an example, VeriSign have documented the process for Tomcat as follows:

# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&id=AR227 creating a CSR and submitting for signing].
# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&actp=CROSSLINK&id=AR153 importing the signed certificate into a JKS keystore]. NOTE: as mentioned previously do not edit server.xml directly. Use the runtime options as documented above.

Additionally, a legacy enPortal's SSL certificate will need to be converted into Tomcat's certificate format to be used in enPortal 5. See the link below:
# [http://www.brandonchecketts.com/archives/convert-and-openssl-apache-ssl-certificate-to-a-pkcs12-tomcat Convert an OpenSSL (Apache) SSL Certificate to a PKCS12 (Tomcat)]