Skip to content

Technical Reference: Custom Certificate Application Logic

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

🔍 High-Level Overview

This automation facilitates the secure deployment of customer-provided PKI artifacts (PFX/PKCS#12) to Rhapsody instances. It handles the secure transfer of certificate data, creates safety backups of existing certificates, and updates the necessary Rhapsody property configurations to bind the new certificate to the web monitoring and administration services.

🔄 Workflow Diagram

graph TD
    A[Start] --> B[Generate UTC Timestamp]
    B --> C{Existing Cert Exists?}
    C -- Yes --> D[Create Backup (.bak_ts)]
    C -- No --> E[Proceed]
    D --> E
    E --> F{Input Method?}
    F -- Base64 (Preferred) --> G[Decode & Write server.pfx]
    F -- File Path (Fallback) --> H[Copy File to server.pfx]
    G --> I[Set Permissions (0400)]
    H --> I
    I --> J[Update rhapsody.properties]
    J --> K{Restart Requested?}
    K -- Yes --> L[Restart Rhapsody Service]
    K -- No --> M[Finish]
    L --> M

🛠️ Detailed Execution Steps

1. Safety Backups

Before making any changes, the playbook preserves the current state.

  • Timestamping: Generates a generic UTC timestamp (YYYYMMDDTHHMMSSZ).

  • Backup Logic: Checks if /data/orionhealth/rhapsody/rhapsody/server.pfx already exists.

  • Action: If found, copies the existing file to server.pfx.bak_<timestamp>. This allows for a quick rollback if the new certificate is corrupt or password-mismatched.

2. Certificate Deployment

The playbook supports two methods for placing the certificate file, prioritizing the secure environment variable method.

  • Method A: Base64 Injection (Primary)

    • Source: Looks for the CERT_PFX_B64 environment variable (injected via GitHub Actions inputs).

    • Action: Decodes the Base64 string on the fly and writes the binary content directly to server.pfx.

    • Security: Uses no_log: true to prevent the raw certificate data from appearing in the Ansible logs.

  • Method B: Local File Copy (Fallback)

    • Source: Looks for the certificate_file_path variable.

    • Action: Copies the file from the specified path on the runner to the destination.

    • Condition: Only executes if the Base64 variable is empty.

  • Permissions: The resulting file is strictly secured with mode 0400 (Read-only for owner) and owned by the rhapsody user/group.

3. Application Configuration

The playbook updates rhapsody.properties to ensure both the Web Management Console and the Administration (Remote Connect) service use the new certificate.

It performs regex replacement for the following keys:

Web Monitoring Service (HTTPS 8444)

  • WebMonitoringService.ssl.keystore: Set to server.pfx

  • WebMonitoringService.ssl.keystoretype: Set to PKCS12

  • WebMonitoringService.ssl.password: Set to {{ admin_cert_password }}

  • WebMonitoringService.ssl.keypassword: Set to {{ admin_cert_password }}

Administration Manager (Remote Connect)

  • AdministrationManager.keystore: Set to server.pfx

  • AdministrationManager.keystoretype: Set to PKCS12

  • AdministrationManager.password: Set to {{ admin_cert_password }}

  • AdministrationManager.keypassword: Set to {{ admin_cert_password }}

4. Service Lifecycle

  • Restart Condition: The Rhapsody service is restarted only if the restart_engine input variable evaluates to true.

  • Impact: A restart is required for the new keystore configuration to be loaded by the JVM.

⚠️ Technical Notes & Constraints

  • Password Special Characters: The password is injected directly into the rhapsody.properties file via Ansible variables. Passwords containing complex special characters (especially those interpreted by shells like $ or escapes like \) should be avoided or carefully tested, as they can cause the properties file parsing to fail.

  • Keystore Type: The playbook explicitly enforces PKCS12 as the keystore type. Ensure the uploaded file is a valid .pfx or .p12 file; legacy JKS files are not supported by this workflow.