Table of Contents

How to Add a Custom Certificate Authority (CA) to PhenixID Server

Overview

Adding a custom Certificate Authority (CA) allows signed documents to be issued with a CA that is trusted within your organization. This ensures that the documents are compliant with internal security policies and widely recognized by organizational systems.

Common Use Cases

  1. Signing Documents:
    • Issue certificates for signing PDF and XML documents, ensuring the authenticity and integrity of the files.
  2. Issuing OneTouch Profiles:
    • Use the custom CA to issue secure profiles for PhenixID OneTouch, enhancing trust and compliance with organizational requirements.

This guide outlines the steps to:

  1. Add a custom CA .p12 file to the PhenixID Server configuration.
  2. Modify the phenix-store.json configuration file to reference the new CA.

Instructions

Step 1: Add the .p12 File to the Configuration

  1. Log in to the PhenixID Configuration UI.
  2. Navigate to Scenarios > Federation, then click the plus sign (+) next to Keystore.
  3. In the dialog:
    • Set a descriptive name for the keystore.
    • Click Next and upload your .p12 file.
    • Enter the password for the .p12 file.
  4. Click Verify and Show to confirm the content of the keystore.
  5. Click Next, then click Create to save the configuration.
  6. Once the scenario is created, copy the ID for the keystore. This ID will be used in subsequent steps.

Step 2: Edit the phenix-store.json File

Before proceeding, create a backup of the phenix-store.json file to ensure you can revert changes if needed.

  1. Open the phenix-store.json file in a text editor.
    The file is located in the PhenixID Server configuration directory.
  2. Locate the CA_CONFIGURATIONS section.
    • This section contains the configurations for Certificate Authorities. It typically includes a default PhenixID CA.
  3. Add the following example configuration to the CA_CONFIGURATIONS section, updating the values to match your environment.
    Ensure that the "ca_keystore_ref" value is set to the ID you copied earlier.

Example Configuration for a Custom CA

{
  "id": "customsignca",
  "name": "My Custom CA",
  "alias": "customsignca",
  "config": {
    "ca_keystore_ref": "yourkeystoreid",
    "ca_profiles": [
      {
        "id": "signprofile",
        "name": "My Signing CA Profile",
        "alias": "default",
        "description": "Profile for signing documents",
        "pipe_ref": "0ac71f4e-9e59-4e39-84a9-da1d16ce342a",
        "issue_pipe_ref": "0ac71f4e-9e59-4e39-84a9-da1d16ce342a",
        "revoke_pipe_ref": "9c4b54b5-53f9-4e91-8876-5f0cffc7c0ff",
        "rules": {
          "subject": {
            "regex": "^CN=.*",
            "required": "true"
          },
          "key": {
            "size": "2048",
            "algorithm": "RSA",
            "values": {
              "size": "2048",
              "algorithm": "RSA"
            }
          },
          "key_usage": {},
          "not_before": {
            "value": "now"
          },
          "not_after": {
            "value": "duration:P365D"
          },
          "extensions": {},
          "signature_algorithm": {
            "value": "SHA256WithRSA"
          }
        }
      }
    ]
  }
}

Notes

  1. Update the following fields to reflect your environment:
    • ca_keystore_ref: Replace yourkeystoreid with the keystore ID copied in Step 1.
    • name, description, rules: Adjust as per your organization's requirements.
    • pipe_ref, issue_pipe_ref, revoke_pipe_ref: Ensure these references are correct for your setup.
  2. Ensure the JSON is valid to avoid issues during startup.

Step 3: Restart the PhenixID Service

Restart the PhenixID Server service to apply the changes:

  • On Linux/Unix:

    sudo /opt/PhenixID/Server/bin/stop-PhenixID.sh
sudo /opt/PhenixID/Server/bin/start-PhenixID.sh

  • On Windows:
    Use the Services application to restart the PhenixID Server service.

Example: Using the Custom CA with CreateShortTermKeyStoreValve

The CreateShortTermKeyStoreValve can reference the custom CA for issuing short-term keystores. Below is an example configuration:

{
  "name": "CreateShortTermKeyStoreValve",
  "config": {
    "subjectKeyParamater": "CN={{item.cn}},O=MyOrganization,C=SE",
    "caTemplateKeyParamater": "customsignca",
    "keyUsage": ["digitalSignature", "keyEncipherment"],
    "notAfterNumberOfDays": 180
  }
}

Explanation of the Configuration

  1. subjectKeyParamater:
    • Specifies the subject Distinguished Name (DN) for the certificate. Example:
      • CN={{item.cn}},O=MyOrganization,C=SE
    • Customize this to fit your organization's naming conventions.
  2. caTemplateKeyParamater:
    • References the custom CA configured in phenix-store.json using the id (customsignca).
  3. keyUsage:
    • Specifies key usage extensions such as:
      • digitalSignature: Enables signing.
      • keyEncipherment: Enables encryption.
  4. notAfterNumberOfDays:
    • Sets the certificate's validity period in days (e.g., 180 days).

This configuration enables the valve to generate short-term certificates signed by the custom CA.

Conclusion

By following this guide, you have successfully added a custom Certificate Authority (CA) to the PhenixID Server. This enables the server to:

  1. Sign Documents:
    • Issue certificates for signing PDF and XML documents, ensuring authenticity and organizational compliance.
  2. Issue OneTouch Profiles:
    • Use the custom CA to issue trusted profiles for PhenixID OneTouch, enhancing user authentication workflows.

Adding a custom CA ensures that signed documents and issued certificates comply with internal trust requirements, providing both security and consistency across your systems.

X509 (Certificates)