Skip to content

Technical Reference: Self-Signed Certificate Generation Logic

Parent Page: [How-To: Rhapsody Certificate Workflows] Description: This document details the step-by-step technical execution performed by the Ansible playbook (rhapsody_certificate.yml) when the "Generate Self-Signed Certificate" workflow is triggered.

🔍 High-Level Overview

This automation provides a "break-glass" or non-production mechanism to secure Rhapsody's HTTPS listeners. It generates a full PKI chain (Key -> CSR -> Certificate -> PFX) locally on the server using OpenSSL, configures Rhapsody to use it, and handles the service restart lifecycle.

🔄 Workflow Diagram

graph TD
    A[Start] --> B{Safety Check}
    B -- Dir Missing & Flag False --> C[Stop Execution]
    B -- Checks Pass --> D[Install Python Crypto Libs]
    D --> E[Generate RSA Key & CSR]
    E --> F[Sign Certificate 2 Years]
    F --> G[Export PFX - Legacy Mode]
    G --> H[Update rhapsody.properties]
    H --> I{Restart Requested?}
    I -- Yes --> J[Compare Fingerprints]
    J -- Changed --> K[Restart Rhapsody]
    J -- No Change --> L[Skip Restart]
    I -- No --> L
    K --> M[Finish]
    L --> M

🛠️ Detailed Execution Steps

1. Pre-Flight Safety Checks

The playbook implements a safety guard rail to prevent accidental execution on identifying the wrong host.

  • Directory Check: It checks for the existence of /data/orionhealth/certificates.

  • Logic: If the directory does not exist AND the input run_playbook is set to false, the playbook aborts immediately. This prevents accidental generation on fresh machines unless explicitly authorized.

  • Hostname Resolution: Captures the machine's hostname to be used as the Common Name (CN) and Subject Alternative Name (SAN).

2. Dependency Management

To perform cryptographic operations within Ansible, the following Python libraries are installed/verified on the target:

  • cryptography

  • pyOpenSSL

  • selinux

  • python3-setuptools

3. Cryptographic Operations (OpenSSL)

The playbook executes a standard PKI generation workflow within the /data/orionhealth/certificates directory:

  1. Private Key: Generates a 4096-bit RSA key (server.key).

  2. CSR (Signing Request): Generates a CSR (server.csr) using:

    • CN: The machine hostname.

    • SAN: DNS:<hostname>.

    • O: Orion Health / OU: RaaS.

  3. Self-Signing: Creates a certificate (server.crt) valid for 730 days (2 years).

  4. PKCS#12 Export (PFX): Combines the key and certificate into a .pfx archive.

    • Passphrase: Sets the keystore password to rhapsody.

    • Legacy Provider: Uses the -legacy OpenSSL provider flag. This is critical for compatibility with the Java environment Rhapsody runs on, ensuring modern OpenSSL (RHEL 8/9) outputs a format the JVM can read.

4. Application Configuration

The playbook copies the generated server.pfx to the runtime directory (/data/orionhealth/rhapsody/rhapsody/). It then uses Regex replacement to modify rhapsody.properties in place:

Property Value Set
WebMonitoringService.ssl.keystore server.pfx
WebMonitoringService.ssl.keystoretype PKCS12
WebMonitoringService.ssl.password rhapsody
WebMonitoringService.ssl.keypassword rhapsody

5. Smart Restart Logic

The playbook attempts to be idempotent regarding restarts to avoid unnecessary downtime.

  1. Fingerprinting: It captures the SSL fingerprint of the currently running service (via openssl s_client) and compares it to the newly generated certificate file.

  2. Restart Condition: The Rhapsody service is restarted only if:

    • The input restart_engine is set to true.

    • AND the fingerprints differ (confirming a change actually occurred).

⚠️ Technical Notes & Constraints

  • Hardcoded Passwords: The playbook currently sets the keystore password to rhapsody by default. This is intended for internal/non-prod use.

  • Java Compatibility: The use of openssl pkcs12 ... -legacy is a specific workaround for FIPS-compliant OSs (like RHEL 8/9) where the default encryption algorithms might be too new for older JDK versions.

  • Browser Warnings: As this is a self-signed certificate, users accessing the Rhapsody Web Management Console will receive browser security warnings. This is expected behavior.