Sun N1 Service Provisioning System 5.1 Installation Guide

Previous: Chapter 5 Installing the N1 Service Provisioning System 5.1 on Windows Systems
Next: Chapter 7 Configuring the N1 Service Provisioning System 5.1 to Use Secure Shell

Chapter 6 Configuring the N1 Service Provisioning System 5.1 for HTTPS

The N1 Service Provisioning System installation program prompts you to select for the browser interface to use HTTP or HTTPS to connect to the Master Server. If you choose HTTPS, the installation program prompts you to enter the keystore file and keystore password. The installation program offers two options for providing the keystore file and the keystore password:

Create keystore file and keystore password before installation:If you create a keystore file and a keystore password before you install the provisioning system, then you can provide the keystore file and keystore password information during installation. For instructions on how to create a keystore file and a keystore password before you install the provisioning system, see Creating a Keystore File and Keystore Password for HTTPS Connections.

Note –
The installation program does not verify that the keystore password is valid. If you enter an invalid password, you might not be able to start the Master Server.
Create keystore file and keystore password after installation:If you do not create a keystore file and a keystore password before installation, you cannot provide the keystore file and keystore password information during the installation. Consequently, the installation script creates an empty keystore file in the N1SPS5.1-home/server/tomcat directory. You must manually replace the empty keystore file and keystore password information before you can start the Master Server. For instructions, see Configuring HTTPS After Installation.

If you select HTTP during installation, you can manually configure the Master Server to use HTTPS. For instructions, see Configuring HTTPS After Selecting HTTP During Installation.

If you have configured the provisioning system to use HTTPS, you can manually reconfigure the provisioning system to use HTTP. For instructions see Reverting to HTTP.

Creating a Keystore File and Keystore Password for HTTPS Connections

HTTPS requires an SSL Certificate. When you generate an SSL Certificate, you are creating a keystore file and a keystore password for use when the browser interface connects to the Master Server.

You can choose whether to have a Certifying Authority sign the certificate or you can use a self-signed certificate. A certificate signed by a Certifying Authority is trusted by browsers, therefore the browser does not issue a warning when a user connects to the browser interface on the Master Server. Generally, Certifying Authorities charge a fee to sign a certificate. A self-signed certificate is available for use immediately after you generate the certificate because you do not have to wait for the Certifying Authority to sign it. However, a self-signed certificate is not trusted by the browser, so the browser issues a warning each time a user connects to the Master Server.

How to Generate SSL Certificates

To enable the browser interface to use SSL, you must first generate an SSL Certificate. You create a keystore file and a keystore password while you generate an SSL Certificate.

Before You Begin

To create a keystore file and a keystore password you will use keytool. keytool is a security tool available with the JRE. If you do not have keytool installed, you must install keytool before you can configure the provisioning system to use HTTPS. The N1 Service Provisioning System installs the JRE. If you are configuring HTTPS after you have installed the provisioning system, keytool is installed on the system.

Steps

Change to the directory in which you installed the JRE.
% cd JAVA-HOME/bin
JAVA-HOME is the directory where you installed the JRE. If you installed the JRE with the N1 Service Provisioning System 5.1, the JRE is installed in the N1SPS5.1-home/common/jre/bin directory.

Generate the certificate.
% keytool -genkey -alias tomcat -keyalg RSA -keystore /keystore-location -storepass password
Set /keystore-location to the location and filename of the keystore file where you want to store the generated key.

Set password to whatever password that you want to use as the keystore password.

Follow the prompts to complete.

Do not include any punctuation in the name of your organization, otherwise the Java Certificate tool fails when attempting to generate the request. The Common Name (CN) must be set to the fully qualified host name, including the domain name, component of the URI.

How to Obtain a Signature for an SSL Certificate

If you want to use a Certificate signed by a Certifying Authority, follow this procedure to submit the Certificate to the Certifying Authority to be signed.

Steps

Generate the Certificate Request.
% keytool -certreq -v -alias tomcat -keyalg RSA -keystore /keystore-location
/keystore-location is the location and filename where you stored the generated key.

Send the Certificate Request to the Certifying Authority.

Follow the instructions provided by the Certifying Authority. The Certifying Authority returns a Certificate Reply.

Save the Certificate Reply to a file.

Verify the Certificate Reply.
% keytool -printcert -file certificate-reply-file
certificate-reply-file is the filename of the Certificate Reply that you received from the Certifying Authority.

Import the Certificate Reply file to the keystore file.
% keytool -v -import -trustcacerts -keystore /keystore-location -file certificate-reply-file -alias tomcat
/keystore-location is the location and filename where you stored the generated key. certificate-reply-file is the filename of the Certificate Reply that you received from the Certifying Authority.

Verify the imported Certificate Reply.
% keytool -v -list -keystore /keystore-location
/keystore-location is the location and filename where you stored the generated key.

Configuring HTTPS After Installation

The N1 Service Provisioning System installation program prompts you to choose to select HTTPS or HTTP for the browser interface to use to connect to the web interface of the Master Server. If you selected HTTPS during the installation, but you did not supply a keystore file and a keystore password during the installation you must manually copy the keystore file to the provisioning system keystore directory. You must also create an encoded keystore password and configure the password in the server.xml file.

How to Copy the Keystore File

Complete the following steps to copy the keystore file to the N1SPS5.1-MasterServer-home/server/tomcat/keystore file.

Before You Begin

