Cluster Security

Every cluster node implements the special cluster user. Cluster communications are always carried on through this user, so any modifications to the permissions on the various nodes should not affect the communication between them.

For example, if you have a user called “Peter” on the master, who is able to access the “stone” repository, you do not need to configure “Peter” on every other node - communication will be carried out through the cluster user.

Cluster communications have an extra layer of security, beyond standard HTTPS encryption. This layer is always active, even if HTTPS has not been enabled. Communication within the cluster in GraphDB is signed with a special token.

Every request has a special header Authorization: GDB-Signature <token>. This signature is compared against a shared secret key configured on each node. The secret key needs to be the same on each node. The signature includes information about the request endpoint, operation, timestamp ± 1 min, and content type.

Communication between the nodes can only happen when the signature is validated. This prevents attackers from impersonating a node in the cluster.


Communication may also be prevented if the signature has already been used. This is meant to prevent replay attacks. Another instance when a request will not go through is when the clocks between the nodes are out of sync by 2 minutes or more.

The secret can be configured in one in three ways. If you run your cluster in a single GraphDB instance, you do not need to do anything, the cluster can run out of the box. If, however, you are using multiple GraphDB installations, the secret will have to be configured.

There are three ways to configure the secret. In order of precedence, those are:

  • A secret explicitly set via the graphdb.auth.token.secret configuration parameter.

  • A secret generated from the private key of the X509 certificate that is also used for HTTPS encryption (configured via the graphdb.connector.keyFile parameter). The same certificate needs to be used on all nodes for the cluster to function properly.

  • Fall back to a randomly generated secret key if none is configured.

We recommend the following steps for securing your cluster:

  • All masters should implement the same configuration and auth providers. This will guarantee that in the event of a failure automatic switching of the client will work.

  • All worker nodes connected to a master should implement the same configuration and auth providers. This simplifies the security management.

  • All workers must be secured even if they are not publicly accessible.

You can find more details in Deploying Secure GraphDB section.