This article covers a Bloomreach Experience Manager version 13. There's anupdated version available that covers our most recent release.

Configure Cargo for SSL/TLS

Introduction

Goal

Configure your local Cargo-based development environment to use SSL/TLS.

Background

A standardimplementation project created using the Bloomreach Experience Manager Maven archetype is configured to run in alocal Cargo-based development environment. By default, the Tomcat container in this environment is configured to use an unencrypted HTTP connection, which is sufficient for most local development use cases. This page explains how you can configure Cargo to use an encrypted HTTPS connection instead, in case you need to develop or test an SSL/TLS setup locally.

Instructions

Prepare Keystore, Certificate, and Truststore

From within your project's root directory, change to theconf directory:

cd conf

Use theJavakeytool command to create a keystore inside theconf directory:

keytool -keystore tomcatkeystore -genkey -alias 127.0.0.1 -keyalg RSA

When answering the questions asked by keytool, make sure to use the name (CN) "127.0.0.1":

Enter keystore password:Re-enter new password:What is your first and last name?  [Unknown]:  127.0.0.1What is the name of your organizational unit?  [Unknown]:  InfraWhat is the name of your organization?  [Unknown]:  BloomreachWhat is the name of your City or Locality?  [Unknown]:  Mountain ViewWhat is the name of your State or Province?  [Unknown]:  CAWhat is the two-letter country code for this unit?  [Unknown]:  USIs CN=127.0.0.1, OU=Infra, O=Hippo, L=Boston, ST=MA, C=US correct?  [no]:  yesEnter key password for <127.0.0.1>        (RETURN if same as keystore password):Re-enter new password:

There should now be a file called tomcatkeystore in your project'sconf directory.

Next, use keytool to export a certificate from the keystore:

keytool -keystore tomcatkeystore -exportcert -alias 127.0.0.1 -file tomcat.cert

Finally, use keytool to create a truststore and import the certificate into it: 

keytool -import -file tomcat.cert -alias 127.0.0.1 -keystore tomcattruststore

When asked to trust the certificate, answer 'yes':

Trust this certificate? [no]:  yes

There should now be a file called tomcattruststore in your project'sconf directory.

Configure Cargo Plugin

In your project's rootpom.xml, find thecargo.run profile.

Inside thecargo.run profile, find the cargo-maven2-plugin plugin configuration properties.

Add the following plugin configuration properties toplugin/configuration/configuration/properties:

<cargo.servlet.port>8443</cargo.servlet.port><cargo.protocol>https</cargo.protocol><cargo.tomcat.connector.clientAuth>false</cargo.tomcat.connector.clientAuth><cargo.tomcat.connector.sslProtocol>TLS</cargo.tomcat.connector.sslProtocol><cargo.tomcat.connector.keystoreFile>${project.basedir}/conf/tomcatkeystore</cargo.tomcat.connector.keystoreFile><cargo.tomcat.connector.keystorePass>changeit</cargo.tomcat.connector.keystorePass><cargo.tomcat.connector.keyAlias>127.0.0.1</cargo.tomcat.connector.keyAlias><cargo.tomcat.httpSecure>true</cargo.tomcat.httpSecure>

Still inside thecargo.run profile, add the following system properties toplugin/configuration/container/systemProperties:

<javax.net.ssl.trustStore>${project.basedir}/conf/tomcattruststore</javax.net.ssl.trustStore><javax.net.ssl.trustStorePassword>changeit</javax.net.ssl.trustStorePassword>

Build your project.

Configure the HST

Run your project.

Point your web browser to the console at:

https://127.0.0.1:8443/cms/console/

Login as admin and browse to the node /hst:platform/hst:hosts.

Set the propertyhst:scheme tohttps:

/hst:platform/hst:hosts  - hst:scheme = https

Browse to the node /hst:platform/hst:hosts/dev-localhost.

Set the hst:defaultport property to port 8443:

/hst:platform/hst:hosts/dev-localhost  - hst:defaultport = 8443

Repeat the previous two steps for the site host configuration at/hst:myproject/hst:hosts/.

Set the propertyhst:scheme tohttps:

/hst:myproject/hst:hosts  - hst:scheme = https

Set the hst:defaultport property to port 8443:

/hst:myproject/hst:hosts/dev-localhost  - hst:defaultport = 8443

Write your changes to the repository.

Point your browser to the CMS at:

https://localhost:8443/cms/

Verify that the channel manager is working.