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:
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 ( 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:
-
Create the user profile to share with Alice. Currently, only user and password-based authentication (e.g. native authentication) are supported.
-
Define the permissions for the user. If you don’t want this user to access
Db2
, here is where you set it. -
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 |
---|---|
The absolute path to the keystore file, including the file name. |
|
The password to the keystore file. Use Command expansion to set the password. |
|
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 |
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 |
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 |