Certificate Authority Options

If an EMS server is configured to require client certificates for authentication, the EMS REST Proxy can be configured to automatically generate a new temporary in-memory client certificate and private key pair to connect to the EMS server with on behalf of the proxy's client. The EMS REST Proxy supports two ways of doing this: ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.clone_client_certificates for clients that connect to the proxy with a trusted client certificate, and ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.generate_missing_client_certificates for clients that connect to the proxy without an existing client certificate.

For client certificates generated by the proxy to be trusted by the EMS server, the EMS server must include the proxy's ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.certificate in its ssl_server_trusted configuration option.

Certificate authority options can also be used to generate client certificates for use with HTTPS monitor URL connections. For connections to the EMS server, use the *.tls.* form of these options. For connections to HTTPS monitor URLs, use the *.monitor_tls.* form.

ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.certificate

The path to a file containing a certificate authority certificate to use when generating a new temporary client certificate. The certificate file can be in PEM (.pem), DER (.der), or PKCS#12 (.p12 or .pfx) format.

If a PKCS#12 file containing both the public certificate and its private key is used, then either specify the same file for both the ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.certificate and ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.private_key options, or leave the ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.certificate option unset and only set the ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.private_key option.

Default value: none

Example usage:

Command Line

--ems.server_groups.{group name}.servers.{server role}.tls.certificate_authority.certificate /path/to/ca_cert.pem 
--ems.server_groups.{group name}.servers.{server role}.monitor_tls.certificate_authority.certificate /path/to/ca_cert.pem

Config File

ems:
  server_groups:
    - name: example
      servers:
        - role: primary
          tls:
            certificate_authority:
              certificate: /path/to/ca_cert.pem 
          monitor_tls:
            certificate_authority:
              certificate: /path/to/ca_cert.pem

Environment Variable

EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_TLS_CERTIFICATE_AUTHORITY_CERTIFICATE='/path/to/ca_cert.pem' 
EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_MONITOR_TLS_CERTIFICATE_AUTHORITY_CERTIFICATE='/path/to/ca_cert.pem'

ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.clone_client_certificates

When enabled and a client connects to the proxy with a client certificate, the proxy will automatically generate a new client certificate with the information in the client's existing certificate, signed by the proxy's configured ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.private_key.

This new generated client certificate is then used to connect to the EMS server on behalf of the proxy's client.

Default value: false

Example usage:

Command Line

--ems.server_groups.{group name}.servers.{server role}.tls.certificate_authority.clone_client_certificates 
--ems.server_groups.{group name}.servers.{server role}.monitor_tls.certificate_authority.clone_client_certificates

Config File

ems:
  server_groups:
    - name: example
      servers:
        - role: primary
          tls:
            certificate_authority:
              clone_client_certificates: true 
          monitor_tls:
            certificate_authority:
              clone_client_certificates: true

Environment Variable

EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_TLS_CERTIFICATE_AUTHORITY_CLONE_CLIENT_CERTIFICATES=true 
EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_MONITOR_TLS_CERTIFICATE_AUTHORITY_CLONE_CLIENT_CERTIFICATES=true

ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.generate_missing_client_certificates

When enabled and a client connects to the proxy without a client certificate, but the EMS server has been configured to require client certificates for authentication, the proxy will automatically generate a new client certificate with its Common Name set to the username of the proxy's client, signed by the proxy's configured ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.private_key.

This new generated client certificate is then used to connect to the EMS server on behalf of the proxy's client.

Caution: A valid EMS username and password are still required even when connecting with a generated client certificate; however, using this option does allow clients without client certificates to connect to an EMS server that would otherwise reject them. Use this option with caution.

Default value: false

Example usage:

Command Line

--ems.server_groups.{group name}.servers.{server role}.tls.certificate_authority.generate_missing_client_certificates 
--ems.server_groups.{group name}.servers.{server role}.monitor_tls.certificate_authority.generate_missing_client_certificates

