druid/docs/content/operations/tls-support.md

layout
doc_page

TLS Support

General Configuration

Property	Description	Default
druid.enablePlaintextPort	Enable/Disable HTTP connector.	true
druid.enableTlsPort	Enable/Disable HTTPS connector.	false

Although not recommended but both HTTP and HTTPS connectors can be enabled at a time and respective ports are configurable using druid.plaintextPort and druid.tlsPort properties on each node. Please see Configuration section of individual nodes to check the valid and default values for these ports.

Jetty Server TLS Configuration

Druid uses Jetty as an embedded web server. To get familiar with TLS/SSL in general and related concepts like Certificates etc. reading this Jetty documentation might be helpful. To get more in depth knowledge of TLS/SSL support in Java in general, please refer to this guide. The documentation here can help in understanding TLS/SSL configurations listed below. This document lists all the possible values for the below mentioned configs among others provided by Java implementation.

Property	Description	Default	Required
druid.server.https.keyStorePath	The file path or URL of the TLS/SSL Key store.	none	yes
druid.server.https.keyStoreType	The type of the key store.	none	yes
druid.server.https.certAlias	Alias of TLS/SSL certificate for the connector.	none	yes
druid.server.https.keyStorePassword	The Password Provider or String password for the Key Store.	none	yes

The following table contains configuration options related to client certificate authentication.

Property	Description	Default	Required
druid.server.https.requireClientCertificate	If set to true, clients must identify themselves by providing a TLS certificate. If requireClientCertificate is false, the rest of the options in this table are ignored.	false	no
druid.server.https.trustStoreType	The type of the trust store containing certificates used to validate client certificates. Not needed if requireClientCertificate is false.	java.security.KeyStore.getDefaultType()	no
druid.server.https.trustStorePath	The file path or URL of the trust store containing certificates used to validate client certificates. Not needed if requireClientCertificate is false.	none	yes, only if requireClientCertificate is true
druid.server.https.trustStoreAlgorithm	Algorithm to be used by TrustManager to validate client certificate chains. Not needed if requireClientCertificate is false.	javax.net.ssl.TrustManagerFactory.getDefaultAlgorithm()	no
druid.server.https.trustStorePassword	The Password Provider or String password for the Trust Store. Not needed if requireClientCertificate is false.	none	no
druid.server.https.validateHostnames	If set to true, check that the client's hostname matches the CN/subjectAltNames in the client certificate. Not used if requireClientCertificate is false.	true	no
druid.server.https.crlPath	Specifies a path to a file containing static Certificate Revocation Lists, used to check if a client certificate has been revoked. Not used if requireClientCertificate is false.	null	no

The following table contains non-mandatory advanced configuration options, use caution.

Property	Description	Default	Required
druid.server.https.keyManagerFactoryAlgorithm	Algorithm to use for creating KeyManager, more details here.	javax.net.ssl.KeyManagerFactory.getDefaultAlgorithm()	no
druid.server.https.keyManagerPassword	The Password Provider or String password for the Key Manager.	none	no
druid.server.https.includeCipherSuites	List of cipher suite names to include. You can either use the exact cipher suite name or a regular expression.	Jetty's default include cipher list	no
druid.server.https.excludeCipherSuites	List of cipher suite names to exclude. You can either use the exact cipher suite name or a regular expression.	Jetty's default exclude cipher list	no
druid.server.https.includeProtocols	List of exact protocols names to include.	Jetty's default include protocol list	no
druid.server.https.excludeProtocols	List of exact protocols names to exclude.	Jetty's default exclude protocol list	no

Druid's internal communication over TLS

Whenever possible Druid nodes will use HTTPS to talk to each other. To enable this communication Druid's HttpClient needs to be configured with a proper SSLContext that is able to validate the Server Certificates, otherwise communication will fail.

Since, there are various ways to configure SSLContext, by default, Druid looks for an instance of SSLContext Guice binding while creating the HttpClient. This binding can be achieved writing a Druid extension which can provide an instance of SSLContext. Druid comes with a simple extension present here which should be useful enough for most simple cases, see this for how to include extensions. If this extension does not satisfy the requirements then please follow the extension implementation to create your own extension.

Upgrading Clients that interact with Overlord or Coordinator

When Druid Coordinator/Overlord have both HTTP and HTTPS enabled and Client sends request to non-leader node, then Client is always redirected to the HTTPS endpoint on leader node. So, Clients should be first upgraded to be able to handle redirect to HTTPS. Then Druid Overlord/Coordinator should be upgraded and configured to run both HTTP and HTTPS ports. Then Client configuration should be changed to refer to Druid Coordinator/Overlord via the HTTPS endpoint and then HTTP port on Druid Coordinator/Overlord should be disabled.

Custom TLS certificate checks

Druid supports custom certificate check extensions. Please refer to the org.apache.druid.server.security.TLSCertificateChecker interface for details on the methods to be implemented.

To use a custom TLS certificate checker, specify the following property:

Property	Description	Default	Required
druid.tls.certificateChecker	Type name of custom TLS certificate checker, provided by extensions. Please refer to extension documentation for the type name that should be specified.	"default"	no

The default checker delegates to the standard trust manager and performs no additional actions or checks.

If using a non-default certificate checker, please refer to the extension documentation for additional configuration properties needed.