Transport security (TLS)

Orchestrator instances must communicate securely with integrated identity systems, secrets providers, and other Orchestrator instances.

The tls field declares the configuration of transport layer security objects. These TLS objects are referenced by the name you define in the Orchestrator HTTP server configuration (for inbound connections), and in Connector or AppGateway configurations (for outbound connections).

On Windows, the Orchestrator can retrieve certificates and keys from the Windows Certificate Store.

Configuration options

Cert File

The certFile represents a path to a PEM encoded certificate.

Key File

The keyFile represents a path to a PEM encoded private key.

CA File

The caFile represents a path to a PEM encoded certificate authority that HTTP clients use when verifying server certificates. If the caFile is undefined, the Orchestrator will default to using the set of trusted CAs found on the operating system. When defined, the supplied CA will be added to the pool of trusted CAs. This field is commonly used when a self-signed (untrusted) CA is used to generate certificates for upstream services.

Min Version

Specifying minVersion is optional and is used to enforce the minimum TLS version. For security, we only allow TLS version 1.2 or higher to be specified. Anything lower than TLS 1.2 will result in the orchestrator failing to start. If not specified, the minimum TLS version will default to TLS 1.2.

Enabled Ciphers

enabledCiphers allows a list of ciphers to be enabled explicitly. By default, the Orchestrator uses the cipher suites in the secure cipher suite list below. This feature is optional and only available with TLS 1.2.

When using TLS 1.3 cipher suites are not configurable.

When using TLS 1.2 (default) cipher suites from the secure list below are used.

When using TLS 1.2 in conjunction with enabledCiphers the ciphers suites from the following list are available but must be listed explicitly. Only the ciphers specified will be used.

For an up-to-date list of secure and insecure cipher suites, please see the Golang documentation. Please note that when listing the ciphers in config, the uppercase name should be used (e.g. TLS_AES_256_GCM_SHA384).

Insecure Skip Verify

The insecureSkipVerify option should only be used for testing. When set to true, the HTTP client will not validate the server’s certificate chain and host name. This option is not suitable for the TLS configuration used for the Orchestrator’s HTTP server, and should always be used with extreme caution.

Windows Certificate Store

If you run the Orchestrator on Windows, you can import the certificates to the Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SystemCertificates\MY store and set the TLS configuration to retrieve certificates and their keys from the Windows Certificate Store via subject or thumbprint.

For example, to search by subject:

tls:
  maverics:
    windowsCertStore:
      subject: "MySiteCert"

To search by thumbprint:

tls:
  maverics:
    windowsCertStore:
      thumbprint: 838A1C18C19FREDACTED47CC21071A0F220617466

Alternatively, you can use an environment variable to search the Windows Cert Store.

MAVERICS_TLS_SERVER_WINDOWS_THUMBPRINT - to search by thumbprint. MAVERICS_TLS_SERVER_WINDOWS_SUBJECT - to search by subject.

The windowsCertStore key cannot be combined with any combination of certFile or keyFile. The thumbprint and subject search methods are also mutually exclusive and cannot be used together in the windowsCertStore section. Additionally, certificates must be imported into the Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SystemCertificates\MY store.

Examples

http:
  address: :443
  tls: maverics

tls:
  maverics: 
    certFile: certs/sonarsystems.crt
    keyFile: certs/sonarsystems.key

  ldapTLS:
    caFile: certs/privCA.crt
    minVersion: 1.3

  ldapTLSLegacy:
    caFile: certs/privCA-old.crt
    minVersion: 1.2
    enabledCiphers:
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
      - TLS_RSA_WITH_3DES_EDE_CBC_SHA

  ldapTestTLS:
    insecureSkipVerify: true

connectors:
  - name: ldapProd
    type: ldap
    tls: ldapTLS
    # ...

  - name: ldapLegacy
    type: ldap
    tls: ldapTLSLegacy
    # ...

  - name: ldapTest
    type: ldap
    tls: ldapTestTLS
    # ...

Using a Secret Provider

Certificates and keys can be fetched from Secret Providers:

tls:
  maverics:
    certFile: <sonarsystems-cert>
    keyFile: <sonarsystems-key>

Inbound TLS

When configuring TLS for the Orchestrator’s HTTP server, provide certFile and keyFile paths that resolve to a PEM encoded key pair.

tls:
  maverics:
    certFile: certs/sonarsystems.crt.pem
    keyFile: certs/sonarsystems.key.pem

http:
  address: :443
  tls: maverics

Outbound TLS

It is common for enterprises to use their own certificate authority for internal applications. If a certificate authority (CA) is not already added to a hosts trusted CA set, the below configuration can be used.

tls:
  ldapTLS:
    caFile: certs/internal-non-root-ca.crt

connectors:
  - name: ldapProd
    type: ldap
    tls: ldapTLS
    # ...

HTTP server Sessions and user state