Configure mTLS authentication

Mutual TLS (mTLS) authentication uses certificate-based authentication for client and internode connections. After the SSL handshake, Hyper-Converged Database (HCD) extracts the identity from client certificates and grants access only to authorized users.

About identity in mTLS

You can define your own identity for certificates by extracting fields or information from the certificates. Implement the MutualTlsCertificateValidator interface to validate and extract identities from certificates. The MutualTlsAuthenticator and MutualTlsInternodeAuthenticator use these identities to customize for the certificate conventions in your deployment environment.

HCD includes a default implementation of MutualTlsCertificateValidator that uses SPIFFE as the certificate identity. SPIFFE must be present in the Subject Alternative Name (SAN) of the certificate.

If you prefer not to use the SPIFFE-based validator, configure a custom CN-based validator that implements MutualTlsCertificateValidator.

Configure mTLS for client connections

HCD supports two approaches for configuring mTLS authentication for client connections:

  • AdvancedAuthenticator (recommended): Supports multiple authentication schemes, allowing you to use mTLS alongside or instead of password-based, OIDC, or LDAP authentication.

  • MutualTlsAuthenticator: Provides certificate-only authentication compatible with open-source Cassandra.

Choose the approach that best fits your deployment requirements.

Configure mTLS with AdvancedAuthenticator

Use AdvancedAuthenticator to enable mTLS alongside other authentication schemes or as the sole authentication method. For more information about AdvancedAuthenticator, see About HCD Unified Authentication.

Prerequisites

The following steps use SPIFFE identity as an example. If you use a custom validator, replace spiffe://testdomain.com/testIdentifier/testValue with your appropriate identity format.

  1. Add authorized users to the system_auth.identity_to_role table.

    Client certificates with identities in this table are trusted by HCD. For more information about role management, see Roles.

    ADD IDENTITY 'spiffe://testdomain.com/testIdentifier/testValue' TO ROLE 'read_only_user'

  2. Locate the cassandra.yaml configuration file.

    The location of the cassandra.yaml file depends on your installation type.

    • Package installations: /etc/hcd/cassandra/cassandra.yaml

    • Tarball installations: INSTALLATION_LOCATION/resources/cassandra/conf/cassandra.yaml

  3. In the cassandra.yaml file, configure the client_encryption_options section:

    client_encryption_options:
  enabled: true
  optional: false
  keystore: conf/.keystore
  keystore_password: cassandra
  truststore: conf/.truststore
  truststore_password: cassandra
  require_client_auth: true

    For more information about client encryption options, see Configure SSL for client-to-node connections.

    enabled

    Enables client-to-node encryption. Set to true to enable mTLS.

    optional

    When set to false, only encrypted connections are allowed. Set to false for mTLS.

    keystore

    Path to the keystore file containing the node’s private key and certificate.

    keystore_password

    Password for the keystore.

    truststore

    Path to the truststore file containing trusted certificates.

    truststore_password

    Password for the truststore.

    require_client_auth

    Set to true to enable mTLS and require client certificate authentication.

  4. Configure the authenticator section with AdvancedAuthenticator and mTLS support:

    authenticator:
  class_name: com.datastax.cassandra.auth.AdvancedAuthenticator
  parameters:
    enabled: true
    default_scheme: internal
    additional_schemes: mtls
    mtls_class_name: org.apache.cassandra.auth.MutualTlsAuthenticator
    mtls_validator_class_name: org.apache.cassandra.auth.SpiffeCertificateValidator
    class_name

    The AdvancedAuthenticator class. Use com.datastax.cassandra.auth.AdvancedAuthenticator.

    enabled

    Set to true to enable authentication.

    default_scheme

    The default authentication scheme. Set to internal for password-based authentication, mtls for certificate-only authentication, oidc for OpenID Connect, or ldap for LDAP authentication.

    additional_schemes

    Comma-separated list of additional authentication schemes. Include mtls to enable mTLS authentication alongside other schemes such as internal, oidc, or ldap.

    mtls_class_name

    The mTLS authenticator class. Use org.apache.cassandra.auth.MutualTlsAuthenticator.

    mtls_validator_class_name

    The certificate validator class. Use org.apache.cassandra.auth.SpiffeCertificateValidator for SPIFFE-based validation, or specify your custom validator class.

  5. Save the cassandra.yaml file.

  6. Complete a rolling rolling restart.