Generate an SSL Certificate, and obtain a signature from a Certifying Authority if necessary. For instructions, see Creating a Keystore File and Keystore Password for HTTPS Connections.

Steps

Move the keystore file to the Master Server home directory.
%mv /keystore-location N1SPS5.1-MasterServer-home/server/tomcat/keystore
/keystore-location is the location and filename where you stored the generated key. N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

Change to the directory where you moved the keystore file.
% cd N1SPS5.1-MasterServer-home/server/tomcat/
N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

Set the ownership and permissions on the keystore file:
%chmod 600 keystore
%chown MS_user:MS_group keystore
MS_user is the user that owns the Master Server application. MS_group is the group that owns the Master Server application.

How to Create and Configure an Encoded Keystore Password

When you generate an SSL certificate, you create a keystore file and you supply a keystore password. The provisioning system must store the keystore password in the server.xml file. For added security, the provisioning system requires an encoded version of the password to store in the server.xml file.

Steps

Change to the directory on the Master Server that contains the crkeys command.
%cd N1SPS5.1-MasterServer-home/server/bin
N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

Create an encoded version of the password that you created when you created the keystore file.
% crkeys -epass -password password
password is the password that you created while generating the SSL certificate.

The crkeys tool prints the encoded password on the screen. Make note of the encoded password.

Change to the directory where the Tomcat configuration files are located.
% cd /N1SPS5.1-MasterServer-home/server/tomcat/conf
N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

Edit the Factory element to include the encoded password.

<Factory className="com.raplix.rolloutexpress.ui.web.EncodedPasswordSSLFactory"
           clientAuth="false" protocol="TLS" 
	keystoreFile="/opt/SUNWn1sps/N1_Service_Provisioning_System_5.1/server/tomcat/keystore"
 keystorePass="ADD_ENCODED_PASSWORD_HERE"/>

Change ADD_ENCODED_PASSWORD_HERE to the encoded version of the password.

Configuring HTTPS After Selecting HTTP During Installation

The N1 Service Provisioning System installation program prompts you to choose to select HTTPS or HTTP for the browser interface to use to connect to the Master Server. If you selected HTTP during the installation, you can manually reconfigure the N1 Service Provisioning System to use HTTPS.

How to Enable HTTPS Connections from the Master Server Browser Interface to the Web Interface of the Master Server

Complete the following steps to configure the browser interface to use HTTPS instead of HTTP to connect to the Master Server.

Before You Begin

Generate an SSL Certificate and obtain a signature from a Certifying Authority if necessary. For instructions, see Creating a Keystore File and Keystore Password for HTTPS Connections.

Steps

Stop the Master Server.
% N1SPS5.1-MasterServer-home/server/bin/cr_server stop
N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

Move the keystore file to the Master Server home directory.
%mv /keystore-location N1SPS5.1-MasterServer-home/server/tomcat/keystore
/keystore-location is the location and filename where you stored the generated key. N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

Change to the directory where you moved the keystore file.
% cd N1SPS5.1-MasterServer-home/server/tomcat/
N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

Set the ownership and permissions on the keystore file:
%chmod 600 keystore
%chown MS_user:MS_group keystore
MS_user is the user that owns the Master Server application. MS_group is the group that owns the Master Server application. /keystore-location is the filename where you stored the generated key.

Change to the directory where the Tomcat configuration files are located.
% cd /N1SPS5.1-MasterServer-home/server/tomcat/conf
N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

In the server.xml file, uncomment the following lines. XML comments begin with .

<Connector className="org.apache.catalina.connector.http.HttpConnector"
               port="8443" minProcessors="5" maxProcessors="75"
               enableLookups="true"
               acceptCount="10" debug="0" scheme="https" secure="true">
          <Factory className="com.raplix.rolloutexpress.ui.web.EncodedPasswordSSLFactory"
               clientAuth="false" protocol="TLS"/>
      </Connector>

Edit the Factory element as follows.

<Factory className="com.raplix.rolloutexpress.ui.web.EncodedPasswordSSLFactory"
           clientAuth="false" protocol="TLS" 
	keystoreFile="N1SPS5.1-MasterServer-home/server/tomcat/keystore"
 keystorePass="password"/>

N1SPS5.1-MasterServer-home is the directory in which you installed the Master Server. password is the encoded version of the password.

How to Require Users to Connect to the Master Server Browser Interface Using SSL

After you have configured the Master Server browser interface to use SSL, you can configure it further so that users must use SSL to connect to the browser interface on the N1 Service Provisioning System Master Server.

Steps

Replace the Tomcat web.xml file with the secure web.xml file.
% cd /N1SPS5.1-MasterServer-home/server/webapp/WEB-INF
% cp web.xml.secure web.xml
N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

Restart the Master Server.
% N1SPS5.1-MasterServer-home/server/bin/cr_server start
N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

Reverting to HTTP

If you have configured the provisioning system to use HTTPS, you can manually reconfigure the provisioning system to use HTTP.

How to Revert to HTTP

Steps

Stop the Master Server
% N1SPS5.1-MasterServer-home/server/bin/cr_server stop
N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

To return to the original configuration, replace the secure web.xml file with the default web.xml file.
% cd /N1SPS5.1-MasterServer-home/server/webapp/WEB-INF
% cp web.xml.default web.xml
N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.

Restart the Master Server.
% N1SPS5.1-MasterServer-home/server/bin/cr_server start
N1SPS5.1-MasterServer-home is the directory where you installed the Master Server.