Older versionVersion 1.5.0 SolutionsUse custom SSL certificate for https

Use custom SSL certificate for https

This PhenixID Solution Document (PSD) is written for PhenixID Server.

This PSD describes how to configure PhenixID Server to use a custom SSL certificate for https.

The reader of this PSD should have some basic knowledge about PhenixID Server.

System requirements

  • PhenixID Server installed.
  • Keystore file (.p12) and keystore password

Overview

This instruction will describe how to setup PhenixID server to use a custom SSL certificate.

Configuration

Make sure you have a recent copy of:

  • <PhenixID Server Installation Path>\config\boot.json.
  • <PhenixID Server Installation Path>\config\phenix-store.json.

Please note that the configuration below has to be adjusted suit your environment!

Resources

Put a copy of the certificate to be used for SSL in the resources folder of PhenixID Server <Installation Path>/Server/resources.

Make sure that all certificates are in p12 format and has file extension *.p12.

Restart PhenixID Server

Restart the server to make sure all resource files are written to the configuration file phenix-store.json.

Stop the server when this is done before proceeding.

Add KEYSTORES configuration

Add the following configuration in the upper part of phenix-store.json:

"KEYSTORES" : [ {
    "id" : "server",
    "type" : "pkcs12",
    "password" : "YourTopSecretPassword",
    "certificateAlias" : "server",
    "privateKeyPassword" : "YourTopSecretPassword",
    "resource" : "server.p12"
  } ],

Make sure to adjust the configuration above in order to suit your environment!

The following commands could be used in order to list information from the certificate keystore like the certificate alias:

keytool -v -list -storetype pkcs12 -keystore server.p12

 Other GUI tools like Portecle or KeyStore Explorer could also be used.

Add HTTP_CONFIGURATIONS

The HTTP_CONFIGURATIONS are used as configuration for HTTP from referenced modules.

Add the following configuration in the upper part of phenix-store.json:

"HTTP_CONFIGURATIONS" : [ {
    "id" : "https",
    "port" : "8443",
    "ssl" : "true",
    "sslKeyStore" : "server"
  } ],

Explanation of parameters:

  • id: The configuration will be referenced by it's id, in this case "https".
  • port: The port to be used by this configuration.
  • ssl: If SSL should be enabled or not.
  • sslKeyStore: a reference to the SSL keystore configured in previous step

 

Modify boot.json

boot.json has to be modified to use the newly configured http configuration.

  • Remove all "ssl" parameters e.g. "ssl":"true"
  • Remove all "port" parameters e.g.  "port":"8443"
  • Add the previously configured http configuration to all http enabled modules by adding "httpConfig":"ID_OF_HTTPCONFIG",

An example of a configuration is found below:

            "module": "com.phenixidentity~phenix-prism",
            "enabled": true,
            "config": {
                "base_url": "/config",
                "enable_language" : "false",
                "httpConfig" : "https",
                "enable_module_deployment": true,
                "enable_roles": "true",
                "enable_language": "false",
                "display_name": "Configuration Manager",
                "prism_modules": [{
                    "name": "com.phenixidentity~phenix-prism-start",
                    "config": {
                        "display_name": "Start",
                        "base_uri": "start",
                        "httpConfig" : "https",
                        "requires_role": "sysadmin"
                    }
                }, {
                    "name": "com.phenixidentity~phenix-prism-guides",
                    "config": {
                        "display_name": "Scenarios",
                        "base_uri": "scenarios",
                        "httpConfig" : "https",
                        "requires_role": "sysadmin"
                    }
                }]
            }
        }, {
            "module": "com.phenixidentity~auth-http",
            "enabled": true,
            "config": {
                "httpConfig" : "https",
                "web_root": "webroot/authentication/web"
            }
        }

Modify phenix-store.json

If phenix-store.json is loading http-enabled modules, these modules has to be modified the same way as the modules in boot.json.

Start server

  • Save all modified files.
  • Restart the PhenixID Server.

Verify SSL certificate

  1. Open a web browser
  2. Browse to PhenixID server
  3. Verify https certificate