HPA installation and deployment HPA portal Portal configuration Configuration file - security.config

Certificates

To expose access trough https protocol, the different components use Java keystore. This file helps to configure keystore/truststore for the different modules.

Keystore vs Truststore

In short keystore can be used to store a public/private key that can be used to:

  • sign the https protocol
  • crypt/decrypt JWT or SAML token

The truststore contains CA (certificate authority) to trust https requests.

Internal communication

As the different components exchange information between themselves, especially with keycloak, they have to trust the certificates of the others components. See the architecture diagram for details.

The different components that expose https endpoint:

  • HPA Portal
  • HPA Webview
  • Keycloak
  • HPA EM Channel for agent communication

The components that need a truststore internally:

  • HPA Portal to consume Keycloak API And optionally (not activated by default) :
  • HPA Webview to consume HPA EM REST API
  • HPA extractor to consume HPA EM REST API

Another fixed public/private key is used:

  • Keycloak hpa-hexagon SAML and Webview Service Provider
  • Keycloak realm keys are stored in database. Keys can be exported through Keycloak GUI
  • HPA Webview use the keystore : spprivatekey.jks with a default password : password

Some internal communication are not secured by default, restrict to 127.0.0.1 local loop:

  • HPA EM Channel (HPA binary proprietary protocol), clients:
    • Webview
    • APMSQL
  • HPA EM REST API, clients:
    • Webview
    • APMSQL
    • HPA extractor
  • JDBC protocol

Defaults and overrides

security.config.default holds the whole configuration and is loaded at every start. security.config is optional : when present it is loaded first and overrides the tunable values, such as the keystore passwords, the aliases or HPA_ROLE_ADMIN.

The computed values (URLs, certificate paths, truststore options) are always recomputed by security.config.default from the values of environment.config, so that a formula change applies to every installation.

Certificate check during installation

Each module verifies, at install time, that its alias exists in the keystore and that the certificate covers the DNS names and IP addresses the module is configured with.

  • Alias missing: a self-signed certificate is generated, unless HPA_CERTIFICATE_<alias>_AUTOGENERATED=0 is set.
  • Alias present, can be updated automatically if generated by a previous installation (self-signed, subject CN=hpa,OU=demo,DC=hexagon-perf,DC=com), it happens to fix configuration.
  • Alias present, any other certificate : the certificate is never replaced, since the installation cannot recreate it. A warning names the required subject alternative names and the installation goes on;

The keystore file is copied next to itself, with a timestamp suffix, before any replacement.

hpa-mcp-server and hpa-external-api connect to hpa-portal-server on its listen IP (HPA_URL_SERVER_PRIVATE): the hpa_portal certificate must cover that IP.

Security.config file

#!/bin/bash
#
# Default values, sourced after security.config : a value already set there wins.
# Site-tunable variable : export HPA_X=${HPA_X-default}, with "-" and not ":-" so that an
# empty value stays an explicit choice. Computed variable (URL, path, options) : plain
# assignment, so that a formula change applies to every installation.
#

export HPA_BASE_HTTP=${HPA_BASE_HTTP-https}

port_replacement() {
  HPA_PORT_PUBLIC=${HPA_EXTERNAL_PORT:-"$HPA_NGINX_PORT"}

  if [[ $HPA_PORT_PUBLIC -eq 443 || $HPA_PORT_PUBLIC -eq 80 ]]; then
    export HPA_HOST_PORT_PUBLIC=$HPA_EXTERNAL_DNS
  else
    export HPA_HOST_PORT_PUBLIC=$HPA_EXTERNAL_DNS:$HPA_PORT_PUBLIC
  fi
}

port_replacement

