RapidIdentity Product Guide

SSL Management
SSL Management

An SSL certificate, also known as a public key certificate, is an electronic document that verifies one's ownership of a public key. When site owners install SSL certificates onto their web servers, all web traffic between their servers and users' browsers gets encrypted, ensuring the confidentiality of the information exchanged. The certificate file must be encoded and formatted based on the type that your server requires.

RapidIdentity releases include a revision to SSL certificate management and stores the KeyStore in a database. Once a KeyStore is configured it can be attached to an SSL Profile. A single SSL Profile can be used by multiple RapidIdentity instances but can only support a single SSL certificate chain.

SSL Management Steps

There are various actions that may be performed using RapidIdentity to manage SSL Profiles.

Frequently Used Terminology
  • SSL (Secure Sockets Layer): Protocols for establishing authenticated and encrypted links between networked computers. (The actual method being used for certification is TLS, but the certificate management is still referred to as SSL management.)

  • Public Key: A large numerical value that is used to encrypt data

  • Certificate Encoding Formats:

    • CSR (Certificate Signing Request): A block of encoded text that contains information about the organization to submit to a Certification Authority for an SSL certificate

      PEM (Privacy Enhanced Mail): A Base64 encoded DER certificate often used for web servers

    • DER (Distinguished Encoding Rules): Contains a single digital certificate that does not store private keys

    • CER/CRT: Contains a single digital certificate that does not store private keys

Create an SSL Profile

There is no limit to the number of SSL Profiles that can be created.

Note

A new SSL profile will contain a new, self-signed certificate by default.

Follow these steps to create a new SSL Profile.

  1. From the Configuration module, select SSL Management from the Security section.

    SSL_Mgmt.png
  2. From the SSL Profiles workspace, click Add Profile+.

    add_profile.png
  3. Enter a Name and an optional Description.

    ssl_profile_details_wildcard.png
    1. If using a domain name, Insert an asterisk in from of the domain name to create a wildcard name.

  4. Click Save.

  5. The newly created SSL Profile will be available in the SSL Profiles workspace for further configuration.

SSL Profile Details

All RapidIdentity instances have a self-signed certificate in the initial configuration and all new SSL Profiles that are created initially begin with a self-signed certificate.  

After the profile has been setup in the intial configuration, the self-signed certificate details are created and available in SSL Profile Details.

  1. From the Configuration menu, select SSL Certificates from the Security menu.

    SSL_Mgmt.png
  2. Select the SSL Profile from the workspace and hover over the far right-hand column to display the Details button.

    SSL_profile_details2.png
  3. Click Details to view the SSL Profile Details.

SSL_Profile_Details_Screen.png
SSL Profile Copy

An SSL Profile can be duplicated by following the below steps.

  1. From the Configuration menu, select SSL Certificates from the Security menu.

    SSL_Mgmt.png
  2. Click the checkbox to select the SSL Profile to copy and click Copy from the bottom action buttons.

    copy.png
    1. If the Copy was successful, a message will briefly display, otherwise, an error message will display.

  3. The copied profile will be displayed in the SSL Profiles workspace. By default, the new profile name will be followed by "-copy." Open the profile Details to change the name.

    copy_rename.png
  4. Save the changes.

SSL Profile Backup

Prior to attempting to configure or manage existing SSL Profiles, it is advisable to backup all existing SSL Profiles.

Follow these steps to back up SSL Profiles.

  1. Click the checkbox to select the SSL Profile to backup and click Export Certificate from the bottom action buttons.

    export_cert.png
  2. The Export Certificate window will launch.  

    export_certificate.png
    1. Select either JKS or PKCS12/PFX for the export File Type.

    2. Enter a Passphrase and an Alias.

    3. Click Export.

  3. A brief confirmation will display at the top of the screen.

  4. The file will be downloaded to the default location for your system. Save the file in a secure location.

