Skip to main content

Secure Cassandra Access with SSO, TLS, and Auditing

Secure Cassandra access with SSO while keeping databases off the public internet, authenticating with short-lived client certificates, and recording every command in the audit log.

Setup takes four steps: create a join token, configure the Cassandra server, grant access through AlmaForge RBAC, and connect with native cqlsh.

info

Running ScyllaDB? See the ScyllaDB database access guide.

Prerequisites​

Cassandra CLI​

On your computer, check whether cqlsh is installed:

Terminal
cqlsh --versioncqlsh 6.2.0

If it is missing, install Homebrew's Cassandra package, which includes cqlsh and its Python dependencies:

Terminal
brew install cassandra...==> Summary...cqlsh --versioncqlsh 6.2.0

You only need the client on your computer. Do not start a local Cassandra service for this guide. For Linux, follow the Cassandra installation instructions.

Cassandra server​

On your computer, open a second terminal and SSH into the database server. Replace <ssh-user> and <database-host> with your SSH account and server address:

Terminal
ssh <ssh-user>@<database-host>...[<ssh-user>@<database-host> ~]$

On the database server, check that you can run administrator commands, then check the operating system and installed database package:

Terminal
sudo -v# No output on success. A password prompt may appear first.grep -E '^(ID_LIKE|VERSION_ID)=' /etc/os-releaseID_LIKE="rhel centos fedora"VERSION_ID="9.8"rpm -q cassandracassandra-5.0.9-1.noarch

sudo -v must succeed. If Cassandra is not installed, install the cassandra package from the Apache Cassandra repository before continuing. Otherwise, the command prints its version.

Use an RPM-based Linux host with dnf for this example.

AlmaForge CLI​

On your computer, check whether alma is installed:

Terminal
alma version --clientClient Version: v2026.1.0+<build>

If the command is not found, install it and repeat the check:

Terminal
curl -fL https://get.almaforge.com/install.sh | sh...==> AlmaForge installed successfullyalma version --clientClient Version: v2026.1.0+<build>

The installer supports Linux and macOS on both amd64 and arm64. See CLI installation for package-specific options.

AlmaForge Cluster​

On your computer, sign in to your cluster and check your permissions.

Get your cluster's hostname from its administrator. If you do not have an AlmaForge cluster yet, complete the standalone deployment before continuing. Replace almaforge.example.com below with that hostname. Run the login command and complete the sign-in in your browser:

Terminal
alma login --proxy=almaforge.example.com:443
text
...
> Profile URL:        https://almaforge.example.com:443
  Logged in as:       [email protected]
  Cluster:            almaforge.example.com
  Roles:              admin
  ...

After signing in, check your account and roles:

Terminal
alma status
text
> Profile URL:        https://almaforge.example.com:443
  Logged in as:       [email protected]
  Cluster:            almaforge.example.com
  Roles:              admin
  ...

In the status output, check that:

  • Cluster names the cluster you intend to configure.
  • Logged in as shows your account.
  • Roles includes admin.

If admin is missing, ask a cluster administrator to grant that role, then run alma logout and repeat the login and status commands. Continue once Roles includes admin.

Step 1. Create AlmaForge join token​

On your computer, create an AlmaForge join token. The database agent uses it to join your AlmaForge cluster:

Terminal
alma create token --services=databaseToken created.  client_id:     <client-id>  client_secret: <client-secret>

You will copy client_id and client_secret into the agent configuration in Step 2. They are valid for 30 minutes. If they expire before the agent joins, create a new token and use its values.

Step 2. Configure the Cassandra server​

Install and configure the agent​

The agent is almad with its Database Service enabled. It connects outward to your cluster on port 443 and carries connections between users and Cassandra.

On the Cassandra server, check whether almad is installed:

Terminal
almad versionAlmaForge v2026.1.0+<build>

If the command is not found, install the AlmaForge package:

Terminal
curl -fL https://get.almaforge.com/install.sh | sh...==> AlmaForge installed successfullyalmad versionAlmaForge v2026.1.0+<build>

On an RPM-based system, the installer uses the RPM package and installs the almad systemd service. It supports both amd64 and arm64. The version command must succeed before you configure the agent. For other Linux distributions, see Linux package installation.

Already running an agent on this host?

