Skip to main content

Secure ScyllaDB Access with SSO, TLS, and Auditing

Secure ScyllaDB 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 ScyllaDB server, grant access through AlmaForge RBAC, and connect with native cqlsh.

info

Running Cassandra? See the Cassandra database access guide.

Prerequisites​

ScyllaDB 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

For Linux, install cqlsh from your package manager or Python's package index:

Terminal
pip install cqlsh...cqlsh --versioncqlsh 6.2.0

ScyllaDB server​

On the database server, check that the ScyllaDB service is active:

Terminal
systemctl is-active scylla-serveractive

Use your package's service name if it differs. You need sudo and root permissions on the database server to configure TLS and register the target.

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:

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.

AlmaForge Cluster​

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

Terminal
alma login --proxy=almaforge.example.com:443alma status

In the status output, confirm that:

  • Cluster names the cluster you intend to configure.
  • Logged in as shows your account.
  • 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>

Copy client_id and client_secret into the agent configuration in Step 2. They are valid for 30 minutes.

Step 2. Configure the ScyllaDB server​

Install and configure the agent​

The agent is almad with its Database Service enabled.

On the ScyllaDB server, install almad if missing:

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

Open the agent configuration:

Terminal
sudoedit /etc/almaforge/almad.env

almad.env:

/etc/almaforge/almad.env
# Database Service agent on the ScyllaDB 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 restrict permissions:

Terminal
sudo chown root:root /etc/almaforge/almad.envsudo chmod 0600 /etc/almaforge/almad.env

Configure ScyllaDB for client certificate TLS​

ScyllaDB accepts standard PEM format certificates. Download the AlmaForge database CA and place the server certificate files in /etc/scylla/:

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.sudo install -d -o scylla -g scylla -m 0700 /etc/scyllasudo install -o scylla -g scylla -m 0644 almaforge-db-ca.pem /etc/scylla/server.cassudo openssl req -x509 -newkey rsa:2048 -nodes -days 3650 \    -subj '/CN=localhost' \    -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1' \    -keyout /etc/scylla/server.key -out /etc/scylla/server.crtsudo chown scylla:scylla /etc/scylla/server.key /etc/scylla/server.crtsudo chmod 0600 /etc/scylla/server.key

Merge the TLS client encryption options into /etc/scylla/scylla.yaml:

scylla-tls.yaml:

/etc/scylla/scylla.yaml
# Require TLS client certificates on ScyllaDB.
# Merge this configuration into /etc/scylla/scylla.yaml and restart ScyllaDB.
authenticator: AllowAllAuthenticator
authorizer: AllowAllAuthorizer
client_encryption_options:
  enabled: true
  certificate: /etc/scylla/server.crt
  keyfile: /etc/scylla/server.key
  truststore: /etc/scylla/server.cas
  require_client_auth: true

Restart ScyllaDB:

Terminal
sudo systemctl restart scylla-serversystemctl is-active scylla-serveractive

Register ScyllaDB with the agent​

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

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

Copy the entire certificate, including the BEGIN and END lines. The agent uses it to verify ScyllaDB. 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/scylladb.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/scylladb.yaml
# Connect the local ScyllaDB instance through AlmaForge.
# Replace the placeholder with the contents of /etc/scylla/server.crt.
apiVersion: almaforge.com/v1
kind: DatabaseTarget
metadata:
  name: scylladb
  labels:
    db: scylladb
    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/scylladb.yaml# No output on success.sudo chmod 0600 /etc/almaforge/almad.d/scylladb.yaml# No output on success.

Start and check the agent​

Enable the services at boot and start the agent:

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

Step 3. Grant access​

On your computer, confirm the database is registered:

Terminal
alma get dbHost             Name            Protocol       URI                 Labels             Version---------------- --------------- -------------- ------------------- ------------------ --------<database-host>  scylladb        cassandra      127.0.0.1:9042      db=scylladb ...    2026.1.0

Download and apply the access role:

scylladb-access.yaml:

scylladb-access.yaml
# Access to the ScyllaDB target.
apiVersion: almaforge.com/v1
kind: Role
metadata:
  name: scylladb-access
spec:
  allow:
    databaseLabels:
      db: scylladb
    databaseUsers:
      - demo

Apply it:

Terminal
alma apply -f scylladb-access.yamlrole 'scylladb-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 ScyllaDB access. Add scylladb-access to that entry's roles list. Preserve the existing roles and mappings, then save and close the editor.

Step 4. Connect​

On your computer, refresh your credentials:

Terminal
alma logoutalma login --proxy=almaforge.example.com:443alma status

Confirm Roles includes scylladb-access. Then connect with alma db connect:

Terminal
alma db connect --db-user=demo scylladbConnected to scylladb at 127.0.0.1:9042.[cqlsh 6.2.0 | Cassandra 4.0.0 | CQL spec 3.4.5 | Native protocol v4]Use HELP for help.demo@cqlsh> DESCRIBE KEYSPACES;

Type exit to disconnect.

Advanced configuration​

GUI clients and scripts​

Open an authenticated tunnel for GUI clients or scripts:

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

Connect your client to 127.0.0.1:54321 over plain TCP. The tunnel authenticates to AlmaForge, and the agent presents the user certificate to ScyllaDB.

Architecture​

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

ScyllaDB database access topology

Troubleshooting​

Database is missing or has no host​

Check /etc/almaforge/almad.d/scylladb.yaml and ALMA_DATABASE_SERVICE=true in /etc/almaforge/almad.env on the database server. Inspect the agent log:

Terminal
sudo journalctl -u almad -n 50 --no-pager

Access is denied​

Run alma status and verify scylladb-access appears in your roles. Ensure the role's databaseLabels match the target labels.

Limitations​

  • AlmaForge proxies the Cassandra wire protocol to ScyllaDB over native port 9042.
  • Mutual TLS requires valid certificates signed by the AlmaForge database CA.

References​