Configure Database and Index Authentication#

In this tutorial, we're going to secure your TheHive installation by configuring authentication for both Cassandra and Elasticsearch. By the end, you'll have password-protected access to your database and index backends.

Maintenance window required

This procedure involves changing configuration files and restarting services. Schedule a maintenance window to prevent service disruption.

Configure authentication for Cassandra#

Step 1: Stop your services#

First, we need to stop your running services in the following order to avoid data corruption:

Stop TheHive service
Stop Cassandra service

Service commands

For stop/restart commands depending on your installation method, refer back to the relevant installation guide.

Step 2: Update Cassandra configuration#

Now we'll modify Cassandra configuration to require authentication.

Locate the cassandra.yaml file.
Open the cassandra.yaml file using a text editor.
In the cassandra.yaml file, enable authentication.

Set the following parameters with these exact values:
```
authenticator: PasswordAuthenticator
authorizer: CassandraAuthorizer 
```
Save your modifications in the cassandra.yaml file.
Restart Cassandra service.

Step 3: Set a secure password for authentication#

By default, Cassandra uses the cassandra username and the password cassandra. For security reasons, especially in production environments, you must change this password immediately after setup.

To do this, we'll use CQL, the Cassandra Query Language, which is similar in purpose to SQL.

Connect to Cassandra using default credentials.
```
cqlsh -u cassandra -p cassandra
```
Cqlsh may not be available on RPM-based systems

On some RPM-based distributions, the cqlsh client isn't included with the cassandra package. If running cqlsh gives an error, download the official Apache Cassandra tarball that matches your server version and extract it. Then run the bundled client: ./bin/cqlsh -u cassandra -p cassandra.

If the connection is successful, you'll see output similar to:
```
Connected to xxx at xx.xx.xx.xx:xxxx
[cqlsh 6.1.0 | Cassandra 4.1.9 | CQL spec 3.4.6 | Native protocol v5]
```
Change the default password.
```
ALTER USER cassandra WITH PASSWORD '<authentication_cassandra_password>';
```
Replace <authentication_cassandra_password> with the password you intend to use for the cassandra superuser account.
Disconnect from the session.

Press Ctrl+D to exit the cqlsh shell.
Reconnect using your new password.
```
cqlsh -u cassandra
```

Step 4: Create a new administrator role for authentication#

To avoid relying on the default cassandra superuser account, create a new administrator role and then delete the default user.

Create the admin role.
```
CREATE ROLE admin WITH PASSWORD = '<authentication_admin_password>' AND LOGIN = true AND SUPERUSER = true;
```
Replace <authentication_admin_password> with the password you intend to use for the admin superuser account.
Disconnect from the session.

Press Ctrl+D to exit the cqlsh shell.
Reconnect as the new admin.
```
cqlsh -u admin
```
Remove the default cassandra user.
```
DROP ROLE cassandra;
```

Step 5: Create a role for TheHive#

Let's create a dedicated role that TheHive will use to connect to Cassandra.

Create a dedicated role for TheHive.
```
CREATE ROLE thehive WITH LOGIN = true AND PASSWORD = '<thehive_role_password>';
```
Replace <thehive_role_password> with the password you intend to use for the thehive role.

Note this password

Keep this password secure. You will need to enter it later in TheHive configuration file so the application can connect to the Cassandra database.

Grant access to the keyspace.

GRANT ALL PERMISSIONS ON KEYSPACE thehive TO 'thehive';

Step 6: Update TheHive configuration#

Now we'll configure TheHive to use the credentials we just created.

Open the application.conf file using a text editor.

In the application.conf file, update the database configuration.

Example of database configuration with authentication

[..]
# Database and index configuration
db.janusgraph {
    storage {
        [..]
        # Cassandra authentication
        username = "thehive"
        password = "<thehive_role_password>"
        cql {
            keyspace = thehive
        }
    }
    index.search {
        [..]
    }
}
[..]

Replace <thehive_role_password> with the password set in Step 5.

To set up SSL for Cassandra connections, see Configure Database and Index SSL.