Open its existing environment file with sudoedit /etc/almaforge/almad.env and preserve its other settings. Set ALMA_DATABASE_SERVICE=true in that file. Preserve any existing label selectors. Step 2 adds Cassandra through a local target file, which does not need a selector. The agent's join credentials must permit the database service.

Terminal
sudoedit /etc/almaforge/almad.env# Your text editor opens.

For a new agent, enter the settings below. Replace ALMA_PROXY with your cluster's hostname and port 443. Set ALMA_CLIENT_ID and ALMA_CLIENT_SECRET to the values from Step 1:

almad.env:

/etc/almaforge/almad.env
# Database Service agent on the Cassandra host.
# Install at /etc/almaforge/almad.env as root:root with mode 0600.
ALMA_PROXY=almaforge.example.com:443

# Printed by `alma create token --services=database`.
ALMA_CLIENT_ID=paste-client-id-here
ALMA_CLIENT_SECRET=paste-client-secret-here

ALMA_DATABASE_SERVICE=true
ALMA_SSH_SERVICE=false

# Agent labels, separate from the database's labels.
ALMA_LABELS=env=demo

Save the file and close the editor. Restrict it to root because it contains the join credentials:

Terminal
sudo chown root:root /etc/almaforge/almad.env# No output on success.sudo chmod 0600 /etc/almaforge/almad.env# No output on success.

Create the TLS certificates​

The agent and Cassandra run on the same server. Their connection uses the loopback interface (localhost, or 127.0.0.1), so this traffic stays on that server. A self-signed certificate for localhost is sufficient. You do not need a public hostname or a certificate from a public CA.

Cassandra uses the AlmaForge database CA to verify client certificates presented by the agent. The files below establish mutual TLS between the agent and Cassandra.

Keep running these commands on the Cassandra server.

Download your cluster's public database CA. Replace almaforge.example.com with your cluster's hostname:

Terminal
curl -fsS -o almaforge-db-ca.pem 'https://almaforge.example.com:443/api/v1/auth/export?type=db'# No output on success.openssl x509 -in almaforge-db-ca.pem -noout# No output means the file contains a valid certificate.

Create a self-signed server certificate and private key for localhost, then combine them into server.pem for Cassandra:

Terminal
sudo openssl req -x509 -newkey rsa:2048 -nodes -days 3650 \    -subj '/CN=localhost' \    -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1' \    -keyout /etc/cassandra/conf/server.key -out /etc/cassandra/conf/server.crt...-----sudo sh -c 'cat /etc/cassandra/conf/server.key /etc/cassandra/conf/server.crt > /etc/cassandra/conf/server.pem'sudo chown cassandra:cassandra /etc/cassandra/conf/server.*# No output on success.sudo chmod 0600 /etc/cassandra/conf/server.key /etc/cassandra/conf/server.pem# No output on success.

Combine the AlmaForge database CA and the server certificate into the client trust bundle. This also permits the local administrative cqlsh connection to present the self-signed certificate:

Terminal
sudo sh -c 'cat almaforge-db-ca.pem /etc/cassandra/conf/server.crt > /etc/cassandra/conf/clients.pem'sudo chown cassandra:cassandra /etc/cassandra/conf/clients.pemsudo chmod 0644 /etc/cassandra/conf/clients.pem# No output on success.

Enable TLS in Cassandra​

Open /etc/cassandra/conf/cassandra.yaml on the server:

Terminal
sudoedit /etc/cassandra/conf/cassandra.yaml# Your text editor opens.

Configure client_encryption_options for PEM-based mutual TLS. Keep your existing cluster settings and data directories:

cassandra-tls.yaml:

/etc/cassandra/conf/cassandra.yaml
# Require TLS client certificates on Cassandra.
# Merge into /etc/cassandra/conf/cassandra.yaml and restart Cassandra.
authenticator: AllowAllAuthenticator
authorizer: AllowAllAuthorizer
client_encryption_options:
  enabled: true
  optional: false
  require_client_auth: true
  ssl_context_factory:
    class_name: org.apache.cassandra.security.PEMBasedSslContextFactory
  keystore: /etc/cassandra/conf/server.pem
  truststore: /etc/cassandra/conf/clients.pem

Save the file, close the editor, and restart Cassandra:

Terminal
sudo systemctl restart cassandra# No output on success.systemctl is-active cassandraactive

