Configure CSA to Use a Self-Signed Certificate

This section describes the process you should follow to obtain, install, and configure a self-signed certificate for use by CSA.

In general, it is recommended that you replace CSA's self-signed certificate with a Certificate Authority-signed certificate. However, you may consider replacing CSA's self-signed with a self-signed certificate you create in the following situations:

• CSA's self-signed certificate has expired and you do not want to configure a Certificate Authority-signed certificate at this time.
• The hostname that you entered when you installed CSA has changed (the hostname you entered during installation is used to configure CSA's self-signed certificate).
• You entered an IP address instead of the fully-qualified domain name when CSA was installed.
• Obtaining a Certificate Authority-signed certificate is not an option in your environment.

You should perform the following general steps:

1. Create a keystore and a self-signed certificate.
2. Export the self-signed certificate.
3. Import the self-signed certificate as a trusted certificate.
4. Configure the Marketplace Portal.
5. Configure the web server.
6. Configure client browsers (optional).
7. Test the secure connection.

Step 1: Create a Keystore and Self-Signed Certificate

To create a self-signed certificate, complete the following steps:

1. Open a command prompt and change directories to CSA_HOME.

2. Run the following command:

   Windows:

   "CSA_JRE_HOME\bin\keytool" -genkeypair -alias csa_self_signed
-validity 365 -keyalg rsa -keysize 2048
-keystore .\jboss‑as\standalone\configuration\
.keystore_self_signed [-ext san=ip:<ip_address>]

   Linux:

   CSA_JRE_HOME/bin/keytool -genkeypair -alias csa_self_signed
-validity 365 -keyalg rsa -keysize 2048
-keystore ./jboss‑as/standalone/configuration/
.keystore_self_signed [-ext san=ip:<ip_address>]

   where CSA_JRE_HOME is the directory in which the JRE that is used by CSA is installed and ‑ext san=ip:<ip_address> is the option to specify the IP address of the system on which CSA is installed. This option is required if you specified an IP address instead of the fully-qualified domain name when you installed CSA. If you specified the fully-qualified domain name during installation, you may omit this option.

   You can use different values for -alias, -validity, -keysize and -keystore. These instructions assume that you will use the -alias and -keystore values recommended here; you will have to adjust the commands accordingly if you use different values.

3. Enter a keystore password.

   This password is used to control access to the keystore. This password must be the same as the password you enter for the key later in this procedure.

4. When you are prompted for your first and last name, enter the fully qualified domain name of the CSA server.

5. Follow the prompts to enter the remaining organization and location values.

6. Enter the keystore password you supplied earlier to use as the key password.

   Although keytool allows you to enter different passwords for the keystore and the key, the two passwords must be the same to work with CSA.

Step 2: Export the Self-Signed Certificate

Export the self-signed certificate using the following procedure:

1. Open a command prompt and change directories to CSA_HOME.

2. Run the following command:

   Windows:

   "CSA_JRE_HOME\bin\keytool" -export -alias csa_self_signed
-file C:\csa_self_signed.cer
-keystore .\jboss‑as\standalone\configuration\
.keystore_self_signed

   Linux:

   CSA_JRE_HOME/bin/keytool -export -alias csa_self_signed
-file /tmp/csa_self_signed.cer
-keystore ./jboss‑as/standalone/configuration/
.keystore_self_signed

   where CSA_JRE_HOME is the directory in which the JRE that is used by CSA is installed.

   NOTE: Please do not anytime delete the default jboss.cer certificate from the folder CSA_HOME\jboss-as\standalone\configuration\

3. When you are prompted for a password, enter the keystore password used in step 1.

Step 3: Import the Self-Signed Certificate as a Trusted Certificate

This step configures the JRE so it trusts the self-signed certificate.

1. Open a command prompt.

2. Run the following command:

   Windows:

   "CSA_JRE_HOME\bin\keytool" -importcert -alias csa_self_signed
-file C:\csa_self_signed.cer -trustcacerts
-keystore "CSA_JRE_HOME\lib\security\cacerts"

   Linux:

   CSA_JRE_HOME/bin/keytool -importcert -alias csa_self_signed
-file /tmp/csa_self_signed.cer -trustcacerts
-keystore CSA_JRE_HOME/lib/security/cacerts

   where CSA_JRE_HOME is the directory in which the JRE that is used by CSA is installed.

3. When prompted for the keystore password, enter changeit.

4. Enter yes when prompted to trust the certificate.

Step 4: Configure the Marketplace Portal

This step converts the CSA keystore to a PKCS#12 archive and configures the Marketplace Portal to use the self-signed certificate.

1. Open a command prompt and navigate to CSA_HOME.

2. Convert the CSA keystore to a PKCS#12 archive. Run the following command:

   Windows:

   "CSA_JRE_HOME\bin\keytool" -importkeystore -srckeystore .\jboss‑as\standalone\configuration\.keystore_self_signed -deststoretype PKCS12 -destkeystore .\portal\conf\.mppkeystore_self_signed

   Linux:

   CSA_JRE_HOME/bin/keytool -importkeystore -srckeystore ./jboss‑as/standalone/configuration/.keystore_self_signed -deststoretype PKCS12 -destkeystore ./portal/conf/.mppkeystore_self_signed

3. When prompted, enter the password for the PKCS#12 archive. You will need this password when you configure the passphrase attribute later in this section.

4. When prompted, enter the password for the CSA keystore (changeit).

5. Open the CSA_HOME/portal/conf/mpp.json file in a text editor.

6. Update the ca attribute value for the provider. Enter the path to the certificate file that you imported in step 2. For example, C:/csa_self_signed.cer on Windows or /tmp/csa_self_signed.cer on Linux.

7. Update the ca attribute value for the idmProvider. Enter the path to the certificate file that you imported in step 2. For example, C:/csa_self_signed.cer on Windows or /tmp/csa_self_signed.cer on Linux.

8. Update the pfx attribute value. Enter the name of the PKS#12 archive you created earlier. For example, ../conf/.mppkeystore_self_signed.

9. Update the passphrase attribute value. Enter the encrypted password used to access the .mppkeystore_self_signed archive (see Encrypt a Marketplace Portal Password for instructions). An encrypted password is preceded by ENC without any separating spaces and is enclosed in parentheses.

10. Save and exit the file.

Step 5: Configure the Web Server

1. Open CSA_HOME\jboss‑as\standalone\configuration\standalone.xml in a text editor.

2. Locate the following entry:

   <keystore keystore-password="changeit" path="CSA_HOME\jboss‑as\standalone\configuration\.keystore"/>

3. Set the path attribute to the keystore you used in step 2, set the keystore‑password attribute to the value that corresponds to the password you selected for the keystore, and add the key-alias attribute and set it to the alias you used in step 2.

   <keystore path="CSA_HOME\jboss-as\standalone\configuration\.keystore_self_signed" keystore-password="keystorePassword" alias="csa_self_signed"/>

   Note This example stores the password in clear text. If you want to use an encrypted password, see Masking Passwords in standalone.xml Using the JBoss vault Script for information about creating a password vault for JBoss.

4. Restart the CSA service. See Restart CSA for instructions.

5. After the service has started, review the log files in the
   CSA_HOME/jboss‑as/standalone/log/ directory and verify that no TLS or keystore errors are present.

Step 6: Configure Client Browsers (Optional)

Because the self-signed certificate is not signed by a Certificate Authority, when accessing the Cloud Service Management Console, warning messages are displayed in the browser (these messages do not affect normal operations of CSA). To avoid these warning messages, import the csa_self_signed.cer file or add an exception.

• Microsoft Internet Explorer and Chrome: From Windows Explorer, double-click on the
  csa_self_signed.cer file to begin the import process. Install the certificate in the Trusted Root Certification Authorities store. For information about how to import the certificate, refer to the browser's online documentation.
• Firefox: Add an exception by opening the browser and navigating to https://<csahostname>:8444/csa where <csahostname> is the fully-qualified domain name of the system on which CSA is running. When the This Connection is Untrusted page opens, select I Understand the Risks, click the Add Exception button, verify the Server Location, and click Confirm Security Exception. For information about how to import the certificate, refer to the browser's online documentation.

Step 7: Test Secure Connections

To test the connection to the Cloud Service Management Console, on a client system, open a supported Web browser and navigate to https://<csahostname>:8444/csa where <csahostname> is the fully-qualified domain name of the system that was used when the certificate was created. If the client browser is configured to accept the self-signed certificate (that is, you have completed step 6) and the Web application opens without a certificate warning, then you have successfully configured CSA to use a self-signed certificate. If you did not complete step 6, verify that the only certificate warning relates to the certificate not being issued by a trusted authority. If any other certificate warning is displayed, review steps 1-6 to be sure they were followed as documented.