Config File

ems:
  server_groups:
    - name: example
      servers:
        - role: primary
          tls:
            certificate_authority:
              generate_missing_client_certificates: true 
          monitor_tls:
            certificate_authority:
              generate_missing_client_certificates: true

Environment Variable

EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_TLS_CERTIFICATE_AUTHORITY_GENERATE_MISSING_CLIENT_CERTIFICATES=true 
EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_MONITOR_TLS_CERTIFICATE_AUTHORITY_GENERATE_MISSING_CLIENT_CERTIFICATES=true

ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.private_key

The path to a file containing the private key corresponding to the ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.certificate used to generate new temporary client certificates.

Key files may be in PEM (.pem), DER (.der), or PKCS#12 (.p12 or .pfx) format.

If a PKCS#12 file containing both the CA certificate and its private key is used, then either specify the same file for both the ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.certificate and ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.private_key options, or leave the ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.certificate option unset and only set theems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.private_key option.

Default value: none

Example usage:

Command Line

--ems.server_groups.{group name}.servers.{server role}.tls.certificate_authority.private_key /path/to/ca_key.pem 
--ems.server_groups.{group name}.servers.{server role}.monitor_tls.certificate_authority.private_key /path/to/ca_key.pem

Config File

ems:
  server_groups:
    - name: example
      servers:
        - role: primary
          tls:
            certificate_authority:
              private_key: /path/to/ca_key.pem 
          monitor_tls:
            certificate_authority:
              private_key: /path/to/ca_key.pem

Environment Variable

EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_TLS_CERTIFICATE_AUTHORITY_PRIVATE_KEY='/path/to/ca_key.pem' 
EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_MONITOR_TLS_CERTIFICATE_AUTHORITY_PRIVATE_KEY='/path/to/ca_key.pem'

ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.private_key_password

The password used to decrypt the ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.private_key if it is encrypted.

Caution: For security purposes, this option is not allowed on the command-line and may only be specified via configuration file or environment variable.

Default value: none

Example usage:

Config File

ems:
  server_groups:
    - name: example
      servers:
        - role: primary
          tls:
            certificate_authority:
              private_key_password: p4ssw0rd123dontUSEme! 
          monitor_tls:
            certificate_authority:
              private_key_password: p4ssw0rd123dontUSEme!

Environment Variable

EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_TLS_CERTIFICATE_AUTHORITY_PRIVATE_KEY_PASSWORD='p4ssw0rd123dontUSEme!' 
EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_MONITOR_TLS_CERTIFICATE_AUTHORITY_PRIVATE_KEY_PASSWORD='p4ssw0rd123dontUSEme!'

ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.private_key_password_file

Path to a file containing the password used to decrypt the ems.server_groups[].servers[].{tls|monitor_tls}.certificate_authority.private_key if it is encrypted.

Warning: Make sure to appropriately protect and limit access to a private key password file if used.

Default value: none

Example usage:

Command Line

--ems.server_groups.{group name}.servers.{server role}.tls.certificate_authority.private_key_password_file /path/to/secret_password.txt 
--ems.server_groups.{group name}.servers.{server role}.monitor_tls.certificate_authority.private_key_password_file /path/to/secret_password.txt

Config File

ems:
  server_groups:
    - name: example
      servers:
        - role: primary
          tls:
            certificate_authority:
              private_key_password_file: /path/to/secret_password.txt 
          monitor_tls:
            certificate_authority:
              private_key_password_file: /path/to/secret_password.txt

Environment Variable

EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_TLS_CERTIFICATE_AUTHORITY_PRIVATE_KEY_PASSWORD_FILE='/path/to/secret_password.txt' 
EMSRESTD_EMS_SERVER_GROUPS_{GROUP NAME}_SERVERS_{SERVER ROLE}_MONITOR_TLS_CERTIFICATE_AUTHORITY_PRIVATE_KEY_PASSWORD_FILE='/path/to/secret_password.txt'