Create the keyspace and sample data​

Configure cqlsh with the local certificates and create the sample keyspace, table, and rows:

cqlshrc.ini:

/etc/cassandra/conf/cqlshrc
# Connect a local cqlsh administrator session over mutual TLS.
[connection]
hostname = 127.0.0.1
port = 9042
ssl = true

[ssl]
certfile = /etc/cassandra/conf/server.crt
validate = true
userkey = /etc/cassandra/conf/server.key
usercert = /etc/cassandra/conf/server.crt
Terminal
sudo cqlsh --cqlshrc /etc/cassandra/conf/cqlshrc <<'EOF'CREATE KEYSPACE IF NOT EXISTS demo WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};CREATE TABLE IF NOT EXISTS demo.demo (id int PRIMARY KEY, name text);INSERT INTO demo.demo (id, name) VALUES (1, 'alice');INSERT INTO demo.demo (id, name) VALUES (2, 'bob');INSERT INTO demo.demo (id, name) VALUES (3, 'carol');EOF

Register Cassandra with the agent​

Still on the Cassandra server, display the public server certificate:

Terminal
sudo cat /etc/cassandra/conf/server.crt-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

Copy the entire certificate, including the BEGIN and END lines. The agent uses it to verify Cassandra. Then open the target configuration:

Terminal
sudo install -d -o root -g root -m 0700 /etc/almaforge/almad.d# No output on success.sudoedit /etc/almaforge/almad.d/cassandra.yaml# Your text editor opens.

For a new file, copy the following YAML. If the file already exists, update the existing resource and preserve its other settings. Replace <paste the complete server certificate here> with the certificate you copied. Indent every certificate line by six spaces beneath caCert: |:

target.yaml.in:

/etc/almaforge/almad.d/cassandra.yaml
# Connect the local Cassandra instance through AlmaForge.
# Replace the placeholder with the contents of /etc/cassandra/conf/server.crt.
apiVersion: almaforge.com/v1
kind: DatabaseTarget
metadata:
  name: cassandra
  labels:
    db: cassandra
    env: prod
spec:
  protocol: cassandra
  uri: 127.0.0.1:9042
  tls:
    caCert: |
      <paste the complete server certificate here>

Check that the certificate includes both its BEGIN and END lines, then save the file and close the editor. Restrict the file to root:

Terminal
sudo chown root:root /etc/almaforge/almad.d/cassandra.yaml# No output on success.sudo chmod 0600 /etc/almaforge/almad.d/cassandra.yaml# No output on success.

Start and check the agent​

Enable the services at boot and start the agent:

Terminal
sudo systemctl enable cassandra almad...sudo systemctl restart almad# No output on success.systemctl is-active cassandra almadactiveactive

Both services must report active. If either fails, inspect its log:

Terminal
sudo journalctl -u cassandra -u almad -n 50 --no-pager...<date> <time> <database-host> almad[<pid>]: <log-message>...

Resolve any reported errors before continuing. The agent reads the target configuration at startup, so restart almad after changing /etc/almaforge/almad.d/cassandra.yaml.

Step 3. Grant access​

On your computer, confirm that the agent has registered the database:

Terminal
alma get dbHost             Name            Protocol       URI                 Labels             Version---------------- --------------- -------------- ------------------- ------------------ --------<database-host>  cassandra       cassandra      <database-uri>      db=cassandra ... 2026.1.0

Check that cassandra appears with protocol cassandra and your database server in the Host column. If either is missing, see Database is missing or has no host.

Download cassandra-access.yaml and save it locally. This role allows the demo session user on targets labeled db: cassandra. The username identifies the connection in AlmaForge. Cassandra's configuration in this example grants all accepted connections full access, regardless of that name.

examples/databases/cassandra/roles/cassandra-access.yaml
# Allow access to the dedicated Cassandra target.
# The sample Cassandra configuration grants accepted connections full access.
apiVersion: almaforge.com/v1
kind: Role
metadata:
  name: cassandra-access
spec:
  allow:
    databaseLabels:
      db: cassandra
    databaseUsers:
      - demo

Apply the role:

Terminal
alma apply -f cassandra-access.yamlrole 'cassandra-access' has been created

Creating the role does not assign it to anyone. To grant it to an SSO group, list your connectors:

