Connecting remote databases

This section describes the steps required to guarantee a secure connection to a remote database.

In the following example, a remote alias in DBMS A will connect to a remote database named Db1 in DBMS B.

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 we connect to the remote database using driver settings.

  • A remote database alias is only accessible by users with appropriate privileges. See DBMS administration for further information.

  • Any user who will have access to the remote alias will need to authenticate with the remote user credentials on DBMS B.

  • A remote alias does not restrict the access to Db2. If the remote user should not be able to access Db2, Administrator B needs to define the appropriate privileges. See Access Control for further information.

  • In a cluster, the administration of the remote database alias must be executed on the system database, on the Leader member of the cluster. The remote database alias is available on all members of a cluster - this applies to Core servers and Read Replicas.

In order to guarantee a secure connection, the following steps are required:

1. Configuration needed on the remote DBMS (Administrator B)

  1. Create the user to share with Administrator A. Currently, only user and password based authentication such as native authentication are supported.

  2. Define the permissions for the user as you see fit.

  3. Securely transmit the credentials to Administrator A, setting up the link to database Db1.

  • If a remote alias target is a cluster, it is recommended to enable Server-side routing to handle leader changes.

  • It is recommended to create a custom role to track all users shared for a remote connection, so they remain trackable.

2. Configuration needed on the DBMS with the remote database alias (Administrator A)

2.1. Generate an encryption key

To authorize anyone to be able to access a remote database alias, the credentials of a user of DBMS B are reversibly encrypted and stored in the system database of DBMS A. The algorithm used is AES/GCM. Therefore, 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 using the following keytool command, which requires a password:

keytool -genseckey -keyalg aes -keysize 256 -storetype pkcs12 -keystore [key-store-name] -alias [key-name] -storepass [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 Java.

2.2. Set configuration

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

Configuration Description

systemdb.secrets.keystore.path

The path to the keystore file

systemdb.secrets.keystore.password

The password to the keystore file

systemdb.secrets.key.name

The name of the secret key

To protect the symmetric key to ensure the integrity of the connection to the remote database, the keystore should be stored in a trusted location, which should be accessible only by admins and readable by the Neo4j user.

In a cluster the keystore file needs to be shared over all servers.

2.3. Managing remote database aliases

Use the alias commands to manage remote database aliases. It is encouraged 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.

In order to do so, either database management or alias management privileges are required. Grant the access privileges to use the remote database alias.

If a transaction modifies an alias, 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.

2.4. Alter configuration

When exchanging the encryption key, existing encrypted credentials can no longer be decrypted, and all remote database aliases need to be updated.