For additional connection parameters and advanced options, see TheHive Database and Index Connection Settings.

Save your modifications in the application.conf file.
Restart TheHive service.

At this point, your Cassandra database is secured with authentication.

Configure authentication for Elasticsearch#

Step 1: Stop services#

First, we need to stop your running services in the following order to avoid data corruption:

Stop TheHive service
Stop Elasticsearch service

Step 2: Update Elasticsearch configuration#

Now we'll modify Elasticsearch configuration to require authentication.

Open the /etc/elasticsearch/elasticsearch.yml file using a text editor.
In the elasticsearch.yml file, add the desired security parameters from the official Elasticsearch security settings documentation.

At minimum add the following line (or edit it if it already exists):
```
xpack.security.enabled: true
```
Restart Elasticsearch service.

Step 3: Set a user with the right permissions for TheHive#

Create a thehive user.
```
sudo /usr/share/elasticsearch/bin/elasticsearch-users useradd thehive -p <thehive_user_password> -r superuser
```
Replace <thehive_user_password> with a secure password you choose for your TheHive user.

Note this password

Keep this password secure. You will need to enter it later in TheHive configuration file so the application can connect to Elasticsearch.

Optional: Set a password for the elastic user.

For Elasticsearch 7.x:

sudo /usr/share/elasticsearch/bin/elasticsearch-setup-passwords interactive

For Elasticsearch 8.0:

sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password

Skip this step if the password is already set.

Create or update a role with the privileges needed for TheHive.

Create a role:

curl -u elastic:<elastic_user_password> -X POST "http://localhost:9200/_security/role/thehive_role" -H "Content-Type: application/json" -d '
{
  "cluster": ["manage"],
  "indices": [
    {
      "names": ["thehive*"],
      "privileges": ["all"]
    }
  ]
}'

Replace <elastic_user_password> with the password you set for the elastic user.

If successful, the command should return: {"role":{"created":true}}.

For more details, refer to the official Elasticsearch API documentation for role creation.

Update a role:

curl -u elastic:<elastic_user_password> -X PUT "http://localhost:9200/_security/role/<role>" -H "Content-Type: application/json" -d '
{
  "cluster": ["manage"],
  "indices": [
    {
      "names": ["thehive*"],
      "privileges": ["all"]
    }
  ]
}'

Replace <role> with the actual role name you want to update.

Replace <elastic_user_password> with the password you set for the elastic user.

For more details, refer to the official Elasticsearch API documentation for updating roles.

Assign the role to the user you'll use for TheHive.
```
curl -u elastic:<elastic_user_password> -X PUT "http://localhost:9200/_security/user/thehive" \
-H "Content-Type: application/json" \
-d '{
    "password" : "<thehive_user_password>",
    "roles" : ["thehive_role"]
}'
```
Replace <thehive_user_password> with the password you set for the thehive user.

Replace <elastic_user_password> with the password you set for the elastic user.

Replace thehive_role with actual role name if different.

If successful, the command should return: {"created":true}.

For more details, refer to the official Elasticsearch API documentation for updating users.

Step 4: Update TheHive configuration#

Now we'll configure TheHive to use the credentials we just created.

Open the application.conf file using a text editor.

In the application.conf file, update the index configuration.

Example of index configuration with authentication

[..]
# Database and index configuration
db.janusgraph {
    storage {
        [..]
    }
    index.search {
        [..]
        # Elasticsearch authentication
        elasticsearch {
            http {
                auth {
                    type = basic
                    basic {
                        username = "thehive"
                        password = "<thehive_user_password>"
                    }
                }
            }
        }
    }
}
[..]

Replace <thehive_user_password> with the password set in Step 3.

To set up SSL for Elasticsearch connections, see Configure Database and Index SSL.

For additional connection parameters and advanced options, see TheHive Database and Index Connection Settings.

Save your modifications in the application.conf file.
Restart TheHive service.

At this point, Elasticsearch is secured and requires valid credentials for access.

Next steps

Configure Database and Index SSL