After the restart, HCD accepts mTLS connections from clients. Access is granted only if the client’s identity is present in the identity_to_role table.

Configure mTLS with MutualTlsAuthenticator

Use MutualTlsAuthenticator for certificate-only authentication without additional authentication schemes.

Prerequisites

The following steps use SPIFFE identity as an example. If you use a custom validator, replace spiffe://testdomain.com/testIdentifier/testValue with your appropriate identity format.

  1. Add authorized users to the system_auth.identity_to_role table.

    Client certificates with identities in this table are trusted by HCD. For more information about role management, see Roles.

    ADD IDENTITY 'spiffe://testdomain.com/testIdentifier/testValue' TO ROLE 'read_only_user'

  2. Locate the cassandra.yaml configuration file.

    The location of the cassandra.yaml file depends on your installation type.

    • Package installations: /etc/hcd/cassandra/cassandra.yaml

    • Tarball installations: INSTALLATION_LOCATION/resources/cassandra/conf/cassandra.yaml

  3. In the cassandra.yaml file, configure the client_encryption_options section:

    client_encryption_options:
  enabled: true
  optional: false
  keystore: conf/.keystore
  keystore_password: cassandra
  truststore: conf/.truststore
  truststore_password: cassandra
  require_client_auth: true

    For more information about client encryption options, see Configure SSL for client-to-node connections.

    enabled

    Enables client-to-node encryption. Set to true to enable mTLS.

    optional

    When set to false, only SSL connections are allowed. Set to false for mTLS.

    keystore

    Path to the keystore file containing the node’s private key and certificate.

    keystore_password

    Password for the keystore.

    truststore

    Path to the truststore file containing trusted certificates.

    truststore_password

    Password for the truststore.

    require_client_auth

    Set to true to enable mTLS and require client certificate authentication.

  4. Configure the authenticator section with MutualTlsAuthenticator:

    authenticator:
  class_name: org.apache.cassandra.auth.MutualTlsAuthenticator
  parameters:
    validator_class_name: org.apache.cassandra.auth.SpiffeCertificateValidator
    class_name

    The mTLS authenticator class. Use org.apache.cassandra.auth.MutualTlsAuthenticator.

    validator_class_name

    The certificate validator class. Use org.apache.cassandra.auth.SpiffeCertificateValidator for SPIFFE-based validation, or specify your custom validator class.

  5. Save the cassandra.yaml file.

  6. Complete a rolling rolling restart.

After the restart, HCD accepts only mTLS connections from clients. Access is granted only if the client’s identity is present in the identity_to_role table.

Configure mTLS for internode connections

Secure node-to-node communication by requiring certificate-based authentication between cluster nodes. The internode authenticator trusts certificates based on the following criteria:

  • If trusted_peer_identities is configured, it trusts certificates whose identities are in that list.

  • If trusted_peer_identities is not configured, it trusts connections with the same identity as the node.

When a node makes an outbound connection to another node, it uses the certificate configured in server_encryption_options.outbound_keystore. During node startup, HCD extracts the identity from the outbound keystore. If trusted_peer_identities is not configured, connections from other nodes with the same identity are trusted.

For example, if a node has testIdentity embedded in the certificate in the outbound keystore, it trusts connections from other nodes when their certificates have testIdentity embedded in them.

Use the optional node_identity configuration to verify the identity extracted from the keystore and avoid configuration errors.

Configure server encryption options

  1. Locate the cassandra.yaml configuration file.

    The location of the cassandra.yaml file depends on your installation type.

    • Package installations: /etc/hcd/cassandra/cassandra.yaml

    • Tarball installations: INSTALLATION_LOCATION/resources/cassandra/conf/cassandra.yaml

  2. Configure the server_encryption_options section:

    server_encryption_options:
  internode_encryption: all
  optional: true
  keystore: conf/.keystore
  keystore_password: cassandra
  outbound_keystore: conf/.outbound_keystore
  outbound_keystore_password: cassandra
  require_client_auth: true
  truststore: conf/.truststore
  truststore_password: cassandra

    For more information about server encryption options, see Configure SSL for node-to-node connections.

    internode_encryption

    Set to all to encrypt all internode communication.

    optional

    Set to true during rolling upgrades to allow both mTLS and non-mTLS connections. Set to false after all nodes are upgraded to require mTLS.

    keystore

    The file path to the keystore file for inbound connections.

    keystore_password

    Password for the inbound keystore.

    outbound_keystore

    Path to the keystore file for outbound connections.

    outbound_keystore_password

    Password for the outbound keystore.

    require_client_auth

    Set to true to enable mTLS for internode connections.

    truststore

    The file path to the truststore file containing trusted certificates.

    truststore_password

    Password for the truststore.

