Deploying Secured GraphDB

There are four topologies for deploying a secure GraphDB instance.

  1. Topology one is a single cluster in a trusted network.


    Here the masters are exposed to the world, but the workers are protected inside a trusted network, such as a company intranet. In this situation there is no need to encrypt the communication between the different workers.

  2. Topology two differs from the first one by the fact that the nodes are located in a non-trusted network, such as a cloud provider’s servers.


    In this situation, encryption on the communication between the masters and the workers is necessary to guarantee a secure environment.

  3. Topology three is a variation on the previous topologies, but with multiple independent masters.


    The best practice in this situation is exactly the same as in the previous two - if operating in a trusted network, you can leave communications between the master and the workers unencrypted, and if operating in a non-trusted network, you should encrypt your connections to guarantee the security of your cluster.

  4. The final topology is a single-worker installation.


    It is recommended that the client-server communications are always encrypted. If the instance is hosting several nodes in a cluster configuration, this is equivalent to topology two, with the only difference being the GraphDB properties file that is one and the same for all masters and workers.

Configuring GraphDB instance with SSL

SSL can be enabled by configuring the following three parameters:

graphdb.connector.SSLEnabled = true
graphdb.connector.scheme = https = true

GraphDB uses the Java implementation of SSL, which requires a configured key in the Java keystore.

graphdb.connector.keystoreFile = <path to the keystore file>
graphdb.connector.keystorePass = <secret>
graphdb.connector.keyAlias = graphdb
graphdb.connector.keyPass = <secret>

If you have no Java keystore, you can generate one by using one of the following methods:

Option one - generate a self-signed key. You would have to trust the certificate in all clients, including all nodes that run in a different JVM.

$ keytool -genkey -alias graphdb -keyalg RSA -keystore \path\to\my\keystore

Option two - convert a third party trusted OpenSSL certificate to PKCS12 key and then import to the Java keystore.

openssl pkcs12 -export -in mycert.crt -inkey mykey.key
               -out mycert.p12 -name tomcat -CAfile myCA.crt
               -caname root -chain

For any additional encryption information, please refer to Encryption section or, since GraphDB runs in an embedded Tomcat, to the Tomcat ssl documentation.

In addition to the above settings, you can set any Tomcat Connector attribute through a property:

graphdb.connector.<attribute> = xxx

Currently, GraphDB does not support configuration of the SSLHostConfig part of the Tomcat configuration. So when configuring SSL, please refer to the Connector attributes and not the SSLHostConfig ones. See the Tomcat attributes documentation for more information.

Securing GraphDB cluster

To secure your cluster, first ensure that security is enabled for all GraphDB instances by using one of the following methods:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: */*' -d 'true' 'http://localhost:7200/rest/security'
  • Edit the settings.js file that contains the settings of the instance located under the GraphDB work directory, in the Workbench folder.

security.enabled = true


We recommend the manual and REST API methods.

Then, for all GraphDB instances, input a shared secret by passing it as a configuration parameter.

graphdb.auth.token.secret = <my-shared-secret-key>

In order for the cluster nodes to communicate, all nodes should be configured to use the same shared key.

In case a shared secret is not explicitly specified, GraphDB will try to obtain one automatically from the X509 security certificate configured by the property.

graphdb.connector.keystoreFile = <path to the keystore file>

Effectively, this means that if all nodes in the cluster are using a shared certificate, they will automatically obtain a correct shared secret as well. However, if the nodes are using different certificates, you would still have to manually set a shared token secret.

Once you have configured this, you can proceed to create your cluster as usual. If you want to configure your entire security in one go, create all the repositories that you will need at this stage. Note that you do not need to input any data yet, you only need the created repositories.

When you have created your cluster, you can enable users and configure their access levels on the master node. Both operations are exactly identical to user management for a single instance. You do not need to configure users on nodes that you do not intend to access directly (i.e., the worker nodes), since all communication between the cluster nodes happens under an internal cluster user that impersonates the permissions available to the user currently accessing the master.

Automatic authentication setup for the Cluster manager

You can use the Cluster manager in the Workbench to setup a cluster by dragging and dropping nodes. In order to keep this a breeze, we provide automatic retrieval and setting of authentication tokens when users connect two nodes. It is always safe to do this, regardless of whether security is enabled at the time of the node connecting.