App Suite middleware connects to an Apache Cassandra cluster through the CQL native transport. This article describes how that connection is configured, focusing on authentication and encryption.

Configuration

Middleware configuration is performed through properties with prefix com.openexchange.nosql.cassandra., see the property documentation for the complete list.

The essential setting is the list of seed nodes the middleware connects to on start-up; the remaining nodes of the cluster are discovered from there. More than one should be given so that a temporarily unavailable seed node does not delay start-up.

com.openexchange.nosql.cassandra.clusterContactPoints = cassandra-1,cassandra-2,cassandra-3
com.openexchange.nosql.cassandra.port = 9042

All settings are read once while the session is built. Changing any of them requires a restart; none of them is reloadable.

Authentication

A cluster running with PasswordAuthenticator instead of AllowAllAuthenticator needs credentials:

com.openexchange.nosql.cassandra.username = ox
com.openexchange.nosql.cassandra.password = secret

While the user name is empty - the default - no authentication is configured at all and the middleware connects anonymously, which is what an unauthenticated cluster expects. Setting the user name enables the driver's PlainTextAuthProvider. A different provider can be selected through com.openexchange.nosql.cassandra.authProviderClass; an unqualified name is resolved by the driver against its own com.datastax.oss.driver.internal.core.auth package.

Since the password ends up in a file below /opt/open-xchange/etc/ in plain text, it is readable by everything that can read the configuration tree. Deployments should render it into a secret rather than into a plain config map.

A rejected credential no longer fails bundle start. It is logged at ERROR and retried every 15 seconds, the same way an unreachable contact point is, so that a secret that has not been rolled out yet degrades the node instead of wedging it.

Note: JVM arguments of the form -Ddatastax-java-driver.advanced.auth-provider.* take precedence over these properties. This is deliberate - it lets a deployment that passes its credentials that way migrate to properties without a flag day - but a leftover argument of that kind silently wins. It is worth ruling out first if a configured credential appears to have no effect.

Encryption

com.openexchange.nosql.cassandra.ssl = true

Encrypts all connections to the cluster using TLS. The connection then follows the server's central SSL configuration: the trust material, the enabled protocols and the cipher suites all come from the properties with prefix com.openexchange.net.ssl., and the node's host name is matched against its certificate unless com.openexchange.net.ssl.hostname.verification.enabled is turned off. A certificate authority that is not known to the JVM therefore belongs into the central custom trust store (com.openexchange.net.ssl.custom.truststore.*), where it also serves every other outbound connection - there is no Cassandra-specific trust store.

A cluster that requires client certificates is the one part that is configured here, because it is specific to this connection:

com.openexchange.nosql.cassandra.sslKeystorePath = /opt/open-xchange/etc/cassandra-keystore.jks
com.openexchange.nosql.cassandra.sslKeystorePassword = secret