Configuring remote database aliases

A remote database alias can be used to provide connection to one or more graphs, on one or more remote standalone servers or clusters.

Although remote database aliases do not store any data, they enable users or applications to perform queries on remote databases as if they were on the local DBMS server. All configurations can be done using administrative commands on a running system. Any changes are automatically synchronized across all instances of a cluster.

The following steps describe the setup required to define a remote database alias both for local and remote DBMSs. They are also useful should there be any changes in the name of the databases or the location of standalone servers and cluster instances. Additionally, you will also find information here on best practices and additional guidance on any changes in the configuration.

Setup example

In this example, Alice is an administrator and Carol is a user who needs access to a database managed by Bob:

remote alias overview
Figure 1. Overview of the required remote database alias setup

A remote alias defines:

  • Which user of the remote DBMS B is used.

  • Where the remote database is located.

  • How to connect to the remote database using driver settings.

A remote database alias is only accessible to users with appropriate privileges. In the example above, Bob is the administrator responsible for deciding which databases (Db1 or Db2) the remote aliases can write and/or read. Meanwhile, Alice is the administrator that assigns who has access to the privileges set by Bob. In the example, Alice will assign that access to Carol.

See lDBMS privileges for more information.

Carol can use her own regular credentials to access the remote database Db1 in DBMS after Alice assigns this privilege to her user profile. This configuration will also allow Carol to access Db2 in DBMS B. If the administrators decide this should not be the case, then Bob must define the appropriate privileges (see Authentication and authorization for further information).

Configure a remote DBMS (Bob)

In the suggested example, there are two administrators: Alice and Bob. Bob is the administrator responsible for the setup of the remote DBMS, which includes the following steps:

  1. Create the user profile to share with Alice. Currently, only user and password-based authentication (e.g. native authentication) are supported.

  2. Define the permissions for the user. If you don’t want this user to access Db2, here is where you set it.

  3. Securely transmit the credentials to Alice, setting up the link to database Db1. It is recommended to create a custom role to track all users shared on a remote connection, so that they remain trackable.

CREATE USER alice SET PASSWORD 'secretpassword'
CREATE ROLE remote
GRANT ACCESS ON DATABASE neo4j TO remote
GRANT MATCH {*} ON GRAPH neo4j TO remote
GRANT ROLE remote TO alice

In this case, Bob must do the required setup for the SSL framework and check whether the database accepts a non-local connection if required.

# accept non-local connections
server.default_listen_address=0.0.0.0

# configure ssl for bolt
dbms.ssl.policy.bolt.enabled=true
dbms.ssl.policy.bolt.base_directory=certificates/bolt
dbms.ssl.policy.bolt.private_key=private.key
dbms.ssl.policy.bolt.public_certificate=public.crt
dbms.ssl.policy.bolt.client_auth=NONE

# enforcing ssl connection
server.bolt.tls_level=REQUIRED

Configure a DBMS with a remote database alias (Alice)

As Alice, you need to generate an encryption key. In this case, the credentials of a user of DBMS B are reversibly encrypted and stored in the system database of DBMS A.

Since the algorithm used is AES/GCM, an AES encryption key needs to be provided. It should have length 256, and be stored in a password-protected keystore, of format pkcs12.

The key can be generated by using the following keytool command in your terminal, which is included in Java Platform, Standard Edition:

keytool -genseckey -keyalg aes -keysize 256 -storetype pkcs12 -keystore [keystore-name] -alias [key-name] -storepass [keystore-password]

It is recommended to generate the keystore on the same Java version on which Neo4j is run, as the supported encryption algorithms may vary. For details on the version of Java required by Neo4j, see System requirements → Java.

The following configuration is necessary for creating a remote database alias:

Configuration Description

dbms.security.keystore.path

The absolute path to the keystore file, including the file name.

dbms.security.keystore.password

The password to the keystore file. Use Command expansion to set the password.

dbms.security.key.name

The name of the secret key

To prevent unauthorized access, the keystore file must be stored in a trusted location. This is the main way to protect the encrypted passwords which will be stored on the system database. It shouldn’t be accessible to any user except for the administrator and neo4j, for whom the keystore file must be readable.

In a cluster, Alice needs to share the same keystore file over all instances.

For example, these would be valid additions to the config when using the suggested keytool command:

dbms.security.keystore.path=/home/secure-folder/keystore-name.pkcs12
dbms.security.keystore.password=$(conf/password.sh)
dbms.security.key.name=key-name

Where password.sh might look like this:

#!/bin/bash
echo "$KEYSTORE_PASSWORD_ENVIRONMENT_VARIABLE"

Additionally, don’t forget to change the permissions of the configuration file, and start Neo4j with the command expansion flag:

chmod 640 conf/neo4j.conf
bin/neo4j start --expand-commands

Manage remote database aliases

You can use the alias commands to manage remote database aliases. In this case, it is strongly recommended to connect to a remote database alias with a secured connection.

Please note that only client-side SSL is supported. By default, remote aliases require a secured URI scheme such as neo4j+s. This can be disabled by setting the driver setting ssl_enforced to false.

For example, the following command can be used to create a remote database alias:

CREATE ALIAS `remote-neo4j` FOR DATABASE `neo4j` AT "neo4j+s://location:7687" USER alice PASSWORD 'secretpassword'

In order to do so, either ldatabase management or lalias management privileges are required. The permission to create an alias can be granted like this:

GRANT CREATE ALIAS ON DBMS TO administrator

Here is how to grant the ACCESS privileges to use the remote database alias:

GRANT ACCESS ON DATABASE `remote-neo4j` TO role

If a transaction modifies an alias (e.g. changing the database targeted on DBMS B), other transactions concurrently executing against that alias may be aborted and rolled back for safety. This prevents issues such as a transaction executing against multiple target databases for the same alias.

Change the encryption key

If the encryption key in the keystore is changed, the encrypted credentials for existing remote database aliases will need to be updated as they will no longer be readable.

If there is a failure when reading the keystore file, investigate the debug.log to find out which parameter is the source of the problem. In case it is not possible to connect to the remote alias after its creation, verify its settings by connecting to the remote database at https://browser.neo4j.io/ or at your local browser.

Connect to remote database aliases

A user can connect to a remote database alias the same way they would do to a database. This includes:

  • Connecting directly to the remote database alias.

  • The Cypher USE clause enables a user to query a remote database alias that they are not directly connected to:

USE `remote-neo4j` MATCH (n) RETURN *

  • Connecting to a remote database alias as a home database. This needs to be set by Administrator A. See more about lUser Management.

ALTER USER alice SET HOME DATABASE `remote-neo4j`

Remote alias transactions will not be visible in SHOW TRANSACTIONS on DBMS A. However, they can be accessed and terminated on the remote database when connecting with the same user.