The steps to import a new certificate can vary from site to site, depending on how the certificate is received and what type of certificate is imported. Java and Windows key stores (.JKS and .PFX files) can be directly imported. If you do not have the correct file type, follow the steps below for the certificate file generation.

  1. Navigate to Configuration > Security > SSL Management and select an SSL Profile for the key or certification upload.

    Add_Profile_New_UI.png
  2. In the SSL Profile Details pop-up, enter a fully qualified domain name to be secured with an SSL certificate. Optionally, generate a CSR code for a wildcard certificate by adding an asterisk in front of the domain (for instance, *.yourdomain.com).

    ssl_profile_details_wildcard.png
  3. The new SSL Profile will be visible in the workspace. Select the new profile and click Generate Certificate in the action bar.

    generate_csr.png
  4. Fill out the Generate Certificate form and click Generate Certificate. Refer to the below table for guidance on completing the online form.

    Generate_CSR_Menu.jpg
    Table 85. Certificate Signing Request Fields

    Field

    Description

    Host Name

    Required field. Fully-qualified domain name of the host server or the *.hostname for wildcard certs

    Note

    Secure with a certificate such as www.google.com, secure.website.org, *.domain.net, etc.

    Org Unit

    Division or department of the organization that applies for an SSL certificate (e.g., Information Technology, Website Security)

    Organization

    The full legal name of your organization, including the corporate identifier

    City/Locality

    The locality or city where your organization is legally incorporated. Do not abbreviate.

    State/Province

    The state or province where your organization is legally incorporated. Do not abbreviate.

    Country Code

    The official two-letter country code (i.e., US, CH) where your organization is legally incorporated



  5. The selected file type (CSR or JKS) will be generated and downloaded to your system.

    1. Provide the downloaded CSR to your Certificate Authority to get a new certificate.

Import Certificate

RapidIdentity allows administrators to import their own certificates to an existing SSL Profile. During the process, download individual .CRTor .PEM files for the certificate, any intermediate certificates, and the root certificate.

The Import menu allows you to upload the private key and certificate from an external certificate authority. Enter the data as described in the below sections.

  1. From the Configuration menu, select SSL Certificates from the Security menu.

    SSL_Mgmt.png
  2. Select an SSL Profile from the workspace for the private key or certificate import and click Import.

    import.png
  3. The Import Certificate window will display.

  4. Select the File Type method for the certification import. Refer to the respective sections below for details on completing the online form.

    1. Import Private Keys and Certificates

    2. Import KeyStore

    3. Import From Profile

Browser Notes

Depending on the Internet browser of choice and its configuration, the browser developer tools may display warnings or errors. In the context of the SSL Profile, if the browser verifies a "Secure Connection" and the certificate chain as "Valid Certificate", then the import and SSL Profile are valid when creating or importing an SSL Profile.

Important

An SSL Profile can be tested to ensure that it is working properly. This action is important to use after adding a private key and one or more certificates to an SSL Profile. Refer to the following section to test certificate import.

Test Certificate Import

After importing any of the certificate types, follow the below steps to validate the certificate import and to activate the import. The testing function is especially helpful when importing a key store or certificates from a third party Cerificate Authority into a copy of the existing default profile to verify operability and compatiblity with the browser to identify any issues that could be problematic to an existing SSL Profile.

Important

The Test functionality attempts to open a new tab pointing to the server at a different TCP port that is temporarily set up to use the SSL certificate chain being tested. In order to be able to test, you will need to connect to the RapidIdentity server on the temporary TCP port. The may require firewall rules to be adjusted.

  1. After enabling pop-ups, select the SSL Proflie from the workspace and click Test to validate the imported certificates.

    test.png
  2. Specify the port, and click Continue. The default port is 8444.

    test_certificate.png
  3. Click Test.

  4. If the Profile has been validated successful, a confirmation message will display, otherwise, an error will display.

    validation_or_error_from_test.png
  5. If the updates have been validated successfully, click Send Cluster Reload to activate the new certificate. It may be necessary to completely close and relaunch the browser session to recognize the new SSL certificate.

Send_Cluster_Reload_New_UI.png
Import Private Keys and Certificates

Note

If you do not have access to a private key at this stage, contact Identity Automation Support.

  1. From the Import Certificate window, select Import Key and Certs from the File Type drop-down.

  2. Enter the data, as described in the below table, and click Import. (Required fields are depicted with an asterisk).

    import_key_and_certs.png
  3. Once the certificate is valid, click the Import button on the live profile and import.

  4. Test and Send a Cluster Reload.

Import Key Store

The Import KeyStore menu allows you to import a JKS keystore file or PFX/PKCS12 file from a RapidIdentity export or from a Certficate Authority (CA).

Note

