Note:

This example uses the manage-certificates tool that comes with PingAuthorize. The tool provides many of the same features as the Java keytool utility but can be easier to use. If you prefer to use keytool, use manage-certificates --display-keytool-command to show a command you can use to obtain a similar result with keytool.

  1. Generate a signing key pair for the Policy Editor.

    Create a key pair consisting of a private key and the corresponding public key. Put the key pair in a key store so that the Policy Editor can use it. The following command accomplishes both of these goals by generating a key store with a self-signed certificate.
    $ manage-certificates generate-self-signed-certificate \
      --keystore "healthcare-pap-signing.jks" \
      --keystore-type jks \
      --keystore-password "<keystore-password>" \
      --private-key-password "<private-key-password>" \
      --alias "healthcare-pap" \
      --subject-dn "cn=Healthcare PAP,dc=example,dc=com" \
      --days-valid 90
    • This command creates a key store with the filename healthcare-pap-signing.jks. The Policy Editor uses this to sign deployment packages.
    • The key store contains the Policy Editor's private signing key and the corresponding public key.
    • The key store itself has the password <keystore-password>.
    • The private key itself also has a password, <private-key-password>.
    • The signing key pair has the nickname/alias healthcare-pap.
    • The subject DN is arbitrary.
    • The keys are valid for 90 days.
    • This key store is a sensitive asset that you should carefully protect.
  2. Export a public certificate from the Policy Editor's key store.
    $ manage-certificates export-certificate \
      --keystore "healthcare-pap-signing.jks" \
      --keystore-password "<keystore-password>" \
      --alias "healthcare-pap" \
      --export-certificate-chain \
      --output-format pem \
      --output-file "healthcare-pap.pem"
    • This command creates a public certificate file with the filename healthcare-pap.pem.
    • The public certificate file is an input during the next step. It is not used directly by either the Policy Editor or PingAuthorize Server.
    • This public certificate represents the public key created in the previous step.
      Note:

      The alias is used to specify the key.

    • This public certificate is not a sensitive asset.
  3. Create a trust store for PingAuthorize Server for the public certificate from the previous step.
    $ manage-certificates import-certificate \
      --keystore "healthcare-pap-verification.jks" \
      --keystore-password "<keystore-password>" \
      --keystore-type jks \
      --alias "healthcare-pap" \
      --certificate-file "healthcare-pap.pem" \
      --no-prompt
    • This command creates a trust store with the filename healthcare-pap-verification.jks. PingAuthorize Server uses this to verify that deployment packages created by the Policy Editor were actually created by that GUI.
    • The trust store contains the Policy Editor's public certificate.
    • The trust store itself has the password <truststore-password>.
    • This trust store is not a sensitive asset.
  4. Configure the Policy Editor to use the key store to sign the deployment packages it creates.

    1. Make a copy of the default options file.
      $ cp config/options.yml my-options.yml
    2. Edit the new options file to include a configuration block like the following one, substituting your passwords and other values. Place this new block at the top level, parallel to the core block, either before or after it.
      deploymentPackageData:
        contentType: json
        keystore:
          resource: /path/to/healthcare-pap-signing.jks
          password: keystore-password
        securityLevel: signed
        signingKey:
          alias: healthcare-pap
          password: private-key-password
    3. Stop the Policy Editor.
      $ bin/stop-server
    4. Run setup using the --optionsFile my-options.yml argument. Customize all other options as appropriate for your needs.
    5. Start the Policy Editor.
      $ bin/start-server
  5. Configure the PingAuthorize Server to use the trust store for verification so that it accepts only deployment packages created by this Policy Editor.

    1. Create a trust manager provider, which is how the PingAuthorize Server configuration refers to a trust store file. Include the path to the trust store file and the trust store's password.
      $ dsconfig create-trust-manager-provider \
        --provider-name "Healthcare PAP Verification Store" \
        --type file-based \
        --set enabled:true \
        --set "trust-store-file:/path/to/healthcare-pap-verification.jks" \
        --set trust-store-type:JKS \
        --set "trust-store-pin:<truststore-password>"
    2. Configure the policy decision service.

      $ dsconfig set-policy-decision-service-prop \
        --set pdp-mode:embedded \
        --set "deployment-package</path/to/deployment-package.deploymentpackage" \
        --set deployment-package-security-level:signed \
        --set "deployment-package-trust-store:Healthcare PAP Verification Store" \
        --set "deployment-package-verification-key-nickname:healthcare-pap"

      Deployment packages are only for the embedded PDP mode, so this command sets the pdp-mode property accordingly. The other properties are described in the following table.

      Property Description

      deployment-package-security-level

      Determines whether PingAuthorize Server require a deployment package to be signed.

      Valid values are:
      • unsigned (the default)

        PingAuthorize Server does not check a deployment package for a trusted signature.

      • signed

        PingAuthorize Server checks a deployment package for a trusted signature and rejects a deployment package that fails that check.

        Whenever a deployment package fails a check, PingAuthorize Server continues to use the last accepted deployment package.

      deployment-package-trust-store

      Specifies a trust manager provider, which specifies in turn a trust store containing a Policy Editor's public certificate.

      This property is required if deployment-package-security-level is signed.

      deployment-package-verification-key-nickname

      Specifies the nickname or alias of the Policy Editor's public certificate.

      This property is required if deployment-package-security-level is signed.

      Note:

      For more information about the properties, see the Configuration Reference located in the server's docs/config-guide directory.