This article describes how to manually setup a Definition Center to run SSL / TLS (Transport Layer Security - HTTPS).

1. Generate the Keystore, create an Alias and Key Pair

  1. Stop the Definition Center service if it is running.
  2. Open a command prompt and navigate to the following directory: \iRise\DefCenter\jvm64\jre\bin 
  3. Type the following command, entering whatever name you like for the alias (make note of the name you use for the alias as you will use this later). Please note that you will need to use lower case to create the alias, and also later on when you add it to the server.xml file.:
     
    keytool -genkeypair -alias <alias> -keyalg RSA -sigalg SHA256withRSA -keypass <key password> -keystore <\iRise\DefCenter\Tomcat\conf\keystore.jks> -storepass <keystore password> -validity <number of days key is valid> -keysize 2048
  4. Enter the following information when prompted:
     
    First and last name - the Keytool program is looking for the common name here. The common name is the fully-qualified domain name (FQDN), Host name or URL - to which you plan to apply your certificate. Do not enter your personal name in this field. NOTE: If you are requesting a Wildcard certificate, please add an asterisk on the left side of the Common Name (e.g., "*.coolexample.com" or "*www.coolexample.com"). This will secure all subdomains of the Common Name.

    Organizational Unit - Use this field to differentiate between divisions within your organization. For example, "Engineering" or "Human Resources." If applicable, you may enter the DBA (doing business as) name in this field.

    Organization
    - The name under which your business is legally registered. The listed organization must be the legal registrant of the domain name in the certificate request. If you are enrolling as an individual, please enter the certificate requestor's name in the Organization field, and the DBA (doing business as) name in the Organizational Unit field

    City/locality
    - Name of the city in which your organization is registered/located. Please spell out the name of the city. Do not abbreviate.

    State/province
    - Name of state or province where your organization is located. Please enter the full name. Do not abbreviate.

    Country code
    - The two-letter International Organization for Standardization- (ISO-) format country code for the country in which your organization is legally registered.

    Keytool will present you with a Distinguished Name (DN), which includes the FQDN, hostname or URL you entered. Please confirm the DN information is correct.

2. Modify the server.xml file

  1. Make a copy of the \iRise\DefCenter\Tomcat\conf\server.xml  file
  2. Edit the server.xml file with a text editor.
  3. Comment out the existing connector by adding <!--  and -->  tags on either side of the connector. Make sure you comment out the entire connector. Look for the closing tag for the connector and make sure your ..> tag is after that tag. To find the connector look for this line in the file:
     
    <!-- Define a non-SSL HTTP/1.1 Connector on port determined by iRise installer user entry -->
     
     The connector is the block of code that follows that.
  4. Uncomment out the SSL connector by removing the <!--  and -->  tags around it. Again, make sure you uncomment out the entire connector. To find the SSL connector look for this line in the file:
     
    <!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
  5. Replace the SSL connector attributes to match below accordingly:
URIEncoding="UTF-8"
address="<IP address Tomcat will listen on>" *see note below
port="443"
maxThreads="200"
minSpareThreads="25"
enableLookups="false"
disableUploadTimeout="true"
acceptCount="200"
scheme="https"
secure="true"
clientAuth="false"
sslProtocol="TLS"
SSLEnabled="true"
keystoreFile="<path to your keystore file>"
keystorePass="<password to your keystore>"
keyPass="<password to private key>"
keyAlias="<alias to your key created above>"
connectionTimeout="60000"
compression="on"
noCompressionUserAgents="gozilla, traviata"
compressableMimeType="text/html,text/xml, text/css, text/javascript, application/x-javascript, application/javascript, binary/xml"
protocol="org.apache.coyote.http11.Http11NioProtocol"
ciphers="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA"
 

* address attribute: For servers with more than one IP address, this attribute specifies which address will be used for listening on the specified port. By default, this port will be used on all IP addresses associated with the server.​

3. Modify the irise.properties file

  1. Make a copy of the \iRise\DefCenter\Tomcat\conf\irise.properties  file.
  2. Edit the irise.properties file with a text editor.
  3. Search for the line: irise.server.protocol and change the value from http to https
  4. Search for the line: irise.server.port and change it to whatever you set the port to be in the SSL connector in the server.xml file. If you are using the default SSL port, enter 443 here

