Search
K

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.

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.
Secure Cipher Suites
  • 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_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
  • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
Insecure Cipher Suites
The following ciphers are considered weak or insecure.
  • TLS_RSA_WITH_RC4_128_SHA
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
  • TLS_ECDHE_RSA_WITH_RC4_128_SHA
  • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

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
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:
caFile: certs/privCA.crt
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/privCA.crt
connectors:
- name: ldapProd
type: ldap
tls: ldapTLS
# ...