Terminal
alma get oidcKind          Name------------- -----------OIDCConnector company-sso

Find the connector your team uses to sign in. Replace <connector-name> with its name from the output, then open it in your text editor:

Terminal
alma edit oidc/<connector-name># Your text editor opens. After saving your changes:oidc connector "<connector-name>" has been updated

Under spec.claimsToRoles, find the entry for the group that should have Cassandra access. Add cassandra-access to that entry's roles list. Preserve the existing roles and mappings, including those that grant admin, then save and close the editor. The command applies your changes. If the group has no mapping yet, follow OIDC role mapping to add one.

Step 4. Connect​

On your computer, sign out of saved sessions, then sign back in with an account in the group granted access in Step 3 to get a session with the new role. logout clears saved sessions for all clusters. Use your cluster's hostname in the login command:

Terminal
alma logoutLogged out all users from all proxies.alma login --proxy=almaforge.example.com:443...> Profile URL:        https://almaforge.example.com:443  Logged in as:       [email protected]  Cluster:            almaforge.example.com  Roles:              cassandra-access  ...alma status> Profile URL:        https://almaforge.example.com:443  Logged in as:       [email protected]  Cluster:            almaforge.example.com  Roles:              cassandra-access  ...

Check that Roles includes cassandra-access. If it is missing, check your SSO group membership and the mapping from Step 3 before continuing.

Connect to the sample data:

Terminal
alma db connect --db-user=demo cassandraPassword:...demo@cqlsh> SELECT * FROM demo.demo;
 id | name----+-------  1 | alice  2 |   bob  3 | carol
(3 rows)

Enter any value at Password: and press Enter. This setup authenticates the client certificate and does not check the password. The three rows confirm access to the sample table. Their order may differ. Type exit to leave cqlsh.

Advanced configuration​

GUI clients and scripts​

Leave this command running while your client uses the connection:

Terminal
alma proxy db --tunnel --db-user=demo cassandraStarted authenticated tunnel for the Cassandra database "cassandra" in cluster "almaforge.example.com" on 127.0.0.1:54321....

Use the printed local address and port in your client. Disable TLS for this local connection. With this example's configuration, leave database authentication disabled. If your client requires a username and password, use demo and any password. The tunnel authenticates you to AlmaForge, and the agent presents a client certificate to Cassandra.

Architecture​

The database agent runs beside Cassandra and opens an outbound tunnel to the AlmaForge Proxy. Cassandra listens on localhost and trusts the agent's client certificates.

Cassandra database access topology

Troubleshooting​

Database is missing or has no host​

On the database server, check that /etc/almaforge/almad.d/cassandra.yaml exists and ALMA_DATABASE_SERVICE=true is set in /etc/almaforge/almad.env. The agent must reach your cluster on port 443. Inspect its log:

Terminal
sudo journalctl -u almad -n 50 --no-pager...<date> <time> <database-host> almad[<pid>]: <log-message>...

Restart almad after correcting its configuration, then repeat alma get db on your computer.

Access is denied​

Run alma status and check for cassandra-access. If it is missing, verify the SSO group mapping from Step 3, then sign out and back in. The role's database labels must match the target file.

Password prompt​

The password prompt comes from cqlsh. With this example's AllowAllAuthenticator, any value works. An existing Cassandra cluster using password authentication requires the selected account's password.

Cassandra service is missing​

Confirm that cassandra is installed and running:

Terminal
systemctl status cassandra

cqlsh cannot find its Python library on the server​

The Cassandra RPM installs its library under Python's site-packages path. If cqlsh fails to start on the server, set PYTHONPATH:

Terminal
sudo env PYTHONPATH=/usr/lib/python3.6/site-packages cqlsh --versioncqlsh 6.2.0

Limitations​

  • In this release, AlmaForge does not provision Cassandra or ScyllaDB users. For a server using PasswordAuthenticator, create the account first and enter its password when connecting. The username must match --db-user.
  • The role's databaseNames does not restrict keyspaces or tables. To grant different database permissions to different accounts, configure Cassandra's PasswordAuthenticator and CassandraAuthorizer, then assign native grants. This sample's AllowAllAuthorizer grants full access.
  • Cassandra and ScyllaDB use the same AlmaForge protocol and role fields, but require their own server configuration. See the ScyllaDB access guide for ScyllaDB.

References​