Configure the internode authenticator

  1. In the cassandra.yaml file, configure the internode_authenticator section:

    internode_authenticator:
  class_name: org.apache.cassandra.auth.MutualTlsInternodeAuthenticator
  parameters:
    validator_class_name: org.apache.cassandra.auth.SpiffeCertificateValidator
    trusted_peer_identities: "spiffe1,spiffe2"
    node_identity: "spiffe1"
    class_name

    The mTLS internode authenticator class. Use org.apache.cassandra.auth.MutualTlsInternodeAuthenticator.

    validator_class_name

    The certificate validator class. Use org.apache.cassandra.auth.SpiffeCertificateValidator for SPIFFE-based validation, or specify your custom validator class.

    trusted_peer_identities

    Optional comma-separated list of trusted peer identities. If not specified, the node trusts connections with the same identity as itself.

    node_identity

    Optional identity to verify against the identity extracted from the outbound keystore. Use this parameter to catch configuration errors.

  2. Save and close the cassandra.yaml file.

Restart the cluster

Complete a rolling rolling restart.

After all nodes restart, all internode communications are authenticated by mTLS.

Migrate to mTLS authentication

You can migrate from password-based authentication to mTLS authentication without downtime.

Migrate client connections with AdvancedAuthenticator

Transition client connections to mTLS by adding mTLS as an additional authentication scheme.

  1. In the cassandra.yaml file, configure optional mode:

    client_encryption_options:
  enabled: true
  optional: true
  keystore: conf/.keystore
  keystore_password: cassandra
  truststore: conf/.truststore
  truststore_password: cassandra
  require_client_auth: true

  2. Add mTLS to the additional schemes:

    authenticator:
  class_name: com.datastax.cassandra.auth.AdvancedAuthenticator
  parameters:
    enabled: true
    default_scheme: internal
    additional_schemes: mtls
    mtls_class_name: org.apache.cassandra.auth.MutualTlsAuthenticator
    mtls_validator_class_name: org.apache.cassandra.auth.SpiffeCertificateValidator

  3. Complete a rolling rolling restart.

  4. After all clients migrate to mTLS, disable optional mode:

    client_encryption_options:
  enabled: true
  optional: false
  keystore: conf/.keystore
  keystore_password: cassandra
  truststore: conf/.truststore
  truststore_password: cassandra
  require_client_auth: true

  5. Change the default scheme to mTLS and remove other schemes:

    authenticator:
  class_name: com.datastax.cassandra.auth.AdvancedAuthenticator
  parameters:
    enabled: true
    default_scheme: mtls
    mtls_class_name: org.apache.cassandra.auth.MutualTlsAuthenticator
    mtls_validator_class_name: org.apache.cassandra.auth.SpiffeCertificateValidator

  6. Complete a rolling rolling restart.

After this final restart, HCD accepts only mTLS client connections.

Migrate internode connections

Transition internode connections to mTLS during a rolling upgrade.

  1. During the rolling upgrade, set server_encryption_options.optional to true:

    server_encryption_options:
  internode_encryption: all
  optional: true
  keystore: conf/.keystore
  keystore_password: cassandra
  outbound_keystore: conf/.outbound_keystore
  outbound_keystore_password: cassandra
  require_client_auth: true
  truststore: conf/.truststore
  truststore_password: cassandra

  2. After all nodes are upgraded, configure the internode authenticator:

    internode_authenticator:
  class_name: org.apache.cassandra.auth.MutualTlsInternodeAuthenticator
  parameters:
    validator_class_name: org.apache.cassandra.auth.SpiffeCertificateValidator

  3. Disable optional mode:

    server_encryption_options:
  internode_encryption: all
  optional: false
  keystore: conf/.keystore
  keystore_password: cassandra
  outbound_keystore: conf/.outbound_keystore
  outbound_keystore_password: cassandra
  require_client_auth: true
  truststore: conf/.truststore
  truststore_password: cassandra

  4. Complete a rolling rolling restart.

After this final restart, all internode communications use mTLS authentication.

See also

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM