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.

ClientAuth

clientAuth determines the server’s policy for TLS Client Authentication. The default is NoClientCert. Client authentication types are available as follows:

NoClientCert indicates that no client certificate should be requested during the handshake, and if any certificates are sent they will not be verified.
RequestClientCert indicates that a client certificate should be requested during the handshake, but does not require that the client send any certificates.
RequireAnyClientCert indicates that a client certificate should be requested during the handshake, and that at least one certificate is required to be sent by the client, but that certificate is not required to be valid.
VerifyClientCertIfGiven indicates that a client certificate should be requested during the handshake, but does not require that the client sends a certificate. If the client does send a certificate it is required to be valid.
RequireAndVerifyClientCert indicates that a client certificate should be requested during the handshake, and that at least one valid certificate is required to be sent by the client.

ClientCAFiles

clientCAFiles optionally defines the set of root certificate authorities that servers use to verify a client certificate. The ClientAuth policy defines the behavior of how client certificates are verified.

OCSP

Online Certificate Status Protocol (OCSP) allows clients and servers to check the revocation status of their peer’s certificate.

When clientAuth is set to VerifyClientCertIfGiven or RequireAndVerifyClientCert, OCSP checking may be done.

If clientAuth is NoClientCert, RequestClientCert, or RequireAnyClientCert, OCSP checking is not performed.

In the case of VerifyClientCertIfGiven, OCSP checking is only done if the client chooses to present a certificate.

RequireAndVerifyClientCert is the only clientAuth option that forces the client’s certificate to be checked via OCSP during the TLS handshake.

Enabled

enabled is a boolean flag that determines whether OCSP checking will be done (when applicable).

Cache Timeout

cacheTimeout defines the number of seconds OCSP responses will remain cached. The default is 86,400 seconds (1 day).

If cacheTimeout is defined, the value is treated as follows:

< 0: caching is disabled
0: caching is enabled with a timeout of 1 day
> 0: caching is enabled with the specified timeout in seconds

Setting the cache timeout to a negative value (e.g., -1) instructs the Orchestrator to disable caching of OCSP responses. Disabling caching is highly discouraged, as it may result in significant performance degradation. This option is primarily intended for troubleshooting, allowing administrators to debug issues in the request flow.

Note: setting a value of ‘0’ will not enable caching with a timeout of zero. The value ‘0’ will cause the Orchestrator to use its default value of 1 day.

CRL

Certificate Revocation List (CRL) allows clients and servers to check the revocation status of their peer’s certificate by retrieving a list of revoked certificates issued by the Certificate Authority (CA).

When clientAuth is set to VerifyClientCertIfGiven or RequireAndVerifyClientCert, CRL checking may be performed. If clientAuth is set to NoClientCert, RequestClientCert, or RequireAnyClientCert, CRL checking is not performed.

In the case of VerifyClientCertIfGiven, CRL checking is only done if the client chooses to present a certificate. RequireAndVerifyClientCert is the only clientAuth option that forces the client’s certificate to be checked against the CRL during the TLS handshake.

Enabled

enabled is a boolean flag that determines whether CRL checking will be done (when applicable).

Cache Timeout

cacheTimeout defines the number of seconds the CRL file will remain cached. The default is 86,400 seconds (1 day).

If cacheTimeout is defined, the value is treated as follows:

< 0: caching is disabled
0: caching is enabled with a timeout of 1 day
> 0: caching is enabled with the specified timeout in seconds

Setting the cache timeout to a negative value (e.g., -1) instructs the Orchestrator to disable caching of CRL files. Disabling caching is highly discouraged, as it may result in significant performance degradation. This option is primarily intended for troubleshooting, allowing administrators to debug issues in the request flow.

Note: setting a value of ‘0’ will not enable caching with a timeout of zero. The value ‘0’ will cause the Orchestrator to use its default value of 1 day.

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

Basic TLS Configuration

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
    # ...

Orchestrator with mTLS

http:
  address: :443
  tls: maverics

tls:
  maverics:
    certFile: certs/sonarsystems.crt
    keyFile: certs/sonarsystems.key
    clientAuth: VerifyClientCertIfGiven
    clientCAFiles:
      - certs/clientCA.pem
    ocsp:
      enabled: true
      cacheTimeout: 3600
    crl:
      enabled: true
      cacheTimeout: 86400

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