If you do not have a JKS or a PFX file, refer to the topic on SSL Certificates to generate the certificate.

  1. From the Import Certifcate window, select Import KeyStore from the File Type drop-down.

  2. Refer to the below table on completing the remaining fields for importing a keystore. Click Import when the form is complete.

keystore.png
Table 86. Import KeyStore Fields

Field

Description

File Type

This is the main drop-down box. Choose Import Keystore to activate the fields described below.

KeyStore

Click Choose File... to select the KeyStore file.

File Type

Choose the appropriate file type: JKS or PKCS12/PFX

Passphrase

Enter the passphrase used when the KeyStore was created.

Alias

Enter the alias used when the KeyStore was created.



Import from Profile

The Import from Profile menu allows you to import settings into a profile from existing SSL Profiles to essentially create a duplicate profile. Importing from Profile is extremely helpful to test validity of importing a key store or certificates from a third party Cerificate Authority into a copy of the existing default profile. This will allow the verification of operability and compatiblity with the browser to identify issues that could be problematic to the default SSL Profile.

After the imports have been validated on the "test" profile, repeat the import on the default SSL Profile.

  1. From the Import Certifcate window, select Import Profile from the File Type drop-down.

  2. Select the respective profile from the drop-down list and click Import.

    import_from_profile2.png
  3. Test and Send a Cluster Reload.

Caution

Clicking Import in this step overwrites any existing certificates attached to an SSL Profile. Always back up existing certificates and KeyStores before choosing to Import From Profile.

Updating rapididentity.properties

If a newly configured SSL Profile is desired in place of the default profile, it is necessary to update RapidIdentity's runtime properties.

Follow these steps to update the settings:

  1. Access RapidIdentity.properties.

  2. Scroll to locate tomcat.sslProfile=default.

    Tomcat.png
  3. Replace "default" with either the SSL Profile name or the SSL Profile ID (unique ID) as shown in the SSL Profile Details window.

    SSL_Profile_ID.png

    Important

    Ensure the line is uncommented by removing any leading "#" characters from the line.

  4. Save the properties file.

  5. Restart RapidIdentity from either the CLI or by clicking the the blue curved arrow in the Appliance | Server Management | Cluster tab.

    1. To restart from the CLI, navigate to the Main Menu | RapidIdentity | Status | Restart

      Restart_RI.png
File Access

This configuration file can be accessed from either of two paths:

  1. SSH into RapidIdentity and log in as the Config user.

  2. From the Main Menu, navigate to RapidIdentity | Advanced | Edit rapididentity.properties.

The rapididentity.properties file displays as follows.

RapidIdentity_Properties.png
RapidIdentity Upgrade Dependencies

An upgrade from RapidIdentity 4.3 to a Rolling or LTS Release should import an existing Keystore and Certificate configuration. If an existing KeyStore in RapidIdentity 4.3 is not imported successfully, the default KeyStore will be configured. Thus, a different KeyStore would need to be imported manually, as described in the Import KeyStore section. Prior to upgrading, if the environment is operating on a version prior to RapidIdentity 4.3, upgrade to RapidIdentity 4.3 first and then upgrade to the desired Rolling or LTS Release version.

Modify rapididentity.properties

The default configuration of the rapididentity.properties file is to have all settings commented with the pound-sign, except for the db.type property.

Follow these steps to modify the rapididentity.properties file:

  1. To enable a property, delete the pound-sign and space before the property and then update the property value.

  2. Type Ctrl-x to exit the file.

  3. Click Y to save the modified buffer (i.e. the file).

  4. Click Enter (Return) on the keyboard.

rapididentity.properties

rapididentity.properties is a configuration file that allows administrators to enable, disable, and configure various settings that affect how a particular instance of RapidIdentity operates. Most configuration for RapidIdentity is stored in the configuration database, but some settings (including how to connect to the configuration database) must be configured in this file.

Upon upgrade from RapidIdentity 4.3 to a Rolling or LTS version, a new rapididentity.properties template file is copied from the existing file. Upgrades from one Rolling Release version to a newer Rolling Release or LTS version does not create a new rapididentity.properties file.

Properties may be updated to address specific environment needs or concerns at any time, however, the default property values will always allow the current RapidIdentity Release version to function normally. If a property is uncommented and its value is blank, RapidIdentity will use the default value.