export HPA_URL_SERVER_PUBLIC=$HPA_BASE_HTTP://$HPA_HOST_PORT_PUBLIC${HPA_URL_CONTEXTPATH_WITH_LEADING_SLASH}
export HPA_URL_SERVER_PRIVATE=$HPA_BASE_HTTP://$HPA_SERVER_LISTENIP:$HPA_SERVER_PORT
export HPA_URL_EXTRACTOR=http://$HPA_EXTRACTOR_LISTENIP:$HPA_EXTRACTOR_PORT
export HPA_URL_EM_WEB=http://$HPA_EM_WEB_HOST:$HPA_EM_WEB_PORT
export HPA_URL_WEBVIEW_PUBLIC=$HPA_BASE_HTTP://$HPA_HOST_PORT_PUBLIC${HPA_URL_CONTEXTPATH_WITH_LEADING_SLASH}/introscope
export HPA_URL_WEBVIEW_PRIVATE=$HPA_BASE_HTTP://$HPA_EM_WEBVIEW_LISTENIP:$HPA_EM_WEBVIEW_PORT
export HPA_URL_KEYCLOAK_PUBLIC=$HPA_BASE_HTTP://$HPA_HOST_PORT_PUBLIC${HPA_URL_CONTEXTPATH_WITH_LEADING_SLASH}/keycloak
export HPA_URL_KEYCLOAK_PRIVATE=$HPA_BASE_HTTP://$HPA_KEYCLOAK_LISTENIP:$HPA_KEYCLOAK_PORT
export HPA_URL_MCP_PUBLIC=$HPA_BASE_HTTP://$HPA_HOST_PORT_PUBLIC${HPA_URL_CONTEXTPATH_WITH_LEADING_SLASH}/mcp
export HPA_URL_MCP_PRIVATE=$HPA_BASE_HTTP://$HPA_MCP_LISTENIP:$HPA_MCP_PORT

#
# NGINX
#
export HPA_NGINX_CERTIFICATE=$HPA_CERTIFICATES_DIR/nginx_fullchain.pem
export HPA_NGINX_CERTIFICATE_KEY=$HPA_CERTIFICATES_DIR/nginx_privkey.pem
export HPA_NGINX_CERTIFICATE_PASSWORD_FILE=$HPA_CERTIFICATES_DIR/nginx_privkey.pass

#
# HPA truststore
#
export HPA_TRUSTSTORE=$HPA_CERTIFICATES_DIR/hpa_truststore.jks
export HPA_TRUSTSTORE_PWD=${HPA_TRUSTSTORE_PWD-changeit}
export HPA_TRUSTSTORE_TYPE=${HPA_TRUSTSTORE_TYPE-JKS}
export HPA_TRUSTSTORE_OPTS="-Djavax.net.ssl.trustStore=$HPA_TRUSTSTORE -Djavax.net.ssl.trustStorePassword=$HPA_TRUSTSTORE_PWD -Djavax.net.ssl.trustStoreType=$HPA_TRUSTSTORE_TYPE"

#
# HPA keystore
#
export HPA_KEYSTORE=$HPA_CERTIFICATES_DIR/hpa_keystore.p12
export HPA_KEYSTORE_PWD=${HPA_KEYSTORE_PWD-changeit}
export HPA_KEYSTORE_TYPE=${HPA_KEYSTORE_TYPE-PKCS12}

#
# Certificate are called, in pem format and named :
# <alias>_certificate.pem
# <alias>_private_key.pem
#
# KEYCLOAK
#
export HPA_KEYCLOAK_ALIAS=${HPA_KEYCLOAK_ALIAS-keycloak}
export HPA_REALM_KEYCLOAK=$HPA_CERTIFICATES_DIR/keycloak_realm_hpa.pem
export HPA_REALM_KEYCLOAK_ALIAS=${HPA_REALM_KEYCLOAK_ALIAS-keycloack_hpa_realm}

#
# SERVER
#
export HPA_SERVER_ALIAS=${HPA_SERVER_ALIAS-hpa_portal}

#
# MCP SERVER
#
export HPA_MCP_ALIAS=${HPA_MCP_ALIAS-hpa_mcp}

#
# EXTRACTOR
#
export HPA_EXTRACTOR_ALIAS=${HPA_EXTRACTOR_ALIAS-hpa_extractor}

#
# EM
#
export HPA_EM_WEB_ALIAS=${HPA_EM_WEB_ALIAS-introscope_em}
export HPA_CHANNEL_ALIAS=${HPA_CHANNEL_ALIAS-introscope_channel}

#
# WEBVIEW
#
export HPA_WEBVIEW_ALIAS=${HPA_WEBVIEW_ALIAS-introscope_webview}

#
# Admin role
#
export HPA_ROLE_ADMIN="${HPA_ROLE_ADMIN-Admin}"

If restricted firewall rules

Check against your firewall rules if default ports are authorized

HPA_EM_PORT HPA_KEYCLOAK_PORT HPA_EM_WEBVIEW_PORT HPA_SERVER_PORT

These ports must be opened to external network: end-user or calypso environments, see the firewall rules.

If restriction on internal server port

The others values should not be modified except if some of these ports are already used on the target HPA server.