4. Test your settings and your self-signed certificate

  1. Start the iRise Definition Center service, then open a browser on the DC server and try to login to https://servername. If you used a port other than 443 type https://servername:<port> replacing <port> with the port number you used
  2. Attempt to login to the Definition Center and navigate around. You will get a security warning in your browser indicating that the certificate for the server is not signed from a trusted authority. This is expected, as the certificate is self-signed at this point. If you do not intend on having a certificate authority (CA) sign your certificate, you can export your certificate from the keystore and import it into your system's trusted store. If you require a trusted CA to sign your certificate, skip the below steps and continue to step 5 to create a certificate signing request (CSR). Otherwise run this command to export your certificate:

    keytool -export -keystore <path to keystore file> -alias <alias> -file <certificate name>.cer
     
    Windows: import self-signed certificate into Windows client:
     
    certutil -addstore "TrustedPublisher" <certificate name>.cer
    certutil -addstore root <certificate name>.cer
     
    Import self-signed certificate into Mac client:
     
    sudo /usr/bin/security add-trusted-cert -d -r trustRoot -k "<certificate name>.cer"
     
    Run these commands to import self-signed certificate into Windows client:
     
    certutil -addstore "TrustedPublisher" <certificate name>.cer
    certutil -addstore root <certificate name>.cer
     
    Import self-signed certificate into Mac client:
     
    sudo /usr/bin/security add-trusted-cert -d -r trustRoot -k "<certificate name>.cer" 

5. ​Generate a Certificate Signing Request (CSR) and Obtain a Certificate

Open a command prompt and navigate to the following directory:
\iRise\DefCenter\jvm64\jre\bin .
 
Generate the CSR using the following command:
 
keytool -certreq -alias <alias> -sigalg SHA256withRSA -file <filename.csr> -keypass <key password> -storetype jks -keystore <path to keystore.jks> -storepass <keystore password>
 
You should now have a CSR in the directory specified in the above command. Open the file with a text editor and cut and paste the contents into your certificate authority’s enrollment form and follow the instructions to generate your certificate.

6. Install and Test your leaf entity Certificate

If given a choice, choose a P7B type certificate, as it contains the full chain, including the root and intermediate certificates. Open a command prompt and navigate to the following directory:

\iRise\DefCenter\jvm64\jre\bin  
 
Import the signed certificate into the keystore with the following command. If you have separate certificates for the root and intermediate (rather than a P7B full chain), you'll need to import them individually (using the same command below) before importing your leaf entity certificate.
 
keytool -import -file <signed certificate> -alias <alias> -trustcacerts -keystore <path to keystore> -storepass <keystore password>
 
If you used a certificate from a trusted root authority (Verisign, Thawte, etc.) you don't need to do anything more. Start the iRise Definition Center service and go to https://<servername> (or https://<servername>:<port> if not using port 443) in a browser to test the configuration. Also use a Studio client to connect to the DC to make sure connections work there as well.
 
Non-trusted Certificate Authority - additional steps
 
If you used a certificate from a non-trusted or internal Certificate Authority (CA), there are some additional steps you need to take.
 
If there are intermediate certificate signing servers between the root authority and your certificate, you need to import the root certificates for those intermediate signing servers to the \iRise\DefCenter\Tomcat\conf\keystore.jks file. You can do this using the keytool program.
 
Example commands for importing root/intermediate certificates into the keystore.jks file:
 
keytool -import -trustcacerts -alias <mycompanyroot> -file <root.cer> -keystore \iRise\DefCenter\Tomcat\conf\keystore.jks
 
keytool -import -trustcacerts -alias <mycompanyintermediate> -file <intermediate.cer> -keystore \iRise\DefCenter\Tomcat\conf\keystore.jks
 
You need to import that certificate authority's root & intermediate (if using) certificate(s) into the \iRise\DefCenter\jvm64\jre\lib\security\cacerts  file.
 
Example commands for importing root/intermediate certificates into the cacerts file:
 
keytool -import -trustcacerts -file <rootcert.cer> -alias <mycompanyroot> -keystore \iRise\DefCenter\jvm64\jre\lib\security\cacerts
 
keytool -import -trustcacerts -file <intermediate.cer> -alias <mycompanyintermediate> -keystore \iRise\DefCenter\jvm64\jre\lib\security\cacerts
 
Non-trusted Certificate Authority - additional steps for Studio Clients
 
Finally, for any Studio client that will be accessing this Definition Center you need to import these same root and intermediate certificates into the C:\Program Files (x86)\iRise\Studio\_jvm\lib\security\cacerts  file. Here is a sample command to do that for the rootcert.cer:
 
Windows:
keytool -import -trustcacerts -file rootcert.cer -alias <mycompanyroot> -keystore C:\Program Files (x86)\iRise\Studio\_jvm\lib\security\cacerts
 
Mac:
keytool -import -trustcacerts -file rootcert.cer -alias <mycompanyroot> -keystore /Contents/Plugins/jre.jdk/Contents/Home/jre/lib/security/cacerts 

You can use the free Keystore Explorer tool (available for Windows and Mac) to create and read keystore files and examine and import certificates. Further details can be found on their website: http://keystore-explorer.sourceforge.net.

Did this answer your question?