From d93610ed13df3c7631c7db190de4ab24dda0900a Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Thu, 30 Oct 2025 16:20:23 +0100 Subject: [PATCH 01/24] docs: updated and added OIDC credential forwarding --- .../manage-aliases-standard-databases.adoc | 54 +++++- .../remote-database-alias-configuration.adoc | 157 ++++++++++++++++-- 2 files changed, 191 insertions(+), 20 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc index 1c6194786..956bf51bb 100644 --- a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc +++ b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc @@ -379,7 +379,7 @@ SHOW ALIAS `northwind-2022` FOR DATABASE YIELD name, properties [[alias-management-create-remote-database-alias]] === Create database aliases for remote databases -A database alias can target a remote database by providing an URL and the credentials of a user on the remote Neo4j DBMS. +A database alias can target a remote database by providing a URL and the credentials of a user on the remote Neo4j DBMS. See xref:database-administration/aliases/remote-database-alias-configuration.adoc[] for the necessary configurations. Since remote database aliases target databases that are not in this DBMS, they do not fetch the default Cypher version from their target like the local database aliases. @@ -387,10 +387,17 @@ Instead, they are assigned the version given by xref:configuration/configuration Alternatively, you can specify the version in the `CREATE ALIAS` or `ALTER ALIAS` commands. See xref:database-administration/aliases/manage-aliases-standard-databases.adoc#set-default-language-for-remote-database-aliases[] and xref:database-administration/aliases/manage-aliases-standard-databases.adoc#alter-default-language-remote-database-alias[] for more information. +When creating a remote database alias, the credentials used to target to the remote DBMS need to be specified and can be either: + +* `STORED NATIVE CREDENTIALS`, using the credentials of a single native user on the remote DBMS. +* `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local DBMS. The user needs to be logged in with an identity provider supporting OIDC. label:new[Introduced in 2025.10] + +To use the credentials of a native user on the remote DBMS, `USER` and `PASSWORD` need to be set when creating the alias. + .Query [source, cypher] ---- -CREATE ALIAS `remote-northwind` FOR DATABASE `northwind-graph-2020` +CREATE ALIAS `remote-northwind-stored-credentials` FOR DATABASE `northwind-graph-2020` AT "neo4j+s://location:7687" USER alice PASSWORD 'example_secret' @@ -401,20 +408,51 @@ To view the remote database alias details, use the `SHOW ALIASES FOR DATABASE` c .Query [source, cypher] ---- -SHOW ALIAS `remote-northwind` +SHOW ALIAS `remote-northwind-stored-credentials` FOR DATABASE ---- .Result [role="queryresult"] ---- -+----------------------------------------------------------------------------------------------------------+ -| name | composite | database | location | url | user | -+----------------------------------------------------------------------------------------------------------+ -| "remote-northwind" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "alice" | -+----------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | user | ++-----------------------------------------------------------------------------------------------------------------------------+ +| "remote-northwind-stored-credentilas" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "alice" | ++-----------------------------------------------------------------------------------------------------------------------------+ +---- + +The `OIDC CREDENTIAL FORWARDING` clause is used to configure a remote database alias to use the logged-in user's OIDC credentials to authenticate to the remote DBMS. +In order to use this method to authenticate, the local DBMS and remote DBMS needs to have SSO authentication and authorization through identity providers implementing the OIDC standard configured, see the xref:authentication-authorization/sso-integration.adoc[SSO integration] on how to configure OIDC identity providers. + +.Query +[source, cypher] +---- +CREATE ALIAS `remote-northwind-oidc-credential-forwarding` FOR DATABASE `northwind-graph-2020` +AT "neo4j+s://location:7687" +OIDC CREDENTIAL FORWARDING ---- +Since the alias use the credentials of the logged-in user when targeting the remote DBMS, there are no stored credentials and user will be `NULL`. + +.Query +[source, cypher] +---- +SHOW ALIAS `remote-northwind-oidc-credential-forwarding` +FOR DATABASE +---- + +.Result +[role="queryresult"] +---- ++-------------------------------------------------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | user | ++-------------------------------------------------------------------------------------------------------------------------------------+ +| "remote-northwind-oidc-credential-forwarding" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | NULL | ++-------------------------------------------------------------------------------------------------------------------------------------+ +---- + + You can also use `IF EXISTS` or `OR REPLACE` when creating remote database aliases. It works the same way as described in the <<_use_if_exists_or_or_replace_when_creating_database_aliases, Use `IF EXISTS` or `OR REPLACE` when creating database aliases>> section. Both check for any remote or local database aliases (with `IF NOT EXISTS` also checking for databases). diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index f5321285b..72439c44c 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -14,18 +14,26 @@ The following steps describe the setup required to define a remote database alia 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_: - -image::remote-alias-overview.svg[title="Overview of the required remote database alias setup", role="middle"] - 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. +When creating the remote database alias, it can be configured to authenticate with either: + +* `STORED NATIVE CREDENTIALS`, the credentials of a single native user on the remote **DBMS B**. +* `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local **DBMS A**. The user needs to be logged in with an identity provider supporting OIDC. label:new[Introduced in 2025.10] + + +[[setup-example-stored-native-credentials]] +== Setup example with stored native credentials + +In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_: + +image::remote-alias-overview.svg[title="Overview of the required remote database alias setup when using stored credentials", role="middle"] + + [NOTE] ==== A remote database alias is only accessible to users with appropriate privileges. @@ -41,13 +49,12 @@ 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 xref:authentication-authorization/index.adoc[Authentication and authorization] for further information. -== Configure a remote DBMS (_Bob_) +=== 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. @@ -80,7 +87,7 @@ server.bolt.tls_level=REQUIRED ---- [[remote-alias-config-DBMS_admin-A]] -== Configure a DBMS with a remote database alias (_Alice_) +=== 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**. @@ -146,7 +153,7 @@ chmod 640 conf/neo4j.conf bin/neo4j start --expand-commands ---- -== Manage remote database aliases +=== Manage remote database aliases You can use the xref:database-administration/aliases/manage-aliases-standard-databases.adoc[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. @@ -155,7 +162,7 @@ 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: +For example, the following command can be used to create a remote database alias with stored native credentials: [source, Cypher] ---- @@ -184,7 +191,7 @@ If a transaction modifies an alias (e.g. changing the database targeted on **DBM This prevents issues such as a transaction executing against multiple target databases for the same alias. ==== -== Change the encryption key +=== 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. @@ -194,6 +201,120 @@ If there is a failure when reading the keystore file, investigate the `debug.log 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. ==== +[role=label--new-2025.10] +[[setup-example-credential-forwarding]] +== Setup example with OIDC credential forwarding + +In order to use OIDC credential forwarding, both *DBMS A* and *DBMS B* need to support the same OIDC identity provider, see the xref:authentication-authorization/sso-integration.adoc[SSO integration] on how to enable OIDC. + +In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_: + +In the example above, _Carol_ logs in to *DBMS A* through an OIDC compliant identity provider by offering a token from the provider. +The token is used to set the username and determine the identity provider groups of the user. +_Alice_ is the admin of *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias to connect to the remote database `Db1`. +Additionally, _Bob_ needs to configure the *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. _Bob_ also needs to configure the mapping of the identity provider groups to the Neo4j roles such that the _Carol's_ identity provider groups gives the appropriate privileges to access `Db1` on the *DBMS B*. + + +[CAUTION] +==== +While it is permitted to use different OIDC configurations across distinct DBMS instances (e.g., local vs. target), users must be aware of the resulting privilege disparity. +A user's effective permissions are not dictated by the identity provider groups alone, but by the mapping of those groups to the roles defined within each specific Neo4j DBMS, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. +Crucially, if the OIDC configuration settings differ between the local DBMS and the target DBMS, the user will have different effective privileges on those systems. +This configuration independence can lead to privilege inconsistency (e.g., over-privileging or unexpected access denial). +==== + +=== 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: + +. Set up SSO and support for the identity provider. +. Map the identity provider groups to the Neo4j roles. If you don’t want specific users to access `Db2`, here is where you set it. + +Additionally, _Bob_ must do the required setup for the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts a non-local connection if required. + +[source, Example of additional configuration] +---- +# 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 + +# OIDC settings - these should be the same on both DBMSs +dbms.security.oidc..well_known_discovery_uri=http://example.com/.well-known/discovery +<...> +dbms.security.oidc..claims.groups=groups +dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = admin; \ + "collaborators" = reader +---- + +=== Configure a DBMS with a remote database alias (_Alice_) + +The steps _Alice_, need to take are: + +. Set up SSO and support for the identity provider. +. Map the identity provider groups to the Neo4j roles. This is where the permission to use the remote database alias is set. + +[source, Example of additional configuration] +---- +# OIDC settings - these should be the same on both DBMSs +dbms.security.oidc..well_known_discovery_uri=http://example.com/.well-known/discovery +<...> +dbms.security.oidc..claims.groups=groups +dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = admin; \ + "collaborators" = reader +---- +=== Manage remote database aliases + +You can use the xref:database-administration/aliases/manage-aliases-standard-databases.adoc[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 with OIDC credential forwarding: + +[source, Cypher] +---- +CREATE ALIAS `remote-neo4j` FOR DATABASE `neo4j` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING +---- + +In order to do so, either xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management] +or xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges are required. +The permission to create an alias can be granted like this: + +[source, Cypher] +---- +GRANT CREATE ALIAS ON DBMS TO administrator +---- + +Here is how to grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias: + +[source, Cypher] +---- +GRANT ACCESS ON DATABASE `remote-neo4j` TO admin +---- + +In order for _Carol_ to get access to the remote database alias, she needs to be in an identity provider group that is mapped to a Neo4j role that is granted access to alias. In this example, if _Carol_ is in the identity provider group `engineers` which is mapped to the `admin` role, she will get the privileges of an `admin` and access to `remote-neo4j`. +For details on how to map identity provider groups to Neo4j roles, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. + +[NOTE] +==== +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. +==== + + == Connect to remote database aliases A user can connect to a remote database alias the same way they would do to a database. @@ -221,3 +342,15 @@ 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. ==== + +[NOTE] +==== +Action on the remote DBMS are all attributed to the user configured for the remote database alias. +In the case of using `STORED NATIVE CREDENTIALS`, the same credentials are used to connect to the remote DBMS independent on which end-user made the query targeting the remote alias. This will result in the stored native user being logged in the audit trails on the remote DBMS for all queries using the remote database alias. +When using `OIDC CREDENTIAL FORWARDING` the actual end-user's credentials and permissions will be used, this will result in per-user audit trails being logged on the remote DBMS. +==== + +[NOTE] +==== +When using a remote database alias with OIDC credential forwarding, the user needs to be logged in to the local DBMS with OIDC, otherwise there is no token to forward and the access to the remote database will be denied with `GQLSTATUS 42NFF`. +==== \ No newline at end of file From 9df769a879dc0252f4c5dc6362b14bf903b3cb41 Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Mon, 10 Nov 2025 08:48:42 +0100 Subject: [PATCH 02/24] docs: include oidc credential forwarding figure --- ...e-alias-credential-forwarding-overview.svg | 56 +++++++++++++++++++ .../remote-database-alias-configuration.adoc | 11 ++-- 2 files changed, 63 insertions(+), 4 deletions(-) create mode 100644 modules/ROOT/images/remote-alias-credential-forwarding-overview.svg diff --git a/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg b/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg new file mode 100644 index 000000000..cfa7cc9f0 --- /dev/null +++ b/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index 72439c44c..57edc5e9c 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -209,15 +209,18 @@ In order to use OIDC credential forwarding, both *DBMS A* and *DBMS B* need to s In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_: + +image::remote-alias-credential-forwarding-overview.svg[title="Overview of the required remote database alias setup when using oidc credential forwarding", role="middle"] + In the example above, _Carol_ logs in to *DBMS A* through an OIDC compliant identity provider by offering a token from the provider. The token is used to set the username and determine the identity provider groups of the user. -_Alice_ is the admin of *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias to connect to the remote database `Db1`. +_Alice_ is the admin of *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `remote-neo4j`, to connect to the remote database `Db1`. Additionally, _Bob_ needs to configure the *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. _Bob_ also needs to configure the mapping of the identity provider groups to the Neo4j roles such that the _Carol's_ identity provider groups gives the appropriate privileges to access `Db1` on the *DBMS B*. [CAUTION] ==== -While it is permitted to use different OIDC configurations across distinct DBMS instances (e.g., local vs. target), users must be aware of the resulting privilege disparity. +While it is possible to use different OIDC configurations across distinct DBMS instances (DBMS A & B in this example), database administrators must be aware of the resulting privilege disparity. A user's effective permissions are not dictated by the identity provider groups alone, but by the mapping of those groups to the roles defined within each specific Neo4j DBMS, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. Crucially, if the OIDC configuration settings differ between the local DBMS and the target DBMS, the user will have different effective privileges on those systems. This configuration independence can lead to privilege inconsistency (e.g., over-privileging or unexpected access denial). @@ -230,7 +233,7 @@ 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: . Set up SSO and support for the identity provider. -. Map the identity provider groups to the Neo4j roles. If you don’t want specific users to access `Db2`, here is where you set it. +. Map the identity provider groups to the Neo4j roles. If you don’t want specific users to access `Db2`, here is where you set it. See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. Additionally, _Bob_ must do the required setup for the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts a non-local connection if required. @@ -262,7 +265,7 @@ dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = The steps _Alice_, need to take are: . Set up SSO and support for the identity provider. -. Map the identity provider groups to the Neo4j roles. This is where the permission to use the remote database alias is set. +. Map the identity provider groups to the Neo4j roles. This is where the permission to use the remote database alias is set. See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. [source, Example of additional configuration] ---- From 88299cbefbcb6b34401cab81d924c059c07f19c0 Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Mon, 10 Nov 2025 13:47:12 +0100 Subject: [PATCH 03/24] docs: add credentials column to show aliases --- .../manage-aliases-composite-databases.adoc | 54 +++++------ .../manage-aliases-standard-databases.adoc | 90 ++++++++++--------- .../tutorial/tutorial-composite-database.adoc | 14 +-- 3 files changed, 81 insertions(+), 77 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc b/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc index 69a420f25..718e7714b 100644 --- a/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc +++ b/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc @@ -42,12 +42,12 @@ SHOW ALIASES FOR DATABASE .Result [role="queryresult"] ---- -+--------------------------------------------------------------------------------------------------+ -| name | composite | database | location | url | user | -+--------------------------------------------------------------------------------------------------+ -| "library.romance" | "library" | "romance-books" | "remote" | "neo4j+s://location:7687" | "alice" | -| "library.sci-fi" | "library" | "sci-fi-books" | "local" | NULL | NULL | -+--------------------------------------------------------------------------------------------------+ ++--------------------------------------------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | ++--------------------------------------------------------------------------------------------------------------------------------+ +| "library.romance" | "library" | "romance-books" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | +| "library.sci-fi" | "library" | "sci-fi-books" | "local" | NULL | NULL | NULL | ++--------------------------------------------------------------------------------------------------------------------------------+ ---- For a description of all the returned columns of this command, and for ways in which the `SHOW ALIASES FOR DATABASE` command can be filtered for aliases, see xref:database-administration/aliases/manage-aliases-standard-databases.adoc#manage-aliases-list[list aliases for standard databases]. @@ -105,12 +105,12 @@ WHERE composite = 'garden' .Result [role="queryresult"] ---- -+-----------------------------------------------------------------------------------------------------+ -| name | composite | database | location | url | user | -+-----------------------------------------------------------------------------------------------------+ -| "garden.flowers" | "garden" | "perennial-flowers" | "local" | NULL | NULL | -| "garden.trees" | "garden" | "trees" | "remote" | "neo4j+s://location:7687" | "alice" | -+-----------------------------------------------------------------------------------------------------+ ++-----------------------------------------------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | ++-----------------------------------------------------------------------------------------------------------------------------------+ +| "garden.flowers" | "garden" | "perennial-flowers" | "local" | NULL | NULL | NULL | +| "garden.trees" | "garden" | "trees" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | ++-----------------------------------------------------------------------------------------------------------------------------------+ ---- Database aliases cannot target a composite database. @@ -159,14 +159,14 @@ SHOW ALIASES FOR DATABASE YIELD * .Result [role="queryresult"] ---- -+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| name | composite | database | location | url | user | driver | defaultLanguage | properties | -+-----------------------------------------------------------------------------------------------------------------------------------------------------+ -| "garden.flowers" | "garden" | "perennial-flowers" | "local" | NULL | NULL | NULL | NULL | {perennial: TRUE} | -| "garden.trees" | "garden" | "updatedtrees" | "remote" | "neo4j+s://location:7687" | "alice" | {} | NULL | {treeversion: 2} | -| "library.romance" | "library" | "romance-books" | "remote" | "neo4j+s://location:7687" | "alice" | {} | NULL | {} | -| "library.sci-fi" | "library" | "sci-fi-books" | "local" | NULL | NULL | NULL | NULL | {} | -+-----------------------------------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | driver | defaultLanguage | properties | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| "garden.flowers" | "garden" | "perennial-flowers" | "local" | NULL | NULL | NULL | NULL | NULL | {perennial: TRUE} | +| "garden.trees" | "garden" | "updatedtrees" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | {} | NULL | {treeversion: 2} | +| "library.romance" | "library" | "romance-books" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | {} | NULL | {} | +| "library.sci-fi" | "library" | "sci-fi-books" | "local" | NULL | NULL | NULL | NULL | NULL | {} | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- [[delete-composite-database-alias]] @@ -192,13 +192,13 @@ SHOW ALIASES FOR DATABASE .Result [role="queryresult"] ---- -+--------------------------------------------------------------------------------------------------+ -| name | composite | database | location | url | user | -+--------------------------------------------------------------------------------------------------+ -| "garden.trees" | "garden" | "updatedtrees" | "remote" | "neo4j+s://location:7687" | "alice" | -| "library.romance" | "library" | "romance-books" | "remote" | "neo4j+s://location:7687" | "alice" | -| "library.sci-fi" | "library" | "sci-fi-books" | "local" | NULL | NULL | -+--------------------------------------------------------------------------------------------------+ ++--------------------------------------------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | ++--------------------------------------------------------------------------------------------------------------------------------+ +| "garden.trees" | "garden" | "updatedtrees" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | +| "library.romance" | "library" | "romance-books" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | +| "library.sci-fi" | "library" | "sci-fi-books" | "local" | NULL | NULL | NULL | ++--------------------------------------------------------------------------------------------------------------------------------+ ---- Additionally, deleted aliases will no longer appear in the `constituents` column for the `SHOW DATABASE` command. diff --git a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc index 956bf51bb..bbfc140f5 100644 --- a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc +++ b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc @@ -113,6 +113,10 @@ If a user has not been granted the `ACCESS` privilege to the target database and | Target location or `null` if the target is local. label:default-output[] | STRING +| credentials +| The type of credentials used to connect to the remote database, either `STORED NATIVE CREDENTIALS` or `OIDC CREDENTIAL FORWARDING`, or null if the target database is local. label:default-output[] label:new[Introduced in 2025.10] +| STRING + | user | Native user connecting to the remote database, or `null` if the target database is local or OIDC credential forwarding is used to authenticate against the remote database. label:default-output[] | STRING @@ -148,13 +152,13 @@ SHOW ALIASES FOR DATABASE .Result [role="queryresult] ---- -+--------------------------------------------------------------------------------------------+ -| name | composite | database | location | url | user | -+--------------------------------------------------------------------------------------------+ -| "films" | NULL | "movies" | "local" | NULL | NULL | -| "motion pictures" | NULL | "movies" | "local" | NULL | NULL | -| "movie scripts" | NULL | "scripts" | "remote" | "neo4j+s://location:7687" | "alice" | -+--------------------------------------------------------------------------------------------+ ++--------------------------------------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | ++--------------------------------------------------------------------------------------------------------------------------+ +| "films" | NULL | "movies" | "local" | NULL | NULL | NULL | +| "motion pictures" | NULL | "movies" | "local" | NULL | NULL | NULL | +| "movie scripts" | NULL | "scripts" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | ++--------------------------------------------------------------------------------------------------------------------------+ ---- === Show a specific database alias @@ -170,11 +174,11 @@ SHOW ALIAS films FOR DATABASES .Result [role="queryresult"] ---- -+---------------------------------------------------------+ -| name | composite | database | location | url | user | -+---------------------------------------------------------+ -| "films" | NULL | "movies" | "local" | NULL | NULL | -+---------------------------------------------------------+ ++--------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | ++--------------------------------------------------------------------------+ +| "films" | NULL | "movies" | "local" | NULL | NULL | NULL | ++--------------------------------------------------------------------------+ ---- === Show detailed information about all database aliases @@ -190,13 +194,13 @@ SHOW ALIASES FOR DATABASE YIELD * .Result [role="queryresult"] ---- -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| name | composite | database | location | url | user | driver | defaultLanguage | properties | -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| "films" | NULL | "movies" | "local" | NULL | NULL | NULL | NULL | {} | -| "motion pictures" | NULL | "movies" | "local" | NULL | NULL | NULL | NULL | {namecontainsspace: TRUE} | -| "movie scripts" | NULL | "scripts" | "remote" | "neo4j+s://location:7687" | "alice" | {connection_pool_idle_test: PT2M, connection_pool_max_size: 10, logging_level: "INFO", ssl_enforced: TRUE, connection_pool_acquisition_timeout: PT1M, connection_timeout: PT5S, connection_max_lifetime: PT1H} | "CYPHER 25" | {} | -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | driver | defaultLanguage | properties | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| "films" | NULL | "movies" | "local" | NULL | NULL | NULL | NULL | NULL | {} | +| "motion pictures" | NULL | "movies" | "local" | NULL | NULL | NULL | NULL | NULL | {namecontainsspace: TRUE} | +| "movie scripts" | NULL | "scripts" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | {connection_pool_idle_test: PT2M, connection_pool_max_size: 10, logging_level: "INFO", ssl_enforced: TRUE, connection_pool_acquisition_timeout: PT1M, connection_timeout: PT5S, connection_max_lifetime: PT1H} | "CYPHER 25" | {} | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- === Show the number of database aliases @@ -305,11 +309,11 @@ SHOW ALIAS `northwind` FOR DATABASE .Result [role="queryresult] ---- -+---------------------------------------------------------------------------+ -| name | composite | database | location | url | user | -+---------------------------------------------------------------------------+ -| "northwind" | NULL | "northwind-graph-2021" | "local" | NULL | NULL | -+---------------------------------------------------------------------------+ ++-----------------------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | ++-----------------------------------------------------------------------------------------+ +| "northwind" | NULL | "northwind-graph-2021" | "local" | NULL | NULL | NULL | ++-----------------------------------------------------------------------------------------+ ---- ==== Use `IF EXISTS` or `OR REPLACE` when creating database aliases @@ -415,11 +419,11 @@ FOR DATABASE .Result [role="queryresult"] ---- -+-----------------------------------------------------------------------------------------------------------------------------+ -| name | composite | database | location | url | user | -+-----------------------------------------------------------------------------------------------------------------------------+ -| "remote-northwind-stored-credentilas" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "alice" | -+-----------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| "remote-northwind-stored-credentilas" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- The `OIDC CREDENTIAL FORWARDING` clause is used to configure a remote database alias to use the logged-in user's OIDC credentials to authenticate to the remote DBMS. @@ -445,11 +449,11 @@ FOR DATABASE .Result [role="queryresult"] ---- -+-------------------------------------------------------------------------------------------------------------------------------------+ -| name | composite | database | location | url | user | -+-------------------------------------------------------------------------------------------------------------------------------------+ -| "remote-northwind-oidc-credential-forwarding" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | NULL | -+-------------------------------------------------------------------------------------------------------------------------------------+ ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| "remote-northwind-oidc-credential-forwarding" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "OIDC CREDENTIAL FORWARDING" | NULL | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- @@ -503,11 +507,11 @@ SHOW ALIAS `remote-with-driver-settings` FOR DATABASE YIELD * .Result [role="queryresult"] ---- -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| name | composite | database | location | url | user | driver | properties | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| "remote-with-driver-settings" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "alice" | {connection_pool_max_size: 10, connection_timeout: PT1M} | {} | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | driver | properties | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| "remote-with-driver-settings" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | {connection_pool_max_size: 10, connection_timeout: PT1M} | {} | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- [role=label--new-2025.06] @@ -790,10 +794,10 @@ SHOW ALIASES `remote-northwind` FOR DATABASE .Result [role="queryresult"] ---- -+-----------------------------------------------------+ -| name | composite | database | location | url | user | -+-----------------------------------------------------+ -+-----------------------------------------------------+ ++-------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | ++-------------------------------------------------------------------+ ++-------------------------------------------------------------------+ ---- === Use `IF EXISTS` when deleting database aliases diff --git a/modules/ROOT/pages/tutorial/tutorial-composite-database.adoc b/modules/ROOT/pages/tutorial/tutorial-composite-database.adoc index 0b8045b28..bcb416f9a 100644 --- a/modules/ROOT/pages/tutorial/tutorial-composite-database.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-composite-database.adoc @@ -498,13 +498,13 @@ SHOW ALIASES FOR DATABASES; + [queryresult] ---- -+--------------------------------------------------------------------------------+ -| name | composite | database | location | url | user | -+--------------------------------------------------------------------------------+ -| "compositenw.product" | "compositenw" | "db0" | "local" | null | null | -| "compositenw.customerEU" | "compositenw" | "db1" | "local" | null | null | -| "compositenw.customerAME" | "compositenw" | "db2" | "local" | null | null | -+--------------------------------------------------------------------------------+ ++----------------------------------------------------------------------------------------------+ +| name | composite | database | location | url | credentials | user | ++----------------------------------------------------------------------------------------------+ +| "compositenw.product" | "compositenw" | "db0" | "local" | null | null | null | +| "compositenw.customerEU" | "compositenw" | "db1" | "local" | null | null | null | +| "compositenw.customerAME" | "compositenw" | "db2" | "local" | null | null | null | ++----------------------------------------------------------------------------------------------+ 3 rows available after 203 ms, consumed after another 16 ms ---- From 07bb533dba8e09ff3b8f3aa2b5772f61e5c4579e Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Mon, 17 Nov 2025 09:43:01 +0100 Subject: [PATCH 04/24] docs: add info about altering alias command not supporting change of credential type --- .../manage-aliases-standard-databases.adoc | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc index bbfc140f5..54c839d08 100644 --- a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc +++ b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc @@ -645,9 +645,9 @@ ALTER ALIAS `remote-northwind` SET DATABASE TARGET `northwind-graph-2020` AT "neo4j+s://other-location:7687" ---- -=== Alter a remote database alias credentials and driver settings +=== Alter a remote database alias stored native credentials and driver settings -You can change the user credentials and driver settings of a remote database alias using the `USER`, `PASSWORD`, and `DRIVER` subclauses of the `SET DATABASE` clause of the `ALTER ALIAS` command. +You can change the stored native credentials and driver settings of a remote database alias using the `USER`, `PASSWORD`, and `DRIVER` subclauses of the `SET DATABASE` clause of the `ALTER ALIAS` command. For example: .Query @@ -669,6 +669,17 @@ All driver settings are replaced by the new ones. In this case, by not repeating the driver setting `connection_pool_max_size`, the value will be deleted and fall back to the default value. ==== +[role=label--new-2025.10] +=== Alter a remote database alias credential type + +Changing the type of credentials used by a remote database alias, `STORED NATIVE CREDENTIALS` or `OIDC CREDENTIAL FORWARDING`, by using the `ALTER ALIAS` command is currently not supported. +To change the type of credentials, the remote database alias needs to be dropped and replaced with a new one. + +[IMPORTANT] +==== +Any associated privileges, driver settings and other properties will be lost when dropping the alias and need to be respecified for the new one. See xref:authentication-authorization/database-administration.adoc[Database privileges] on how to manage access to the remote database alias and other privileges. +==== + === Remove all custom driver settings from a remote database alias You can remove all custom driver settings from a remote database alias by setting the `DRIVER` clause to an empty map `{}`. From 1a5e7f8bba7eabfb6cb7bb5a927908426c612255 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 27 Nov 2025 16:10:51 +0000 Subject: [PATCH 05/24] editorial updates --- .../manage-aliases-standard-databases.adoc | 71 ++++++++++++------- .../remote-database-alias-configuration.adoc | 67 +++++++++-------- 2 files changed, 76 insertions(+), 62 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc index 54c839d08..2a4e17011 100644 --- a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc +++ b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc @@ -79,20 +79,22 @@ The `YIELD *` clause returns the full set of columns. The required privileges are described in the xref:authentication-authorization/dbms-administration/dbms-alias-management-privileges.adoc[The DBMS ALIAS MANAGEMENT privileges]. .Available columns -[options="header" cols="2m,4a,2m"] +[options="header" cols="2m,4a,2m,2a"] |=== -| Column | Description | Type +| Column | Description | Type | Default output | name -| The fully qualified name of the database alias. label:default-output[] +| The fully qualified name of the database alias. | STRING +| {check-mark} | composite -| The name of the composite database this alias belongs to, or `null` if the alias does not belong to a composite database. label:default-output[] +| The name of the composite database this alias belongs to, or `null` if the alias does not belong to a composite database. | STRING +| {check-mark} | database -| The name of the target database. label:default-output[] +| The name of the target database. This column is filtered according to the `ACCESS` privileges of the user. However, some privileges enable users to see additional databases regardless of their `ACCESS` privileges: @@ -104,37 +106,45 @@ However, some privileges enable users to see additional databases regardless of If a user has not been granted the `ACCESS` privilege to the target database and none of the above special cases apply, then it is not visible to the user and this column will be `null`. | STRING +| {check-mark} | location -| The location of the database, either `local` or `remote`. label:default-output[] +| The location of the database, either `local` or `remote`. | STRING +| {check-mark} | url -| Target location or `null` if the target is local. label:default-output[] +| Target location or `null` if the target is local. | STRING +| {check-mark} | credentials -| The type of credentials used to connect to the remote database, either `STORED NATIVE CREDENTIALS` or `OIDC CREDENTIAL FORWARDING`, or null if the target database is local. label:default-output[] label:new[Introduced in 2025.10] +| label:new[Introduced in 2025.10] The type of credentials used to connect to the remote database, either `STORED NATIVE CREDENTIALS` or `OIDC CREDENTIAL FORWARDING`, or null if the target database is local. | STRING +| {check-mark} | user -| Native user connecting to the remote database, or `null` if the target database is local or OIDC credential forwarding is used to authenticate against the remote database. label:default-output[] +| Native user connecting to the remote database, or `null` if the target database is local or OIDC credential forwarding is used to authenticate against the remote database. | STRING +| {check-mark} | driver | The driver options for connection to the remote database or `null` if the target database is local. List of xref::database-administration/aliases/manage-aliases-standard-databases.adoc#alias-management-create-remote-database-alias-driver-settings[driver settings] allowed for remote database aliases. | MAP +| | defaultLanguage | label:new[Introduced in 2025.06] The default language for non-constituent remote database aliases or `null` if it is a constituent or local database alias. | STRING +| | properties | Any properties set on the database alias. | MAP +| |=== @@ -391,12 +401,21 @@ Instead, they are assigned the version given by xref:configuration/configuration Alternatively, you can specify the version in the `CREATE ALIAS` or `ALTER ALIAS` commands. See xref:database-administration/aliases/manage-aliases-standard-databases.adoc#set-default-language-for-remote-database-aliases[] and xref:database-administration/aliases/manage-aliases-standard-databases.adoc#alter-default-language-remote-database-alias[] for more information. -When creating a remote database alias, the credentials used to target to the remote DBMS need to be specified and can be either: +When creating a remote database alias, you need to specify the credentials used to target to the remote DBMS. +You can choose between two types of credentials: * `STORED NATIVE CREDENTIALS`, using the credentials of a single native user on the remote DBMS. -* `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local DBMS. The user needs to be logged in with an identity provider supporting OIDC. label:new[Introduced in 2025.10] +* label:new[Introduced in 2025.10] `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local DBMS. +The user must be logged in with an identity provider supporting OIDC. -To use the credentials of a native user on the remote DBMS, `USER` and `PASSWORD` need to be set when creating the alias. +You can also use `IF EXISTS` or `OR REPLACE` when creating remote database aliases. +It works the same way as described in the <<_use_if_exists_or_or_replace_when_creating_database_aliases, Use `IF EXISTS` or `OR REPLACE` when creating database aliases>> section. +Both check for any remote or local database aliases (with `IF NOT EXISTS` also checking for databases). + +==== Create remote database aliases with stored native credentials + +You can create a remote database alias using stored native credentials by specifying the `USER` and `PASSWORD` clauses when creating the alias. +For example: .Query [source, cypher] @@ -407,8 +426,7 @@ USER alice PASSWORD 'example_secret' ---- -To view the remote database alias details, use the `SHOW ALIASES FOR DATABASE` command: - +You can verify that the remote database alias has been created correctly by using the `SHOW ALIASES FOR DATABASE` command: .Query [source, cypher] ---- @@ -426,8 +444,12 @@ FOR DATABASE +-----------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- -The `OIDC CREDENTIAL FORWARDING` clause is used to configure a remote database alias to use the logged-in user's OIDC credentials to authenticate to the remote DBMS. -In order to use this method to authenticate, the local DBMS and remote DBMS needs to have SSO authentication and authorization through identity providers implementing the OIDC standard configured, see the xref:authentication-authorization/sso-integration.adoc[SSO integration] on how to configure OIDC identity providers. +==== Create remote database aliases with OIDC credential forwarding + +You can create a remote database alias using OIDC credential forwarding by specifying the `OIDC CREDENTIAL FORWARDING` clause when creating the alias. +The `OIDC CREDENTIAL FORWARDING` clause configures the remote database alias to use the logged-in user's OIDC credentials to authenticate to it. +To use this method for authentication, both the local and remote DBMSs must have SSO authentication and authorization through identity providers that implement the OIDC standard configured. +See the xref:authentication-authorization/sso-integration.adoc[SSO integration] for details on how to configure OIDC identity providers. .Query [source, cypher] @@ -437,7 +459,7 @@ AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING ---- -Since the alias use the credentials of the logged-in user when targeting the remote DBMS, there are no stored credentials and user will be `NULL`. +Since the alias uses the credentials of the logged-in user when targeting the remote DBMS, there are no stored credentials, and the user will be `NULL`. .Query [source, cypher] @@ -456,12 +478,6 @@ FOR DATABASE +--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- - -You can also use `IF EXISTS` or `OR REPLACE` when creating remote database aliases. -It works the same way as described in the <<_use_if_exists_or_or_replace_when_creating_database_aliases, Use `IF EXISTS` or `OR REPLACE` when creating database aliases>> section. -Both check for any remote or local database aliases (with `IF NOT EXISTS` also checking for databases). - - [[alias-management-create-remote-database-alias-driver-settings]] ==== Create remote database aliases with driver settings @@ -672,12 +688,13 @@ In this case, by not repeating the driver setting `connection_pool_max_size`, th [role=label--new-2025.10] === Alter a remote database alias credential type -Changing the type of credentials used by a remote database alias, `STORED NATIVE CREDENTIALS` or `OIDC CREDENTIAL FORWARDING`, by using the `ALTER ALIAS` command is currently not supported. -To change the type of credentials, the remote database alias needs to be dropped and replaced with a new one. +Changing a remote database alias credential type (`STORED NATIVE CREDENTIALS` or `OIDC CREDENTIAL FORWARDING`) using the `ALTER ALIAS` command is currently not supported +To change the type of credentials, you must drop the remote database alias and replace it with a new one. -[IMPORTANT] +[CAUTION] ==== -Any associated privileges, driver settings and other properties will be lost when dropping the alias and need to be respecified for the new one. See xref:authentication-authorization/database-administration.adoc[Database privileges] on how to manage access to the remote database alias and other privileges. +Any associated privileges, driver settings and other properties will be lost when dropping the alias and need to be respecified for the new one. +See xref:authentication-authorization/database-administration.adoc[Database privileges] on how to manage access to the remote database alias and other privileges. ==== === Remove all custom driver settings from a remote database alias diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index 57edc5e9c..bf63f4c1f 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -4,26 +4,25 @@ [[manage-remote-aliases]] = 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. +You can use a remote database alias to connect to one or more graphs or to 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 xref:database-administration/aliases/manage-aliases-standard-databases.adoc[administrative commands] on a running system. -Any changes are automatically synchronized across all instances of a cluster. +Any changes are automatically synchronized across all members 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. +The following steps describe the setup required to define a remote database alias for both local and remote DBMSs. +They assume that you have already installed and started both DBMSs: a local *DBMS A* and a remote *DBMS B*, and that you have administrator access to both systems. -A remote alias defines: +By creating a remote alias, you define: -* Which user of the remote **DBMS B** is used. +* 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. When creating the remote database alias, it can be configured to authenticate with either: -* `STORED NATIVE CREDENTIALS`, the credentials of a single native user on the remote **DBMS B**. -* `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local **DBMS A**. The user needs to be logged in with an identity provider supporting OIDC. label:new[Introduced in 2025.10] +* `STORED NATIVE CREDENTIALS`, the credentials of a single native user on the remote *DBMS B*. +* label:new[Introduced in 2025.10] `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local *DBMS A*. The user needs to be logged in with an identity provider supporting OIDC. [[setup-example-stored-native-credentials]] @@ -34,10 +33,10 @@ In this example, _Alice_ is an administrator and _Carol_ is a user who needs acc image::remote-alias-overview.svg[title="Overview of the required remote database alias setup when using stored credentials", role="middle"] -[NOTE] +[TIP] ==== 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. +In this example, _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_. @@ -45,7 +44,7 @@ See xref:authentication-authorization/dbms-administration/index.adoc[DBMS privil ==== _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**. +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 xref:authentication-authorization/index.adoc[Authentication and authorization] for further information. @@ -55,7 +54,8 @@ 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_. -. Define the permissions for the user. If you don’t want this user to access `Db2`, here is where you set it. +. Define the permissions for the user. +If you do not 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. @@ -90,7 +90,7 @@ 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**. +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. @@ -187,7 +187,7 @@ GRANT ACCESS ON DATABASE `remote-neo4j` TO role [NOTE] ==== -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. +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. ==== @@ -205,15 +205,16 @@ In case it is not possible to connect to the remote alias after its creation, ve [[setup-example-credential-forwarding]] == Setup example with OIDC credential forwarding -In order to use OIDC credential forwarding, both *DBMS A* and *DBMS B* need to support the same OIDC identity provider, see the xref:authentication-authorization/sso-integration.adoc[SSO integration] on how to enable OIDC. +In order to use OIDC credential forwarding, both *DBMS A* and *DBMS B* need to support the same OIDC identity provider. +See the xref:authentication-authorization/sso-integration.adoc[SSO integration] on how to enable OIDC. In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_: -image::remote-alias-credential-forwarding-overview.svg[title="Overview of the required remote database alias setup when using oidc credential forwarding", role="middle"] +image::remote-alias-credential-forwarding-overview1.svg[title="Overview of the required remote database alias setup when using oidc credential forwarding", role="middle"] In the example above, _Carol_ logs in to *DBMS A* through an OIDC compliant identity provider by offering a token from the provider. -The token is used to set the username and determine the identity provider groups of the user. +The token is used to set the username and determine the identity provider groups of the user. + _Alice_ is the admin of *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `remote-neo4j`, to connect to the remote database `Db1`. Additionally, _Bob_ needs to configure the *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. _Bob_ also needs to configure the mapping of the identity provider groups to the Neo4j roles such that the _Carol's_ identity provider groups gives the appropriate privileges to access `Db1` on the *DBMS B*. @@ -221,14 +222,15 @@ Additionally, _Bob_ needs to configure the *DBMS B* to support SSO with the same [CAUTION] ==== While it is possible to use different OIDC configurations across distinct DBMS instances (DBMS A & B in this example), database administrators must be aware of the resulting privilege disparity. -A user's effective permissions are not dictated by the identity provider groups alone, but by the mapping of those groups to the roles defined within each specific Neo4j DBMS, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. +A user's effective permissions are not dictated by the identity provider groups alone, but by the mapping of those groups to the roles defined within each specific Neo4j DBMS. +See xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. + Crucially, if the OIDC configuration settings differ between the local DBMS and the target DBMS, the user will have different effective privileges on those systems. This configuration independence can lead to privilege inconsistency (e.g., over-privileging or unexpected access denial). ==== === 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: @@ -313,7 +315,7 @@ For details on how to map identity provider groups to Neo4j roles, see xref:auth [NOTE] ==== -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. +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. ==== @@ -324,8 +326,8 @@ A user can connect to a remote database alias the same way they would do to a da This includes: * Connecting directly to the remote database alias. -* The Cypher link:{neo4j-docs-base-uri}/cypher-manual/current/clauses/use[`USE` clause] enables a user to query a remote database alias that they are not directly connected to: - +* Querying a remote database alias that they are not directly connected to using the Cypher link:{neo4j-docs-base-uri}/cypher-manual/current/clauses/use[`USE` clause]: ++ [source, Cypher] ---- USE `remote-neo4j` MATCH (n) RETURN * @@ -340,20 +342,15 @@ See more about xref:authentication-authorization/dbms-administration/dbms-user-m ALTER USER alice SET HOME DATABASE `remote-neo4j` ---- -[NOTE] -==== -Remote alias transactions will not be visible in `SHOW TRANSACTIONS` on **DBMS A**. +== Important notes + + +* 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. -==== -[NOTE] -==== -Action on the remote DBMS are all attributed to the user configured for the remote database alias. + +* Action on the remote DBMS are all attributed to the user configured for the remote database alias. In the case of using `STORED NATIVE CREDENTIALS`, the same credentials are used to connect to the remote DBMS independent on which end-user made the query targeting the remote alias. This will result in the stored native user being logged in the audit trails on the remote DBMS for all queries using the remote database alias. When using `OIDC CREDENTIAL FORWARDING` the actual end-user's credentials and permissions will be used, this will result in per-user audit trails being logged on the remote DBMS. -==== -[NOTE] -==== -When using a remote database alias with OIDC credential forwarding, the user needs to be logged in to the local DBMS with OIDC, otherwise there is no token to forward and the access to the remote database will be denied with `GQLSTATUS 42NFF`. -==== \ No newline at end of file +* When using a remote database alias with OIDC credential forwarding, the user needs to be logged in to the local DBMS with OIDC, otherwise there is no token to forward and the access to the remote database will be denied with GQLSTATUS link:https://neo4j.com/docs/status-codes/current/errors/gql-errors/42NFF/[`42NFF`]. \ No newline at end of file From 3095df544f8c3cd5dee15e6f47e335ed061dd189 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 27 Nov 2025 16:18:23 +0000 Subject: [PATCH 06/24] add the diagram file --- ...-alias-credential-forwarding-overview1.svg | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 modules/ROOT/images/remote-alias-credential-forwarding-overview1.svg diff --git a/modules/ROOT/images/remote-alias-credential-forwarding-overview1.svg b/modules/ROOT/images/remote-alias-credential-forwarding-overview1.svg new file mode 100644 index 000000000..2954180c6 --- /dev/null +++ b/modules/ROOT/images/remote-alias-credential-forwarding-overview1.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From f68e2e309d54601bbc6c5925c6583f171f110be5 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 2 Dec 2025 11:21:11 +0000 Subject: [PATCH 07/24] Editorial changes --- ...e-alias-credential-forwarding-overview.svg | 110 +++++----- ...-alias-credential-forwarding-overview1.svg | 56 ----- modules/ROOT/images/remote-alias-overview.svg | 83 ++++---- .../manage-aliases-standard-databases.adoc | 13 +- .../remote-database-alias-configuration.adoc | 192 +++++++++--------- 5 files changed, 203 insertions(+), 251 deletions(-) delete mode 100644 modules/ROOT/images/remote-alias-credential-forwarding-overview1.svg diff --git a/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg b/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg index cfa7cc9f0..3b190f551 100644 --- a/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg +++ b/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg @@ -1,56 +1,56 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/modules/ROOT/images/remote-alias-credential-forwarding-overview1.svg b/modules/ROOT/images/remote-alias-credential-forwarding-overview1.svg deleted file mode 100644 index 2954180c6..000000000 --- a/modules/ROOT/images/remote-alias-credential-forwarding-overview1.svg +++ /dev/null @@ -1,56 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/modules/ROOT/images/remote-alias-overview.svg b/modules/ROOT/images/remote-alias-overview.svg index d51cdcda9..71da57bd5 100644 --- a/modules/ROOT/images/remote-alias-overview.svg +++ b/modules/ROOT/images/remote-alias-overview.svg @@ -1,42 +1,43 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc index 2a4e17011..4076852b8 100644 --- a/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc +++ b/modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc @@ -119,7 +119,7 @@ If a user has not been granted the `ACCESS` privilege to the target database and | {check-mark} | credentials -| label:new[Introduced in 2025.10] The type of credentials used to connect to the remote database, either `STORED NATIVE CREDENTIALS` or `OIDC CREDENTIAL FORWARDING`, or null if the target database is local. +| label:new[Introduced in 2025.x] The type of credentials used to connect to the remote database, either `STORED NATIVE CREDENTIALS` or `OIDC CREDENTIAL FORWARDING`, or null if the target database is local. | STRING | {check-mark} @@ -405,7 +405,7 @@ When creating a remote database alias, you need to specify the credentials used You can choose between two types of credentials: * `STORED NATIVE CREDENTIALS`, using the credentials of a single native user on the remote DBMS. -* label:new[Introduced in 2025.10] `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local DBMS. +* label:new[Introduced in 2025.x] `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local DBMS. The user must be logged in with an identity provider supporting OIDC. You can also use `IF EXISTS` or `OR REPLACE` when creating remote database aliases. @@ -426,7 +426,8 @@ USER alice PASSWORD 'example_secret' ---- -You can verify that the remote database alias has been created correctly by using the `SHOW ALIASES FOR DATABASE` command: +Verify that the remote database alias has been created correctly using the `SHOW ALIASES FOR DATABASE` command: + .Query [source, cypher] ---- @@ -487,7 +488,7 @@ This is the list of the allowed driver settings for remote database aliases: * `ssl_enforced` (Default: `true`) -- SSL for remote database alias drivers is configured through the target URL scheme. If `ssl_enforced` is set to true, a secure URL scheme is enforced. -It is be validated when the command is executed. +It will be validated when the command is executed. * `connection_timeout` (For details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection.connect_timeout[dbms.routing.driver.connection.connect_timeout].) * `connection_max_lifetime` (For details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection.max_lifetime[dbms.routing.driver.connection.max_lifetime].) * connection_pool_acquisition_timeout -- for details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection.pool.acquisition_timeout[dbms.routing.driver.connection.pool.acquisition_timeout]. @@ -688,12 +689,12 @@ In this case, by not repeating the driver setting `connection_pool_max_size`, th [role=label--new-2025.10] === Alter a remote database alias credential type -Changing a remote database alias credential type (`STORED NATIVE CREDENTIALS` or `OIDC CREDENTIAL FORWARDING`) using the `ALTER ALIAS` command is currently not supported +Changing a remote database alias credential type (`STORED NATIVE CREDENTIALS` or `OIDC CREDENTIAL FORWARDING`) using the `ALTER ALIAS` command is currently not supported. To change the type of credentials, you must drop the remote database alias and replace it with a new one. [CAUTION] ==== -Any associated privileges, driver settings and other properties will be lost when dropping the alias and need to be respecified for the new one. +Any associated privileges, driver settings, and other properties will be lost when dropping the alias, and need to be respecified for the new one. See xref:authentication-authorization/database-administration.adoc[Database privileges] on how to manage access to the remote database alias and other privileges. ==== diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index bf63f4c1f..6631af71a 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -22,53 +22,50 @@ By creating a remote alias, you define: When creating the remote database alias, it can be configured to authenticate with either: * `STORED NATIVE CREDENTIALS`, the credentials of a single native user on the remote *DBMS B*. -* label:new[Introduced in 2025.10] `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local *DBMS A*. The user needs to be logged in with an identity provider supporting OIDC. +* label:new[Introduced in 2025.x] `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local *DBMS A*. +The user needs to be logged in with an identity provider supporting OIDC. [[setup-example-stored-native-credentials]] == Setup example with stored native credentials -In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_: +In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_. image::remote-alias-overview.svg[title="Overview of the required remote database alias setup when using stored credentials", role="middle"] - -[TIP] -==== A remote database alias is only accessible to users with appropriate privileges. -In this example, _Bob_ is the administrator responsible for deciding which databases (`Db1` or `Db2`) the remote aliases can write and/or read. +In this example, _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 xref:authentication-authorization/dbms-administration/index.adoc[DBMS 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. + +_Carol_ can use her own regular credentials to access the remote database `db1` in *DBMS B* after _Alice_ assigns this privilege to her user profile. +This configuration will also allow _Carol_ to access `db2` in *DBMS B*, if _Bob_ grants the necessary privileges to the user profile shared with _Alice_. See xref:authentication-authorization/index.adoc[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: +As _Bob_, you are responsible for setting up the remote DBMS, which includes the following steps: . Create the user profile to share with _Alice_. . Define the permissions for the user. -If you do not 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`. +(If you do not 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. [source, Example Setup Administrator B] ---- CREATE USER alice SET PASSWORD 'secretpassword' CREATE ROLE remote -GRANT ACCESS ON DATABASE neo4j TO remote -GRANT MATCH {*} ON GRAPH neo4j TO remote +GRANT ACCESS ON DATABASE db1 TO remote +GRANT MATCH {*} ON GRAPH db1 TO remote GRANT ROLE remote TO alice ---- -In this case, _Bob_ must do the required setup for the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts a non-local connection if required. +In this case, you must also set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. [source, Example of additional configuration] ---- @@ -89,27 +86,26 @@ server.bolt.tls_level=REQUIRED [[remote-alias-config-DBMS_admin-A]] === 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. +As _Alice_, you are responsible for setting up the DBMS with the remote database alias, which includes the following steps: +. 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, you must provide an AES encryption key of length 256 and store it in a password-protected keystore in the PKCS12 format. ++ The key can be generated by using the following keytool command in your terminal, which is included in link:https://docs.oracle.com/en/java/javase/11/tools/keytool.html[Java Platform, Standard Edition]: - ++ [source] ---- keytool -genseckey -keyalg aes -keysize 256 -storetype pkcs12 -keystore [keystore-name] -alias [key-name] -storepass [keystore-password] ---- - -[NOTE] ++ +[TIP] ==== -It is recommended to generate the keystore on the same Java version on which Neo4j is run, as the supported encryption algorithms may vary. +It is recommended to generate the keystore using the same Java version as the one on which Neo4j is run, as the supported encryption algorithms may vary. For details on the version of Java required by Neo4j, see link:https://neo4j.com/docs/operations-manual/current/installation/requirements/#deployment-requirements-java[System requirements -> Java]. ==== - -The following configuration is necessary for creating a remote database alias: - +. Configure the following settings to create the remote database alias: ++ [options="header" cols="m,a"] |=== | Configuration | Description @@ -118,16 +114,15 @@ The following configuration is necessary for creating a remote database alias: | xref:configuration/configuration-settings.adoc#config_dbms.security.keystore.password[`dbms.security.keystore.password`] | The password to the keystore file. Use xref:configuration/command-expansion.adoc[Command expansion] to set the password. | xref:configuration/configuration-settings.adoc#config_dbms.security.key.name[`dbms.security.key.name`] | The name of the secret key |=== - ++ [CAUTION] ==== -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. +To prevent unauthorized access, you must store the keystore file in a trusted location. +This is the main way to protect the encrypted passwords that will be stored in the `system` database. +It must not 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. - +In a cluster, you must share the same keystore file among all servers. For example, these would be valid additions to the config when using the suggested keytool command: [source] @@ -145,7 +140,7 @@ Where `password.sh` might look like this: 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: +Additionally, do not forget to change the permissions of the configuration file and start Neo4j with the command expansion flag: [source] ---- @@ -155,34 +150,38 @@ bin/neo4j start --expand-commands === Manage remote database aliases -You can use the xref:database-administration/aliases/manage-aliases-standard-databases.adoc[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. +To be able to manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management] +or xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges. -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 with stored native credentials: +For example, the following command grants the permission to create an alias to the `administrator` role: [source, Cypher] ---- -CREATE ALIAS `remote-neo4j` FOR DATABASE `neo4j` AT "neo4j+s://location:7687" USER alice PASSWORD 'secretpassword' +GRANT CREATE ALIAS ON DBMS TO administrator ---- -In order to do so, either xref:authentication-authorization/dbms-administration/dbms-database-management-privileges.adoc[database management] -or xref:authentication-authorization/dbms-administration/dbms-alias-management-privileges.adoc[alias management] privileges are required. -The permission to create an alias can be granted using the following command: +And here is how to grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias: [source, Cypher] ---- -GRANT CREATE ALIAS ON DBMS TO administrator +GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote ---- -Here is how to grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias: +Once you have all privileges in place, you can use the xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias commands] to manage remote database aliases. +It is strongly recommended to connect to a remote database alias with a secured connection. + +[NOTE] +==== +Note that only client-side SSL is supported. +By default, remote aliases require a secured URI scheme such as `neo4j+s`. +However, if you want to disable the secure URL scheme, you can set the driver setting `ssl_enforced` to `false`. +==== + +For example, you can use the following command to create a remote database alias with stored native credentials: [source, Cypher] ---- -GRANT ACCESS ON DATABASE `remote-neo4j` TO role +CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER alice PASSWORD 'secretpassword' ---- [NOTE] @@ -193,31 +192,33 @@ This prevents issues such as a transaction executing against multiple target dat === 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. +Changing the encryption key in the keystore requires updating the encrypted credentials for all existing remote database aliases, as they will no longer be readable with the new key. [NOTE] ==== -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 of 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. ==== -[role=label--new-2025.10] +[role=label--new-2025.x] [[setup-example-credential-forwarding]] == Setup example with OIDC credential forwarding -In order to use OIDC credential forwarding, both *DBMS A* and *DBMS B* need to support the same OIDC identity provider. +In order to use OIDC credential forwarding, both *DBMS A* and *DBMS B* must support the same OIDC identity provider. See the xref:authentication-authorization/sso-integration.adoc[SSO integration] on how to enable OIDC. -In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_: +In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_. + +image::remote-alias-credential-forwarding-overview.svg[title="Overview of the required remote database alias setup when using oidc credential forwarding", role="middle"] -image::remote-alias-credential-forwarding-overview1.svg[title="Overview of the required remote database alias setup when using oidc credential forwarding", role="middle"] +_Carol_ logs into *DBMS A* through an OIDC-compliant identity provider by offering a token from the provider. +The token is used to set the username and determine the identity provider groups to which the user belongs. -In the example above, _Carol_ logs in to *DBMS A* through an OIDC compliant identity provider by offering a token from the provider. -The token is used to set the username and determine the identity provider groups of the user. + -_Alice_ is the admin of *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `remote-neo4j`, to connect to the remote database `Db1`. -Additionally, _Bob_ needs to configure the *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. _Bob_ also needs to configure the mapping of the identity provider groups to the Neo4j roles such that the _Carol's_ identity provider groups gives the appropriate privileges to access `Db1` on the *DBMS B*. +_Alice_ is the admin of *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `db1-remote-alias` to connect to the remote database `db1`. +_Bob_ configures the *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. +He also configures the mapping of the identity provider groups to the Neo4j roles such that the _Carol's_ identity provider groups grant the appropriate privileges to access `db1` on the *DBMS B*. [CAUTION] ==== @@ -231,13 +232,12 @@ This configuration independence can lead to privilege inconsistency (e.g., over- === 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: +As _Bob_, you are responsible for setting up the remote DBMS, which includes the following steps: . Set up SSO and support for the identity provider. -. Map the identity provider groups to the Neo4j roles. If you don’t want specific users to access `Db2`, here is where you set it. See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. - -Additionally, _Bob_ must do the required setup for the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts a non-local connection if required. +. Map the identity provider groups to the Neo4j roles. +If you do not want specific users to access `db2`, here is where you set it. See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. +. Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. [source, Example of additional configuration] ---- @@ -264,10 +264,12 @@ dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = === Configure a DBMS with a remote database alias (_Alice_) -The steps _Alice_, need to take are: +As _Alice_, you are responsible for setting up the DBMS with the remote database alias, which includes the following steps: . Set up SSO and support for the identity provider. -. Map the identity provider groups to the Neo4j roles. This is where the permission to use the remote database alias is set. See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. +. Map the identity provider groups to the Neo4j roles. +This is where the permission to use the remote database alias is set. + See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. [source, Example of additional configuration] ---- @@ -280,53 +282,56 @@ dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = ---- === Manage remote database aliases -You can use the xref:database-administration/aliases/manage-aliases-standard-databases.adoc[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`. +To be able to manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management] +or xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges. -For example, the following command can be used to create a remote database alias with OIDC credential forwarding: +For example, the following command grants the permission to create an alias to the `administrator` role: [source, Cypher] ---- -CREATE ALIAS `remote-neo4j` FOR DATABASE `neo4j` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING +GRANT CREATE ALIAS ON DBMS TO administrator ---- -In order to do so, either xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management] -or xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges are required. -The permission to create an alias can be granted like this: +And here is how to grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias: [source, Cypher] ---- -GRANT CREATE ALIAS ON DBMS TO administrator +GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote ---- -Here is how to grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias: +In order for _Carol_ to get access to the remote database alias, she needs to be in an identity provider group that is mapped to a Neo4j role that is granted access to alias. +In this example, if _Carol_ is in the identity provider group `engineers`, which is mapped to the `admin` role, she will get the privileges of an `admin` and access to `db1-remote-alias`. +For details on how to map identity provider groups to Neo4j roles, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. + +Once you have all privileges in place, you can use the xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias commands] to manage remote database aliases. +It is strongly recommended to connect to a remote database alias with a secured connection. + +[NOTE] +==== +Note that only client-side SSL is supported. +By default, remote aliases require a secured URI scheme such as `neo4j+s`. +However, if you want to disable the secure URL scheme, you can set the driver setting `ssl_enforced` to `false`. +==== + +For example, you can use the following command to create a remote database alias with OIDC credential forwarding: [source, Cypher] ---- -GRANT ACCESS ON DATABASE `remote-neo4j` TO admin +CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING ---- -In order for _Carol_ to get access to the remote database alias, she needs to be in an identity provider group that is mapped to a Neo4j role that is granted access to alias. In this example, if _Carol_ is in the identity provider group `engineers` which is mapped to the `admin` role, she will get the privileges of an `admin` and access to `remote-neo4j`. -For details on how to map identity provider groups to Neo4j roles, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. - [NOTE] ==== 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. ==== - == 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: +You can connect to a remote database alias the same way as you would connect to a standard database using any of the following options: * Connecting directly to the remote database alias. -* Querying a remote database alias that they are not directly connected to using the Cypher link:{neo4j-docs-base-uri}/cypher-manual/current/clauses/use[`USE` clause]: +* Querying a remote database alias that you are not directly connected to using the Cypher link:{neo4j-docs-base-uri}/cypher-manual/current/clauses/use[`USE` clause]: + [source, Cypher] ---- @@ -339,18 +344,19 @@ See more about xref:authentication-authorization/dbms-administration/dbms-user-m [source, Cypher] ---- -ALTER USER alice SET HOME DATABASE `remote-neo4j` +ALTER USER alice SET HOME DATABASE `db1-remote-alias` ---- == Important notes +When using remote database aliases, keep in mind that: * 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. +* Actions on the remote *DBMS B* are all attributed to the user configured for the remote database alias. +In the case of using `STORED NATIVE CREDENTIALS`, the same credentials are used to connect to the remote DBMS regardless of which end-user made the query targeting the remote alias. +This will result in the stored native user being logged in the audit trails on the remote DBMS for all queries using the remote database alias. +When using `OIDC CREDENTIAL FORWARDING`, the actual end-user's credentials and permissions are used, resulting in per-user audit trails being logged on the remote DBMS. -* Action on the remote DBMS are all attributed to the user configured for the remote database alias. -In the case of using `STORED NATIVE CREDENTIALS`, the same credentials are used to connect to the remote DBMS independent on which end-user made the query targeting the remote alias. This will result in the stored native user being logged in the audit trails on the remote DBMS for all queries using the remote database alias. -When using `OIDC CREDENTIAL FORWARDING` the actual end-user's credentials and permissions will be used, this will result in per-user audit trails being logged on the remote DBMS. - -* When using a remote database alias with OIDC credential forwarding, the user needs to be logged in to the local DBMS with OIDC, otherwise there is no token to forward and the access to the remote database will be denied with GQLSTATUS link:https://neo4j.com/docs/status-codes/current/errors/gql-errors/42NFF/[`42NFF`]. \ No newline at end of file +* When using a remote database alias with OIDC credential forwarding, the user needs to be logged in to the local DBMS with OIDC, otherwise there is no token to forward, and the access to the remote database will be denied with GQLSTATUS link:https://neo4j.com/docs/status-codes/current/errors/gql-errors/42NFF/[`42NFF`]. \ No newline at end of file From b23d74e2947b8ab1ea27a8f0ff6c93e50f840b4f Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 2 Dec 2025 11:21:48 +0000 Subject: [PATCH 08/24] replace the diagrams --- ...ias-credential-forwarding-overview-old.svg | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 modules/ROOT/images/remote-alias-credential-forwarding-overview-old.svg diff --git a/modules/ROOT/images/remote-alias-credential-forwarding-overview-old.svg b/modules/ROOT/images/remote-alias-credential-forwarding-overview-old.svg new file mode 100644 index 000000000..cfa7cc9f0 --- /dev/null +++ b/modules/ROOT/images/remote-alias-credential-forwarding-overview-old.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From e680761396a07837d5cd783d464dc6618f04f544 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 2 Dec 2025 16:48:57 +0000 Subject: [PATCH 09/24] further editorial changes to fix inconsistencies --- .../remote-database-alias-configuration.adoc | 41 +++++++++++-------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index 6631af71a..a0bfbf246 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -34,7 +34,7 @@ In this example, _Alice_ is an administrator and _Carol_ is a user who needs acc image::remote-alias-overview.svg[title="Overview of the required remote database alias setup when using stored credentials", role="middle"] A remote database alias is only accessible to users with appropriate privileges. -In this example, _Bob_ is the administrator responsible for deciding which databases (`db1` or `db2`) the remote aliases can write and/or read. +In this example, _Bob_ is the administrator responsible for deciding which database (`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_. @@ -48,7 +48,7 @@ See xref:authentication-authorization/index.adoc[Authentication and authorizatio === Configure a remote DBMS (_Bob_) -As _Bob_, you are responsible for setting up the remote DBMS, which includes the following steps: +As _Bob_, you are responsible for setting up the remote *DBMS B*, which includes the following steps: . Create the user profile to share with _Alice_. . Define the permissions for the user. @@ -56,7 +56,8 @@ As _Bob_, you are responsible for setting up the remote DBMS, which includes the . 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. -[source, Example Setup Administrator B] +.Example setup administrator B +[source, Cypher] ---- CREATE USER alice SET PASSWORD 'secretpassword' CREATE ROLE remote @@ -67,7 +68,8 @@ GRANT ROLE remote TO alice In this case, you must also set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. -[source, Example of additional configuration] +.Example of additional configuration +[parameters] ---- # accept non-local connections server.default_listen_address=0.0.0.0 @@ -112,7 +114,7 @@ For details on the version of Java required by Neo4j, see link:https://neo4j.com | xref:configuration/configuration-settings.adoc#config_dbms.security.keystore.path[`dbms.security.keystore.path`] | The absolute path to the keystore file, including the file name. | xref:configuration/configuration-settings.adoc#config_dbms.security.keystore.password[`dbms.security.keystore.password`] | The password to the keystore file. Use xref:configuration/command-expansion.adoc[Command expansion] to set the password. -| xref:configuration/configuration-settings.adoc#config_dbms.security.key.name[`dbms.security.key.name`] | The name of the secret key +| xref:configuration/configuration-settings.adoc#config_dbms.security.key.name[`dbms.security.key.name`] | The name of the secret key. |=== + [CAUTION] @@ -125,7 +127,7 @@ It must not be accessible to any user except for the administrator and `neo4j`, In a cluster, you must share the same keystore file among all servers. For example, these would be valid additions to the config when using the suggested keytool command: -[source] +[parameters] ---- dbms.security.keystore.path=/home/secure-folder/keystore-name.pkcs12 dbms.security.keystore.password=$(conf/password.sh) @@ -134,7 +136,8 @@ dbms.security.key.name=key-name Where `password.sh` might look like this: -[source, Password.sh] +.Password.sh +[source, bash] ---- #!/bin/bash echo "$KEYSTORE_PASSWORD_ENVIRONMENT_VARIABLE" @@ -142,7 +145,7 @@ echo "$KEYSTORE_PASSWORD_ENVIRONMENT_VARIABLE" Additionally, do not forget to change the permissions of the configuration file and start Neo4j with the command expansion flag: -[source] +[source, bash] ---- chmod 640 conf/neo4j.conf bin/neo4j start --expand-commands @@ -215,7 +218,7 @@ image::remote-alias-credential-forwarding-overview.svg[title="Overview of the re _Carol_ logs into *DBMS A* through an OIDC-compliant identity provider by offering a token from the provider. The token is used to set the username and determine the identity provider groups to which the user belongs. -_Alice_ is the admin of *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `db1-remote-alias` to connect to the remote database `db1`. +_Alice_ is the admin of *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `db1-remote-alias`, to connect to the remote database `db1`. _Bob_ configures the *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. He also configures the mapping of the identity provider groups to the Neo4j roles such that the _Carol's_ identity provider groups grant the appropriate privileges to access `db1` on the *DBMS B*. @@ -232,14 +235,15 @@ This configuration independence can lead to privilege inconsistency (e.g., over- === Configure a remote DBMS (_Bob_) -As _Bob_, you are responsible for setting up the remote DBMS, which includes the following steps: +As _Bob_, you are responsible for setting up the remote *DBMS B*, which includes the following steps: . Set up SSO and support for the identity provider. . Map the identity provider groups to the Neo4j roles. If you do not want specific users to access `db2`, here is where you set it. See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. . Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. -[source, Example of additional configuration] +.Example of additional configuration +[parameters] ---- # accept non-local connections server.default_listen_address=0.0.0.0 @@ -264,14 +268,15 @@ dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = === Configure a DBMS with a remote database alias (_Alice_) -As _Alice_, you are responsible for setting up the DBMS with the remote database alias, which includes the following steps: +As _Alice_, you are responsible for setting up the *DBMS A* with the remote database alias, which includes the following steps: . Set up SSO and support for the identity provider. . Map the identity provider groups to the Neo4j roles. This is where the permission to use the remote database alias is set. - See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. +See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. -[source, Example of additional configuration] +.Example of additional configuration +[parameters] ---- # OIDC settings - these should be the same on both DBMSs dbms.security.oidc..well_known_discovery_uri=http://example.com/.well-known/discovery @@ -335,13 +340,13 @@ You can connect to a remote database alias the same way as you would connect to + [source, Cypher] ---- -USE `remote-neo4j` MATCH (n) RETURN * +USE `db1-remote-alias` MATCH (n) RETURN * ---- * Connecting to a remote database alias as a home database. -This needs to be set by Administrator A. -See more about xref:authentication-authorization/dbms-administration/dbms-user-management-privileges.adoc[User Management]. - +This needs to be set by an administrator. +See xref:authentication-authorization/dbms-administration/dbms-user-management-privileges.adoc[User Management] for more information. ++ [source, Cypher] ---- ALTER USER alice SET HOME DATABASE `db1-remote-alias` From 9de18d7bff1d39f4929a9b3a4a6701228dd8d422 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 4 Dec 2025 16:20:16 +0000 Subject: [PATCH 10/24] update the diagrams --- ...ias-credential-forwarding-overview-old.svg | 56 --------- ...e-alias-credential-forwarding-overview.svg | 110 +++++++++--------- modules/ROOT/images/remote-alias-overview.svg | 84 ++++++------- 3 files changed, 97 insertions(+), 153 deletions(-) delete mode 100644 modules/ROOT/images/remote-alias-credential-forwarding-overview-old.svg diff --git a/modules/ROOT/images/remote-alias-credential-forwarding-overview-old.svg b/modules/ROOT/images/remote-alias-credential-forwarding-overview-old.svg deleted file mode 100644 index cfa7cc9f0..000000000 --- a/modules/ROOT/images/remote-alias-credential-forwarding-overview-old.svg +++ /dev/null @@ -1,56 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg b/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg index 3b190f551..d96b28a26 100644 --- a/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg +++ b/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg @@ -1,56 +1,56 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/modules/ROOT/images/remote-alias-overview.svg b/modules/ROOT/images/remote-alias-overview.svg index 71da57bd5..7da5e4f8e 100644 --- a/modules/ROOT/images/remote-alias-overview.svg +++ b/modules/ROOT/images/remote-alias-overview.svg @@ -1,43 +1,43 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 90e623490ec070487c52692649034dc26c047cf0 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 4 Dec 2025 16:28:27 +0000 Subject: [PATCH 11/24] apply some suggestions from review --- .../remote-database-alias-configuration.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index a0bfbf246..7e1cdf835 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -10,12 +10,12 @@ Although remote database aliases do not store any data, they enable users or app All configurations can be done using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[administrative commands] on a running system. Any changes are automatically synchronized across all members of a cluster. -The following steps describe the setup required to define a remote database alias for both local and remote DBMSs. -They assume that you have already installed and started both DBMSs: a local *DBMS A* and a remote *DBMS B*, and that you have administrator access to both systems. +The following examples describe how to set up a remote database alias in two different ways: using stored native credentials and using OIDC credential forwarding. +It is assumed that you have two separate DBMS instances: a local *DBMS A* and a remote *DBMS B*. By creating a remote alias, you define: -* Which user of the remote *DBMS B* is used. +* Which user of the remote *DBMS B* can access the remote alias. * Where the remote database is located. * How to connect to the remote database using driver settings. @@ -31,7 +31,7 @@ The user needs to be logged in with an identity provider supporting OIDC. In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_. -image::remote-alias-overview.svg[title="Overview of the required remote database alias setup when using stored credentials", role="middle"] +image::remote-alias-overview.svg[title="Overview of the required remote database alias setup when using stored native credentials", role="middle"] A remote database alias is only accessible to users with appropriate privileges. In this example, _Bob_ is the administrator responsible for deciding which database (`db1` or `db2`) the remote aliases can write and/or read. @@ -213,14 +213,14 @@ See the xref:authentication-authorization/sso-integration.adoc[SSO integration] In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_. -image::remote-alias-credential-forwarding-overview.svg[title="Overview of the required remote database alias setup when using oidc credential forwarding", role="middle"] +image::remote-alias-credential-forwarding-overview.svg[title="Overview of the required remote database alias setup when using OIDC credential forwarding", role="middle"] -_Carol_ logs into *DBMS A* through an OIDC-compliant identity provider by offering a token from the provider. +_Carol_ logs into the local *DBMS A* through an OIDC-compliant identity provider by offering a token from the provider. The token is used to set the username and determine the identity provider groups to which the user belongs. -_Alice_ is the admin of *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `db1-remote-alias`, to connect to the remote database `db1`. +_Alice_ is the admin of the local *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `db1-remote-alias`, to connect to the remote database `db1`. -_Bob_ configures the *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. +_Bob_ configures the remote *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. He also configures the mapping of the identity provider groups to the Neo4j roles such that the _Carol's_ identity provider groups grant the appropriate privileges to access `db1` on the *DBMS B*. [CAUTION] From 8f21930fb035bd1852a842318d7ecfdcf9c44ca7 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 5 Dec 2025 13:35:41 +0000 Subject: [PATCH 12/24] apply suggestions from review --- .../aliases/remote-database-alias-configuration.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index 7e1cdf835..b5f65614a 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -125,7 +125,7 @@ It must not be accessible to any user except for the administrator and `neo4j`, ==== In a cluster, you must share the same keystore file among all servers. -For example, these would be valid additions to the config when using the suggested keytool command: +For example, these would be valid additions to the configuration when using the suggested keytool command: [parameters] ---- @@ -151,7 +151,7 @@ chmod 640 conf/neo4j.conf bin/neo4j start --expand-commands ---- -=== Manage remote database aliases +=== Manage remote database aliases (_Carol_) To be able to manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management] or xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges. @@ -285,16 +285,16 @@ dbms.security.oidc..claims.groups=groups dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = admin; \ "collaborators" = reader ---- -=== Manage remote database aliases +=== Manage remote database aliases (_Carol_) To be able to manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management] or xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges. -For example, the following command grants the permission to create an alias to the `administrator` role: +For example, the following command grants the permission to create an alias to the `admin` role, which _Carol_ is a member of: [source, Cypher] ---- -GRANT CREATE ALIAS ON DBMS TO administrator +GRANT CREATE ALIAS ON DBMS TO admin ---- And here is how to grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias: @@ -364,4 +364,4 @@ In the case of using `STORED NATIVE CREDENTIALS`, the same credentials are used This will result in the stored native user being logged in the audit trails on the remote DBMS for all queries using the remote database alias. When using `OIDC CREDENTIAL FORWARDING`, the actual end-user's credentials and permissions are used, resulting in per-user audit trails being logged on the remote DBMS. -* When using a remote database alias with OIDC credential forwarding, the user needs to be logged in to the local DBMS with OIDC, otherwise there is no token to forward, and the access to the remote database will be denied with GQLSTATUS link:https://neo4j.com/docs/status-codes/current/errors/gql-errors/42NFF/[`42NFF`]. \ No newline at end of file +* When using a remote database alias with OIDC credential forwarding, the user needs to be logged into the local *DBMS A* with OIDC, otherwise there is no token to forward, and the access to the remote database will be denied with GQLSTATUS link:https://neo4j.com/docs/status-codes/current/errors/gql-errors/42NFF/[`42NFF`]. \ No newline at end of file From 79bd5b57afc83aae85497270cf86d17c0e4e594e Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 5 Dec 2025 14:19:22 +0000 Subject: [PATCH 13/24] fix broken links --- .../aliases/remote-database-alias-configuration.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index b5f65614a..3b9cbeec8 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -153,8 +153,8 @@ bin/neo4j start --expand-commands === Manage remote database aliases (_Carol_) -To be able to manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management] -or xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges. +To be able to manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration/dbms-database-management-privileges.adoc[database management] +or xref:authentication-authorization/dbms-administration/dbms-alias-management-privileges.adoc[alias management] privileges. For example, the following command grants the permission to create an alias to the `administrator` role: @@ -287,8 +287,8 @@ dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = ---- === Manage remote database aliases (_Carol_) -To be able to manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management] -or xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges. +To be able to manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration/dbms-database-management-privileges.adoc[database management] +or xref:authentication-authorization/dbms-administration/dbms-alias-management-privileges.adoc[alias management] privileges. For example, the following command grants the permission to create an alias to the `admin` role, which _Carol_ is a member of: From 331ca0e884ce5af4f1f26d02eb26294f047bee4a Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 9 Dec 2025 13:45:50 +0000 Subject: [PATCH 14/24] an attempt to incorporate the comments from the review --- .../remote-database-alias-configuration.adoc | 212 ++++++++++-------- 1 file changed, 115 insertions(+), 97 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index 3b9cbeec8..90b6f9313 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -10,10 +10,23 @@ Although remote database aliases do not store any data, they enable users or app All configurations can be done using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[administrative commands] on a running system. Any changes are automatically synchronized across all members of a cluster. -The following examples describe how to set up a remote database alias in two different ways: using stored native credentials and using OIDC credential forwarding. +[NOTE] +==== +To manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration/dbms-database-management-privileges.adoc[database management] +or xref:authentication-authorization/dbms-administration/dbms-alias-management-privileges.adoc[alias management] privileges. + +For example, the following command grants the permission to create an alias to the `administrator` role: + +[source, Cypher] +---- +GRANT CREATE ALIAS ON DBMS TO administrator +---- +==== + +The following examples describe how to set up access to a remote database via a remote database alias in two different ways: using stored native credentials and using OIDC credential forwarding. It is assumed that you have two separate DBMS instances: a local *DBMS A* and a remote *DBMS B*. -By creating a remote alias, you define: +By creating a remote database alias, you define: * Which user of the remote *DBMS B* can access the remote alias. * Where the remote database is located. @@ -29,7 +42,7 @@ The user needs to be logged in with an identity provider supporting OIDC. [[setup-example-stored-native-credentials]] == Setup example with stored native credentials -In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_. +In this example, _Alice_ is an administrator of *DBMS A*, _Bob_ is an administrator of *DBMS B*, and _Carol_ is a user who needs access to a database managed by _Bob_. image::remote-alias-overview.svg[title="Overview of the required remote database alias setup when using stored native credentials", role="middle"] @@ -42,32 +55,33 @@ See xref:authentication-authorization/dbms-administration/index.adoc[DBMS privil ==== -_Carol_ can use her own regular credentials to access the remote database `db1` in *DBMS B* after _Alice_ assigns this privilege to her user profile. +_Carol_ can use her own regular credentials to access the remote database `db1` in *DBMS B* after _Bob_ creates a user profile for her and shares the credentials with _Alice_. +Then, _Alice_ will be able to grant _Carol_ access to the remote database alias `db1-remote-alias` that connects to `db1` on *DBMS B* using the shared credentials. This configuration will also allow _Carol_ to access `db2` in *DBMS B*, if _Bob_ grants the necessary privileges to the user profile shared with _Alice_. See xref:authentication-authorization/index.adoc[Authentication and authorization] for further information. -=== Configure a remote DBMS (_Bob_) +=== Configure the remote DBMS (_Bob_) -As _Bob_, you are responsible for setting up the remote *DBMS B*, which includes the following steps: +As _Bob_, you are responsible for the remote *DBMS B*. +You can create and delete users and grant or deny privileges on the databases managed by *DBMS B*. + +In this example, you create a user called `alias_user`, which will be used by the remote database alias to connect to `db1`, and shares the credentials with _Alice_. . Create the user profile to share with _Alice_. . Define the permissions for the user. (If you do not 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. - ++ .Example setup administrator B [source, Cypher] ---- -CREATE USER alice SET PASSWORD 'secretpassword' +CREATE USER alias_user SET PASSWORD 'secretpassword' CREATE ROLE remote GRANT ACCESS ON DATABASE db1 TO remote GRANT MATCH {*} ON GRAPH db1 TO remote -GRANT ROLE remote TO alice +GRANT ROLE remote TO alias_user ---- - -In this case, you must also set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. - +. Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. ++ .Example of additional configuration [parameters] ---- @@ -84,30 +98,40 @@ dbms.ssl.policy.bolt.client_auth=NONE # enforcing ssl connection server.bolt.tls_level=REQUIRED ---- +. 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. [[remote-alias-config-DBMS_admin-A]] === Configure a DBMS with a remote database alias (_Alice_) -As _Alice_, you are responsible for setting up the DBMS with the remote database alias, which includes the following steps: +As _Alice_, you are responsible for setting up *DBMS А*. +You can create and delete the database aliases and grant or deny users' access to them. + +In this example, you create a remote database alias, called `db1-remote-alias`, which connects to `db1` on *DBMS B* using the credentials shared by _Bob_. -. Generate an encryption key. + +==== Generate an encryption key + +First, 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, you must provide an AES encryption key of length 256 and store it in a password-protected keystore in the PKCS12 format. -+ + The key can be generated by using the following keytool command in your terminal, which is included in link:https://docs.oracle.com/en/java/javase/11/tools/keytool.html[Java Platform, Standard Edition]: -+ + [source] ---- keytool -genseckey -keyalg aes -keysize 256 -storetype pkcs12 -keystore [keystore-name] -alias [key-name] -storepass [keystore-password] ---- -+ + [TIP] ==== It is recommended to generate the keystore using the same Java version as the one on which Neo4j is run, as the supported encryption algorithms may vary. For details on the version of Java required by Neo4j, see link:https://neo4j.com/docs/operations-manual/current/installation/requirements/#deployment-requirements-java[System requirements -> Java]. ==== -. Configure the following settings to create the remote database alias: -+ + +==== Configure the keystore settings + +After generating the keystore file, you need to configure *DBMS A* to use it by setting the following configuration parameters in the `neo4j.conf` file: + [options="header" cols="m,a"] |=== | Configuration | Description @@ -116,7 +140,7 @@ For details on the version of Java required by Neo4j, see link:https://neo4j.com | xref:configuration/configuration-settings.adoc#config_dbms.security.keystore.password[`dbms.security.keystore.password`] | The password to the keystore file. Use xref:configuration/command-expansion.adoc[Command expansion] to set the password. | xref:configuration/configuration-settings.adoc#config_dbms.security.key.name[`dbms.security.key.name`] | The name of the secret key. |=== -+ + [CAUTION] ==== To prevent unauthorized access, you must store the keystore file in a trusted location. @@ -151,40 +175,32 @@ chmod 640 conf/neo4j.conf bin/neo4j start --expand-commands ---- -=== Manage remote database aliases (_Carol_) +==== Create the remote database alias and grant access to Carol -To be able to manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration/dbms-database-management-privileges.adoc[database management] -or xref:authentication-authorization/dbms-administration/dbms-alias-management-privileges.adoc[alias management] privileges. - -For example, the following command grants the permission to create an alias to the `administrator` role: - -[source, Cypher] ----- -GRANT CREATE ALIAS ON DBMS TO administrator ----- - -And here is how to grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias: - -[source, Cypher] ----- -GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote ----- - -Once you have all privileges in place, you can use the xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias commands] to manage remote database aliases. -It is strongly recommended to connect to a remote database alias with a secured connection. +Finally, you create the remote database alias using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias administrative commands]. [NOTE] ==== +It is strongly recommended to connect to a remote database alias with a secured connection. Note that only client-side SSL is supported. By default, remote aliases require a secured URI scheme such as `neo4j+s`. However, if you want to disable the secure URL scheme, you can set the driver setting `ssl_enforced` to `false`. ==== -For example, you can use the following command to create a remote database alias with stored native credentials: +For example, you can use the following command to create a remote database alias with stored native credentials shared by _Bob_: + +[source, Cypher] +---- +CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER alias_user PASSWORD 'secretpassword' +---- + +Then, you can grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias to _Carol_: [source, Cypher] ---- -CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER alice PASSWORD 'secretpassword' +CREATE ROLE remote_access +GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access +GRANT ROLE remote_access TO Carol ---- [NOTE] @@ -193,7 +209,7 @@ If a transaction modifies an alias (e.g. changing the database targeted on *DBMS This prevents issues such as a transaction executing against multiple target databases for the same alias. ==== -=== Change the encryption key +==== Changing the encryption key Changing the encryption key in the keystore requires updating the encrypted credentials for all existing remote database aliases, as they will no longer be readable with the new key. @@ -210,15 +226,14 @@ In case it is not possible to connect to the remote alias after its creation, ve In order to use OIDC credential forwarding, both *DBMS A* and *DBMS B* must support the same OIDC identity provider. See the xref:authentication-authorization/sso-integration.adoc[SSO integration] on how to enable OIDC. - -In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_. +In this example, _Alice_ is an administrator of *DBMS A*, _Bob_ is an administrator of *DBMS B*, and _Carol_ is a user who needs access to a database managed by _Bob_. image::remote-alias-credential-forwarding-overview.svg[title="Overview of the required remote database alias setup when using OIDC credential forwarding", role="middle"] _Carol_ logs into the local *DBMS A* through an OIDC-compliant identity provider by offering a token from the provider. The token is used to set the username and determine the identity provider groups to which the user belongs. -_Alice_ is the admin of the local *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `db1-remote-alias`, to connect to the remote database `db1`. +_Alice_ is the administrator of the local *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `db1-remote-alias`, to connect to the remote database `db1`. _Bob_ configures the remote *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. He also configures the mapping of the identity provider groups to the Neo4j roles such that the _Carol's_ identity provider groups grant the appropriate privileges to access `db1` on the *DBMS B*. @@ -233,16 +248,30 @@ Crucially, if the OIDC configuration settings differ between the local DBMS and This configuration independence can lead to privilege inconsistency (e.g., over-privileging or unexpected access denial). ==== -=== Configure a remote DBMS (_Bob_) +=== Configure the remote DBMS B (_Bob_) -As _Bob_, you are responsible for setting up the remote *DBMS B*, which includes the following steps: +As _Bob_, you are responsible for setting up the remote *DBMS B*. +You can create and delete users and grant or deny privileges on the databases managed by *DBMS B*. -. Set up SSO and support for the identity provider. -. Map the identity provider groups to the Neo4j roles. -If you do not want specific users to access `db2`, here is where you set it. See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. -. Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. +In this example, you need to ensure that _Carol_ can access `db1` on *DBMS B* using OIDC credential forwarding. -.Example of additional configuration +. Set up SSO and support for the identity provider and map the identity provider groups to the Neo4j roles. +For details, see the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] and xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. +If you do not want specific users to access `db2`, here is where you set it. ++ +[parameters] +---- +# OIDC settings - these should be the same on both DBMSs +dbms.security.oidc..well_known_discovery_uri=http://example.com/.well-known/discovery +<...> +dbms.security.oidc..claims.groups=groups +dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = admin; \ + "collaborators" = reader; \ + "remote_users" = remote_access +---- + +. Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. ++ [parameters] ---- # accept non-local connections @@ -257,74 +286,63 @@ dbms.ssl.policy.bolt.client_auth=NONE # enforcing ssl connection server.bolt.tls_level=REQUIRED - -# OIDC settings - these should be the same on both DBMSs -dbms.security.oidc..well_known_discovery_uri=http://example.com/.well-known/discovery -<...> -dbms.security.oidc..claims.groups=groups -dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = admin; \ - "collaborators" = reader ---- -=== Configure a DBMS with a remote database alias (_Alice_) +=== Configure the local DBMS A (_Alice_) -As _Alice_, you are responsible for setting up the *DBMS A* with the remote database alias, which includes the following steps: +As _Alice_, you are responsible for setting up the local *DBMS A*. +You can create and delete the database aliases and grant or deny users' access to them. -. Set up SSO and support for the identity provider. -. Map the identity provider groups to the Neo4j roles. -This is where the permission to use the remote database alias is set. -See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. +In this case, you need to set up a remote database alias that connects to `db1` on *DBMS B* using OIDC credential forwarding and grant _Carol_ access to it. + +==== Set up SSO on the local DBMS and map the identity provider groups to the Neo4j roles + +In order for _Carol_ to get access to the remote database alias, she needs to be in an identity provider group that is mapped to a Neo4j role that is granted access to that alias. + +You set up SSO on the local *DBMS A* and map the identity provider groups to the Neo4j roles that match those on the remote *DBMS B*. +For details on how to map identity provider groups to Neo4j roles, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. -.Example of additional configuration [parameters] ---- -# OIDC settings - these should be the same on both DBMSs dbms.security.oidc..well_known_discovery_uri=http://example.com/.well-known/discovery <...> dbms.security.oidc..claims.groups=groups dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = admin; \ - "collaborators" = reader ----- -=== Manage remote database aliases (_Carol_) - -To be able to manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration/dbms-database-management-privileges.adoc[database management] -or xref:authentication-authorization/dbms-administration/dbms-alias-management-privileges.adoc[alias management] privileges. - -For example, the following command grants the permission to create an alias to the `admin` role, which _Carol_ is a member of: - -[source, Cypher] ----- -GRANT CREATE ALIAS ON DBMS TO admin ----- - -And here is how to grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias: - -[source, Cypher] ----- -GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote + "collaborators" = reader; \ + "remote_users" = remote_access ---- ++ +This is where the permission to use the remote database alias is set. +See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. -In order for _Carol_ to get access to the remote database alias, she needs to be in an identity provider group that is mapped to a Neo4j role that is granted access to alias. -In this example, if _Carol_ is in the identity provider group `engineers`, which is mapped to the `admin` role, she will get the privileges of an `admin` and access to `db1-remote-alias`. -For details on how to map identity provider groups to Neo4j roles, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. +==== Create the remote database alias and grant access to Carol -Once you have all privileges in place, you can use the xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias commands] to manage remote database aliases. -It is strongly recommended to connect to a remote database alias with a secured connection. +Finally, you create the remote database alias using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias administrative commands]. +. Create the remote database alias using OIDC credential forwarding: ++ [NOTE] ==== +It is strongly recommended to connect to a remote database alias with a secured connection. Note that only client-side SSL is supported. By default, remote aliases require a secured URI scheme such as `neo4j+s`. However, if you want to disable the secure URL scheme, you can set the driver setting `ssl_enforced` to `false`. ==== - -For example, you can use the following command to create a remote database alias with OIDC credential forwarding: - ++ [source, Cypher] ---- CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING ---- +. Grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias to _Carol_: ++ +[source, Cypher] +---- +CREATE ROLE remote_access +GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access +GRANT ROLE remote_access TO Carol +---- ++ [NOTE] ==== 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. From c6f1711fc34c2e150ce13bcd6d443dca59e30394 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 9 Dec 2025 14:04:00 +0000 Subject: [PATCH 15/24] remove a leftover formatting --- .../aliases/remote-database-alias-configuration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index 90b6f9313..bec24446c 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -52,7 +52,6 @@ Meanwhile, _Alice_ is the administrator that assigns who has access to the privi In the example, _Alice_ will assign that access to _Carol_. See xref:authentication-authorization/dbms-administration/index.adoc[DBMS privileges] for more information. -==== _Carol_ can use her own regular credentials to access the remote database `db1` in *DBMS B* after _Bob_ creates a user profile for her and shares the credentials with _Alice_. @@ -349,6 +348,7 @@ If a transaction modifies an alias (e.g. changing the database targeted on *DBMS This prevents issues such as a transaction executing against multiple target databases for the same alias. ==== + == Connect to remote database aliases You can connect to a remote database alias the same way as you would connect to a standard database using any of the following options: From 29a0070cbf2757db35fdb1fdf95c2cd55257ba07 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 9 Dec 2025 14:53:11 +0000 Subject: [PATCH 16/24] firther improvements --- .../remote-database-alias-configuration.adoc | 30 ++++++++++++------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index bec24446c..ca79646e0 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -28,7 +28,7 @@ It is assumed that you have two separate DBMS instances: a local *DBMS A* and a By creating a remote database alias, you define: -* Which user of the remote *DBMS B* can access the remote alias. +* Which user credentials of the remote *DBMS B* can access the remote database alias. * Where the remote database is located. * How to connect to the remote database using driver settings. @@ -56,25 +56,32 @@ See xref:authentication-authorization/dbms-administration/index.adoc[DBMS privil _Carol_ can use her own regular credentials to access the remote database `db1` in *DBMS B* after _Bob_ creates a user profile for her and shares the credentials with _Alice_. Then, _Alice_ will be able to grant _Carol_ access to the remote database alias `db1-remote-alias` that connects to `db1` on *DBMS B* using the shared credentials. -This configuration will also allow _Carol_ to access `db2` in *DBMS B*, if _Bob_ grants the necessary privileges to the user profile shared with _Alice_. -See xref:authentication-authorization/index.adoc[Authentication and authorization] for further information. +//This configuration will also allow _Carol_ to access `db2` in *DBMS B*, if _Bob_ grants the necessary privileges to the user profile shared with _Alice_. +//See xref:authentication-authorization/index.adoc[Authentication and authorization] for further information. -=== Configure the remote DBMS (_Bob_) +=== Configure the remote DBMS B (_Bob_) As _Bob_, you are responsible for the remote *DBMS B*. You can create and delete users and grant or deny privileges on the databases managed by *DBMS B*. In this example, you create a user called `alias_user`, which will be used by the remote database alias to connect to `db1`, and shares the credentials with _Alice_. -. Create the user profile to share with _Alice_. -. Define the permissions for the user. -(If you do not want this user to access `db2`, here is where you set it.) +. Create the user profile to share with _Alice_: + -.Example setup administrator B [source, Cypher] ---- CREATE USER alias_user SET PASSWORD 'secretpassword' +---- +. Create a custom role to track all users shared on a remote connection, so that they remain trackable: ++ +[source, Cypher] +---- CREATE ROLE remote +---- +. Grant the necessary privileges on `db1` to the custom role and assign the role to the user profile created for the remote database alias: ++ +[source, Cypher] +---- GRANT ACCESS ON DATABASE db1 TO remote GRANT MATCH {*} ON GRAPH db1 TO remote GRANT ROLE remote TO alias_user @@ -101,7 +108,7 @@ server.bolt.tls_level=REQUIRED It is recommended to create a custom role to track all users shared on a remote connection, so that they remain trackable. [[remote-alias-config-DBMS_admin-A]] -=== Configure a DBMS with a remote database alias (_Alice_) +=== Configure the local DBMS A and grant access to Carol (_Alice_) As _Alice_, you are responsible for setting up *DBMS А*. You can create and delete the database aliases and grant or deny users' access to them. @@ -287,7 +294,7 @@ dbms.ssl.policy.bolt.client_auth=NONE server.bolt.tls_level=REQUIRED ---- -=== Configure the local DBMS A (_Alice_) +=== Configure the local DBMS A and grant access to Carol (_Alice_) As _Alice_, you are responsible for setting up the local *DBMS A*. You can create and delete the database aliases and grant or deny users' access to them. @@ -333,7 +340,8 @@ However, if you want to disable the secure URL scheme, you can set the driver se CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING ---- -. Grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias to _Carol_: +. Create a role to grant access to the remote database alias and assign it to _Carol_. +See the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] for more information. + [source, Cypher] ---- From 4a756b353530645ae8f28a2d527caf4cfdfd9a47 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 9 Dec 2025 15:06:54 +0000 Subject: [PATCH 17/24] further improvements --- .../remote-database-alias-configuration.adoc | 37 +++++++++---------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index ca79646e0..fb067223e 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -10,6 +10,18 @@ Although remote database aliases do not store any data, they enable users or app All configurations can be done using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[administrative commands] on a running system. Any changes are automatically synchronized across all members of a cluster. +When creating the remote database alias, it can be configured to authenticate with either: + +* `STORED NATIVE CREDENTIALS`, the credentials of a single native user on the remote DBMS. +* label:new[Introduced in 2025.x] `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local DBMS. +The user needs to be logged in with an identity provider supporting OIDC. + +By creating a remote database alias, you define: + +* Which user credentials of the remote DBMS can access the remote database alias. +* Where the remote database is located. +* How to connect to the remote database using driver settings. + [NOTE] ==== To manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration/dbms-database-management-privileges.adoc[database management] @@ -23,21 +35,8 @@ GRANT CREATE ALIAS ON DBMS TO administrator ---- ==== -The following examples describe how to set up access to a remote database via a remote database alias in two different ways: using stored native credentials and using OIDC credential forwarding. -It is assumed that you have two separate DBMS instances: a local *DBMS A* and a remote *DBMS B*. - -By creating a remote database alias, you define: - -* Which user credentials of the remote *DBMS B* can access the remote database alias. -* Where the remote database is located. -* How to connect to the remote database using driver settings. - -When creating the remote database alias, it can be configured to authenticate with either: - -* `STORED NATIVE CREDENTIALS`, the credentials of a single native user on the remote *DBMS B*. -* label:new[Introduced in 2025.x] `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local *DBMS A*. -The user needs to be logged in with an identity provider supporting OIDC. - +The following examples describe how to set up access to a remote database via a remote database alias by using either stored native credentials, or OIDC credential forwarding. +They assume that you have two separate DBMS instances: a local *DBMS A* and a remote *DBMS B*. [[setup-example-stored-native-credentials]] == Setup example with stored native credentials @@ -88,7 +87,6 @@ GRANT ROLE remote TO alias_user ---- . Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. + -.Example of additional configuration [parameters] ---- # accept non-local connections @@ -166,7 +164,6 @@ dbms.security.key.name=key-name Where `password.sh` might look like this: -.Password.sh [source, bash] ---- #!/bin/bash @@ -382,12 +379,12 @@ ALTER USER alice SET HOME DATABASE `db1-remote-alias` When using remote database aliases, keep in mind that: -* Remote alias transactions will not be visible in `SHOW TRANSACTIONS` on *DBMS A*. +* Remote alias transactions will not be visible in `SHOW TRANSACTIONS` on the local DBMS. However, they can be accessed and terminated on the remote database when connecting with the same user. -* Actions on the remote *DBMS B* are all attributed to the user configured for the remote database alias. +* Actions on the remote DBMS are all attributed to the user configured for the remote database alias. In the case of using `STORED NATIVE CREDENTIALS`, the same credentials are used to connect to the remote DBMS regardless of which end-user made the query targeting the remote alias. This will result in the stored native user being logged in the audit trails on the remote DBMS for all queries using the remote database alias. When using `OIDC CREDENTIAL FORWARDING`, the actual end-user's credentials and permissions are used, resulting in per-user audit trails being logged on the remote DBMS. -* When using a remote database alias with OIDC credential forwarding, the user needs to be logged into the local *DBMS A* with OIDC, otherwise there is no token to forward, and the access to the remote database will be denied with GQLSTATUS link:https://neo4j.com/docs/status-codes/current/errors/gql-errors/42NFF/[`42NFF`]. \ No newline at end of file +* When using a remote database alias with OIDC credential forwarding, the user needs to be logged into the local DBMS with OIDC, otherwise there is no token to forward, and the access to the remote database will be denied with GQLSTATUS link:https://neo4j.com/docs/status-codes/current/errors/gql-errors/42NFF/[`42NFF`]. \ No newline at end of file From ba229565c3e56706f0ec8f702d69b14af73d8abc Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 9 Dec 2025 16:05:03 +0000 Subject: [PATCH 18/24] fixed a few more inconsistencies --- .../remote-database-alias-configuration.adoc | 45 ++++++++++--------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index fb067223e..f4c215f0d 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -48,7 +48,7 @@ image::remote-alias-overview.svg[title="Overview of the required remote database A remote database alias is only accessible to users with appropriate privileges. In this example, _Bob_ is the administrator responsible for deciding which database (`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_. +In the example, _Alice_ assigns that access to _Carol_. See xref:authentication-authorization/dbms-administration/index.adoc[DBMS privileges] for more information. @@ -75,15 +75,15 @@ CREATE USER alias_user SET PASSWORD 'secretpassword' + [source, Cypher] ---- -CREATE ROLE remote +CREATE ROLE remote_access ---- . Grant the necessary privileges on `db1` to the custom role and assign the role to the user profile created for the remote database alias: + [source, Cypher] ---- -GRANT ACCESS ON DATABASE db1 TO remote -GRANT MATCH {*} ON GRAPH db1 TO remote -GRANT ROLE remote TO alias_user +GRANT ACCESS ON DATABASE db1 TO remote_access +GRANT MATCH {*} ON GRAPH db1 TO remote_access +GRANT ROLE remote_access TO alias_user ---- . Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. + @@ -109,7 +109,7 @@ It is recommended to create a custom role to track all users shared on a remote === Configure the local DBMS A and grant access to Carol (_Alice_) As _Alice_, you are responsible for setting up *DBMS А*. -You can create and delete the database aliases and grant or deny users' access to them. +You can create and delete database aliases and grant or deny users' access to them. In this example, you create a remote database alias, called `db1-remote-alias`, which connects to `db1` on *DBMS B* using the credentials shared by _Bob_. @@ -180,7 +180,7 @@ bin/neo4j start --expand-commands ==== Create the remote database alias and grant access to Carol -Finally, you create the remote database alias using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias administrative commands]. +You create the remote database alias using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias administrative commands] and grant _Carol_ access to it. [NOTE] ==== @@ -190,18 +190,18 @@ By default, remote aliases require a secured URI scheme such as `neo4j+s`. However, if you want to disable the secure URL scheme, you can set the driver setting `ssl_enforced` to `false`. ==== -For example, you can use the following command to create a remote database alias with stored native credentials shared by _Bob_: - +. Use the following command to create a remote database alias with the stored native credentials shared by _Bob_: ++ [source, Cypher] ---- CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER alias_user PASSWORD 'secretpassword' ---- -Then, you can grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias to _Carol_: - +. Grant access to the remote database alias to the `remote_access` role and assign it to _Carol_. +See xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] for more information. ++ [source, Cypher] ---- -CREATE ROLE remote_access GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access GRANT ROLE remote_access TO Carol ---- @@ -236,7 +236,7 @@ image::remote-alias-credential-forwarding-overview.svg[title="Overview of the re _Carol_ logs into the local *DBMS A* through an OIDC-compliant identity provider by offering a token from the provider. The token is used to set the username and determine the identity provider groups to which the user belongs. -_Alice_ is the administrator of the local *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `db1-remote-alias`, to connect to the remote database `db1`. +_Alice_ is the administrator of the local *DBMS A* and sets up SSO for the identity provider and configures the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `db1-remote-alias`, to connect to the remote database `db1`. _Bob_ configures the remote *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. He also configures the mapping of the identity provider groups to the Neo4j roles such that the _Carol's_ identity provider groups grant the appropriate privileges to access `db1` on the *DBMS B*. @@ -258,9 +258,9 @@ You can create and delete users and grant or deny privileges on the databases ma In this example, you need to ensure that _Carol_ can access `db1` on *DBMS B* using OIDC credential forwarding. -. Set up SSO and support for the identity provider and map the identity provider groups to the Neo4j roles. +. Set up SSO for the identity provider _Carol_ uses and map the identity provider groups to the Neo4j roles as done on the local *DBMS A*. For details, see the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] and xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. -If you do not want specific users to access `db2`, here is where you set it. +//If you do not want specific users to access `db2`, here is where you set it. + [parameters] ---- @@ -294,7 +294,7 @@ server.bolt.tls_level=REQUIRED === Configure the local DBMS A and grant access to Carol (_Alice_) As _Alice_, you are responsible for setting up the local *DBMS A*. -You can create and delete the database aliases and grant or deny users' access to them. +You can create and delete database aliases and grant or deny users' access to them. In this case, you need to set up a remote database alias that connects to `db1` on *DBMS B* using OIDC credential forwarding and grant _Carol_ access to it. @@ -320,10 +320,8 @@ See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial ==== Create the remote database alias and grant access to Carol -Finally, you create the remote database alias using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias administrative commands]. +You create the remote database alias using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias administrative commands]. -. Create the remote database alias using OIDC credential forwarding: -+ [NOTE] ==== It is strongly recommended to connect to a remote database alias with a secured connection. @@ -331,18 +329,25 @@ Note that only client-side SSL is supported. By default, remote aliases require a secured URI scheme such as `neo4j+s`. However, if you want to disable the secure URL scheme, you can set the driver setting `ssl_enforced` to `false`. ==== + +. Use the following command to create a remote database alias using OIDC credential forwarding: + [source, Cypher] ---- CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING ---- -. Create a role to grant access to the remote database alias and assign it to _Carol_. +. Create a custom role to track all users shared on a remote connection, so that they remain trackable: See the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] for more information. + [source, Cypher] ---- CREATE ROLE remote_access +---- +. Grant access to the remote database alias to the `remote_access` role and assign it to _Carol_. ++ +[source, Cypher] +---- GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access GRANT ROLE remote_access TO Carol ---- From f92c78646880d4bd15114bd774463009ca616e52 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 9 Dec 2025 17:06:42 +0000 Subject: [PATCH 19/24] further improvements --- .../remote-database-alias-configuration.adoc | 139 +++++++++--------- 1 file changed, 66 insertions(+), 73 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index f4c215f0d..b91d3a2d3 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -18,7 +18,7 @@ The user needs to be logged in with an identity provider supporting OIDC. By creating a remote database alias, you define: -* Which user credentials of the remote DBMS can access the remote database alias. +* Which user can access the remote database alias. * Where the remote database is located. * How to connect to the remote database using driver settings. @@ -46,10 +46,9 @@ In this example, _Alice_ is an administrator of *DBMS A*, _Bob_ is an administra image::remote-alias-overview.svg[title="Overview of the required remote database alias setup when using stored native credentials", role="middle"] A remote database alias is only accessible to users with appropriate privileges. -In this example, _Bob_ is the administrator responsible for deciding which database (`db1` or `db2`) the remote aliases can write and/or read. +In this example, _Bob_ is the administrator responsible for deciding which database (`db1` or `db2`) the remote alias 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_ assigns that access to _Carol_. - See xref:authentication-authorization/dbms-administration/index.adoc[DBMS privileges] for more information. @@ -77,7 +76,7 @@ CREATE USER alias_user SET PASSWORD 'secretpassword' ---- CREATE ROLE remote_access ---- -. Grant the necessary privileges on `db1` to the custom role and assign the role to the user profile created for the remote database alias: +. Grant the `remote_access` role access to `db1` and assign the role to the user profile created for the remote database alias, `alias_user`: + [source, Cypher] ---- @@ -103,7 +102,6 @@ dbms.ssl.policy.bolt.client_auth=NONE server.bolt.tls_level=REQUIRED ---- . 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. [[remote-alias-config-DBMS_admin-A]] === Configure the local DBMS A and grant access to Carol (_Alice_) @@ -116,7 +114,7 @@ In this example, you create a remote database alias, called `db1-remote-alias`, ==== Generate an encryption key First, 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*. +In this case, the credentials of the user `alias_user` of *DBMS B* are reversibly encrypted and stored in the `system` database of *DBMS A*. Since the algorithm used is AES/GCM, you must provide an AES encryption key of length 256 and store it in a password-protected keystore in the PKCS12 format. The key can be generated by using the following keytool command in your terminal, which is included in link:https://docs.oracle.com/en/java/javase/11/tools/keytool.html[Java Platform, Standard Edition]: @@ -197,13 +195,13 @@ However, if you want to disable the secure URL scheme, you can set the driver se CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER alias_user PASSWORD 'secretpassword' ---- -. Grant access to the remote database alias to the `remote_access` role and assign it to _Carol_. +. Grant the `remote_access` role access to the remote database alias and assign it to _Carol_. See xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] for more information. + [source, Cypher] ---- GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access -GRANT ROLE remote_access TO Carol +GRANT ROLE remote_access TO carol ---- [NOTE] @@ -251,46 +249,6 @@ Crucially, if the OIDC configuration settings differ between the local DBMS and This configuration independence can lead to privilege inconsistency (e.g., over-privileging or unexpected access denial). ==== -=== Configure the remote DBMS B (_Bob_) - -As _Bob_, you are responsible for setting up the remote *DBMS B*. -You can create and delete users and grant or deny privileges on the databases managed by *DBMS B*. - -In this example, you need to ensure that _Carol_ can access `db1` on *DBMS B* using OIDC credential forwarding. - -. Set up SSO for the identity provider _Carol_ uses and map the identity provider groups to the Neo4j roles as done on the local *DBMS A*. -For details, see the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] and xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. -//If you do not want specific users to access `db2`, here is where you set it. -+ -[parameters] ----- -# OIDC settings - these should be the same on both DBMSs -dbms.security.oidc..well_known_discovery_uri=http://example.com/.well-known/discovery -<...> -dbms.security.oidc..claims.groups=groups -dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = admin; \ - "collaborators" = reader; \ - "remote_users" = remote_access ----- - -. Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. -+ -[parameters] ----- -# 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 the local DBMS A and grant access to Carol (_Alice_) As _Alice_, you are responsible for setting up the local *DBMS A*. @@ -298,26 +256,6 @@ You can create and delete database aliases and grant or deny users' access to th In this case, you need to set up a remote database alias that connects to `db1` on *DBMS B* using OIDC credential forwarding and grant _Carol_ access to it. -==== Set up SSO on the local DBMS and map the identity provider groups to the Neo4j roles - -In order for _Carol_ to get access to the remote database alias, she needs to be in an identity provider group that is mapped to a Neo4j role that is granted access to that alias. - -You set up SSO on the local *DBMS A* and map the identity provider groups to the Neo4j roles that match those on the remote *DBMS B*. -For details on how to map identity provider groups to Neo4j roles, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. - -[parameters] ----- -dbms.security.oidc..well_known_discovery_uri=http://example.com/.well-known/discovery -<...> -dbms.security.oidc..claims.groups=groups -dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = admin; \ - "collaborators" = reader; \ - "remote_users" = remote_access ----- -+ -This is where the permission to use the remote database alias is set. -See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details. - ==== Create the remote database alias and grant access to Carol You create the remote database alias using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias administrative commands]. @@ -338,18 +276,17 @@ CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" ---- . Create a custom role to track all users shared on a remote connection, so that they remain trackable: -See the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] for more information. + [source, Cypher] ---- CREATE ROLE remote_access ---- -. Grant access to the remote database alias to the `remote_access` role and assign it to _Carol_. +. Grant the `remote_access` role access to the remote database alias and assign the role to _Carol_: + [source, Cypher] ---- GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access -GRANT ROLE remote_access TO Carol +GRANT ROLE remote_access TO carol ---- + [NOTE] @@ -358,6 +295,62 @@ If a transaction modifies an alias (e.g. changing the database targeted on *DBMS This prevents issues such as a transaction executing against multiple target databases for the same alias. ==== +==== Set up SSO on the local DBMS and map the identity provider groups to the Neo4j roles + +In order for _Carol_ to get access to the remote database alias, she needs to be in an identity provider group that is mapped to a Neo4j role that is granted access to that alias. + +You set up SSO on the local *DBMS A* and map the identity provider groups to the Neo4j roles. +For details, see the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] and xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. + +[parameters] +---- +dbms.security.oidc..well_known_discovery_uri=http://example.com/.well-known/discovery +<...> +dbms.security.oidc..claims.groups=groups +dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = admin; \ + "collaborators" = reader; \ + "remote_users" = remote_access +---- + +=== Configure the remote DBMS B (_Bob_) + +As _Bob_, you are responsible for setting up the remote *DBMS B*. +You can create and delete users and grant or deny privileges on the databases managed by *DBMS B*. + +In this example, you need to ensure that _Carol_ can access `db1` on *DBMS B* using OIDC credential forwarding. + +. Set up SSO on the remote *DBMS B* and map the identity provider groups to the Neo4j roles. +The configuration must match the one on the local *DBMS A*. +For details, see the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] and xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. +//If you do not want specific users to access `db2`, here is where you set it. ++ +[parameters] +---- +dbms.security.oidc..well_known_discovery_uri=http://example.com/.well-known/discovery +<...> +dbms.security.oidc..claims.groups=groups +dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = admin; \ + "collaborators" = reader; \ + "remote_users" = remote_access +---- + +. Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. ++ +[parameters] +---- +# 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 +---- == Connect to remote database aliases @@ -372,12 +365,12 @@ USE `db1-remote-alias` MATCH (n) RETURN * ---- * Connecting to a remote database alias as a home database. -This needs to be set by an administrator. +This needs to be set by an administrator, in this case _Alice_. See xref:authentication-authorization/dbms-administration/dbms-user-management-privileges.adoc[User Management] for more information. + [source, Cypher] ---- -ALTER USER alice SET HOME DATABASE `db1-remote-alias` +ALTER USER carol SET HOME DATABASE `db1-remote-alias` ---- == Important notes From 082180c791e590d9281a98b32326f558dc10a95f Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 10 Dec 2025 10:30:35 +0000 Subject: [PATCH 20/24] Update modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc Co-authored-by: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> --- .../aliases/remote-database-alias-configuration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index b91d3a2d3..a9f81d682 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -62,7 +62,7 @@ Then, _Alice_ will be able to grant _Carol_ access to the remote database alias As _Bob_, you are responsible for the remote *DBMS B*. You can create and delete users and grant or deny privileges on the databases managed by *DBMS B*. -In this example, you create a user called `alias_user`, which will be used by the remote database alias to connect to `db1`, and shares the credentials with _Alice_. +In this example, you create a user called `alias_user`, which will be used by the remote database alias to connect to `db1`, and share the credentials with _Alice_. . Create the user profile to share with _Alice_: + From 6b68373171cba9e94663cb8f14761d07731d186d Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Fri, 12 Dec 2025 15:22:16 +0100 Subject: [PATCH 21/24] docs: fixing descriptive steps and adding info --- .../remote-database-alias-configuration.adoc | 86 ++++++++++++++----- 1 file changed, 63 insertions(+), 23 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index a9f81d682..37684527b 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -4,7 +4,7 @@ [[manage-remote-aliases]] = Configuring remote database aliases -You can use a remote database alias to connect to one or more graphs or to one or more remote standalone servers or clusters. +You can use a remote database alias to connect to a graph located on a remote standalone server or cluster. 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 xref:database-administration/aliases/manage-aliases-standard-databases.adoc[administrative commands] on a running system. @@ -18,7 +18,7 @@ The user needs to be logged in with an identity provider supporting OIDC. By creating a remote database alias, you define: -* Which user can access the remote database alias. +* Which credentials to use to authenticate to the remote database. * Where the remote database is located. * How to connect to the remote database using driver settings. @@ -35,6 +35,13 @@ GRANT CREATE ALIAS ON DBMS TO administrator ---- ==== +By granting access to the remote database alias, you define which users can use it to connect to the database on the remote DBMS. + +[CAUTION] +==== +Many of the xref:authentication-authorization/built-in-roles.adoc[built-in roles] that Neo4j provides have access to all databases, this includes any remote database alias. +==== + The following examples describe how to set up access to a remote database via a remote database alias by using either stored native credentials, or OIDC credential forwarding. They assume that you have two separate DBMS instances: a local *DBMS A* and a remote *DBMS B*. @@ -46,43 +53,57 @@ In this example, _Alice_ is an administrator of *DBMS A*, _Bob_ is an administra image::remote-alias-overview.svg[title="Overview of the required remote database alias setup when using stored native credentials", role="middle"] A remote database alias is only accessible to users with appropriate privileges. -In this example, _Bob_ is the administrator responsible for deciding which database (`db1` or `db2`) the remote alias can write and/or read. +In this example, _Bob_ is the administrator responsible for deciding which database (`db1` or `db2`) the remote database alias 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_ assigns that access to _Carol_. See xref:authentication-authorization/dbms-administration/index.adoc[DBMS privileges] for more information. -_Carol_ can use her own regular credentials to access the remote database `db1` in *DBMS B* after _Bob_ creates a user profile for her and shares the credentials with _Alice_. -Then, _Alice_ will be able to grant _Carol_ access to the remote database alias `db1-remote-alias` that connects to `db1` on *DBMS B* using the shared credentials. +_Bob_ creates a user profile on *DBMS B*, grants it access to database `db1` and shares the credentials with _Alice_. +Then, _Alice_ creates a remote database alias `db1-remote-alias` on *DBMS A* that connects to `db1` on *DBMS B* using the shared credentials. +After _Alice_ grants _Carol_ access to the remote database alias, _Carol_ can log in to the local *DBMS A*, using her own credentials, and through the remote database alias connect to `db1` on *DBMS B*. //This configuration will also allow _Carol_ to access `db2` in *DBMS B*, if _Bob_ grants the necessary privileges to the user profile shared with _Alice_. //See xref:authentication-authorization/index.adoc[Authentication and authorization] for further information. +[CAUTION] +==== +All operations executed on the remote DBMS are performed under the identity of the user associated with the remote database alias. +When using `STORED NATIVE CREDENTIALS`, the same credentials are used to connect to the remote DBMS regardless of which end-user made the query targeting the remote database alias. +As a result, a user's roles and permissions on the local DBMS do not restrict the actions that are processed on the remote DBMS. +Any local user who can access the remote database alias effectively inherits the permissions granted to the user configured for that alias. +It is therefore essential to watch of any privilege mismatch that can result from this configuration (e.g., over-privileging or under-privileging). + +For example, suppose the shared user on *DBMS B*, who is shared and configured for the remote database alias on the *DBMS A*, is assigned the built-in role `editor`, allowing both read and write access. +A local user on *DBMS A* may only have the `reader` role and therefore be limited to read-only operations locally. +However, that user can access the remote database alias, and thus operate on DBMS B using the alias’s credentials and therefore gain the associated write privileges, enabling them to modify data on DBMS B despite their limited local role. +==== + === Configure the remote DBMS B (_Bob_) As _Bob_, you are responsible for the remote *DBMS B*. You can create and delete users and grant or deny privileges on the databases managed by *DBMS B*. -In this example, you create a user called `alias_user`, which will be used by the remote database alias to connect to `db1`, and share the credentials with _Alice_. +In this example, you create a user called `remote_user`, which will be used by the remote database alias to connect to `db1`, and share the credentials with _Alice_. . Create the user profile to share with _Alice_: + [source, Cypher] ---- -CREATE USER alias_user SET PASSWORD 'secretpassword' +CREATE USER remote_user SET PASSWORD 'secretpassword' ---- . Create a custom role to track all users shared on a remote connection, so that they remain trackable: + [source, Cypher] ---- -CREATE ROLE remote_access +CREATE ROLE shared_to_remote ---- -. Grant the `remote_access` role access to `db1` and assign the role to the user profile created for the remote database alias, `alias_user`: +. Grant the `shared_to_remote` role access to `db1` and assign the role to the user profile created for the remote database alias, `remote_user`: + [source, Cypher] ---- GRANT ACCESS ON DATABASE db1 TO remote_access GRANT MATCH {*} ON GRAPH db1 TO remote_access -GRANT ROLE remote_access TO alias_user +GRANT ROLE shared_to_remote TO remote_user ---- . Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. + @@ -114,7 +135,7 @@ In this example, you create a remote database alias, called `db1-remote-alias`, ==== Generate an encryption key First, you need to generate an encryption key. -In this case, the credentials of the user `alias_user` of *DBMS B* are reversibly encrypted and stored in the `system` database of *DBMS A*. +In this case, the credentials of the user `remote_user` of *DBMS B* are reversibly encrypted and stored in the `system` database of *DBMS A*. Since the algorithm used is AES/GCM, you must provide an AES encryption key of length 256 and store it in a password-protected keystore in the PKCS12 format. The key can be generated by using the following keytool command in your terminal, which is included in link:https://docs.oracle.com/en/java/javase/11/tools/keytool.html[Java Platform, Standard Edition]: @@ -184,7 +205,7 @@ You create the remote database alias using xref:database-administration/aliases/ ==== It is strongly recommended to connect to a remote database alias with a secured connection. Note that only client-side SSL is supported. -By default, remote aliases require a secured URI scheme such as `neo4j+s`. +By default, remote database aliases require a secured URI scheme such as `neo4j+s`. However, if you want to disable the secure URL scheme, you can set the driver setting `ssl_enforced` to `false`. ==== @@ -192,7 +213,14 @@ However, if you want to disable the secure URL scheme, you can set the driver se + [source, Cypher] ---- -CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER alias_user PASSWORD 'secretpassword' +CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER remote_user PASSWORD 'secretpassword' +---- + +.Create a custom role to track all users who have access to the remote database alias (or chose an already existing role): + +[source, Cypher] +---- +CREATE ROLE remote_access ---- . Grant the `remote_access` role access to the remote database alias and assign it to _Carol_. @@ -212,12 +240,12 @@ This prevents issues such as a transaction executing against multiple target dat ==== Changing the encryption key -Changing the encryption key in the keystore requires updating the encrypted credentials for all existing remote database aliases, as they will no longer be readable with the new key. +If the encryption key in the keystore is changed, the encrypted credentials for all existing remote database aliases requires updating, as they will no longer be readable with the new key. [NOTE] ==== In case of 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. +In case it is not possible to connect to the remote database alias after its creation, verify its settings by connecting to the remote database at https://browser.neo4j.io/ or at your local browser. ==== [role=label--new-2025.x] @@ -264,7 +292,7 @@ You create the remote database alias using xref:database-administration/aliases/ ==== It is strongly recommended to connect to a remote database alias with a secured connection. Note that only client-side SSL is supported. -By default, remote aliases require a secured URI scheme such as `neo4j+s`. +By default, remote database aliases require a secured URI scheme such as `neo4j+s`. However, if you want to disable the secure URL scheme, you can set the driver setting `ssl_enforced` to `false`. ==== @@ -275,18 +303,17 @@ However, if you want to disable the secure URL scheme, you can set the driver se CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING ---- -. Create a custom role to track all users shared on a remote connection, so that they remain trackable: +. Create a custom role to track all users who have access to the remote database alias (or chose an already existing role): + [source, Cypher] ---- CREATE ROLE remote_access ---- -. Grant the `remote_access` role access to the remote database alias and assign the role to _Carol_: +. Grant the `remote_access` role access to the remote database alias, the role will be assigned to _Carol_ on log in via the mapping of identity provider groups to the Neo4j roles: + [source, Cypher] ---- GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access -GRANT ROLE remote_access TO carol ---- + [NOTE] @@ -319,8 +346,21 @@ You can create and delete users and grant or deny privileges on the databases ma In this example, you need to ensure that _Carol_ can access `db1` on *DBMS B* using OIDC credential forwarding. +. Create a custom role or chose an existing one, the roles will be assigned to the users on log in via the mapping of identity provider groups to the Neo4j roles: ++ +[source, Cypher] +---- +CREATE ROLE db1_access +---- +. Grant the `db1_access` role access to `db1`. ++ +[source, Cypher] +---- +GRANT ACCESS ON DATABASE db1 TO db1_access +GRANT MATCH {*} ON GRAPH db1 TO db1_access +---- + . Set up SSO on the remote *DBMS B* and map the identity provider groups to the Neo4j roles. -The configuration must match the one on the local *DBMS A*. For details, see the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] and xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. //If you do not want specific users to access `db2`, here is where you set it. + @@ -331,7 +371,7 @@ dbms.security.oidc..well_known_discovery_uri=http://example.com/.well- dbms.security.oidc..claims.groups=groups dbms.security.oidc..authorization.group_to_role_mapping= "engineers" = admin; \ "collaborators" = reader; \ - "remote_users" = remote_access + "remote_users" = db1_access ---- . Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. @@ -377,11 +417,11 @@ ALTER USER carol SET HOME DATABASE `db1-remote-alias` When using remote database aliases, keep in mind that: -* Remote alias transactions will not be visible in `SHOW TRANSACTIONS` on the local DBMS. +* Remote database alias transactions will not be visible in `SHOW TRANSACTIONS` on the local DBMS. However, they can be accessed and terminated on the remote database when connecting with the same user. * Actions on the remote DBMS are all attributed to the user configured for the remote database alias. -In the case of using `STORED NATIVE CREDENTIALS`, the same credentials are used to connect to the remote DBMS regardless of which end-user made the query targeting the remote alias. +In the case of using `STORED NATIVE CREDENTIALS`, the same credentials are used to connect to the remote DBMS regardless of which end-user made the query targeting the remote database alias. This will result in the stored native user being logged in the audit trails on the remote DBMS for all queries using the remote database alias. When using `OIDC CREDENTIAL FORWARDING`, the actual end-user's credentials and permissions are used, resulting in per-user audit trails being logged on the remote DBMS. From 2360dc0e5d7a3af4d9f831f7bdedbafb7508dd4d Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Fri, 12 Dec 2025 16:58:12 +0100 Subject: [PATCH 22/24] docs: add oidc cred forwarding to database management command syntax page --- .../pages/database-administration/syntax.adoc | 48 +++++++++++++++++-- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/database-administration/syntax.adoc b/modules/ROOT/pages/database-administration/syntax.adoc index 553c36f4a..ca19e48ae 100644 --- a/modules/ROOT/pages/database-administration/syntax.adoc +++ b/modules/ROOT/pages/database-administration/syntax.adoc @@ -392,6 +392,10 @@ CREATE OR REPLACE ALIAS name FOR DATABASE targetName === Create a remote alias +[.tabbed-example] +===== +[role=include-with-cypher-5] +====== [options="header", width="100%", cols="1m,5a"] |=== | Command | Syntax @@ -399,27 +403,63 @@ CREATE OR REPLACE ALIAS name FOR DATABASE targetName | CREATE ALIAS | [source, syntax, role=noheader] ------ +---- CREATE ALIAS name [IF NOT EXISTS] FOR DATABASE targetName AT 'url' USER username PASSWORD 'password' [DRIVER "{" setting: value[, ...] "}"] [DEFAULT LANGUAGE CYPHER {5\|25}] [PROPERTIES "{" key: value[, ...] "}"] ------ +---- [source, syntax, role=noheader] ------ +---- CREATE OR REPLACE ALIAS name FOR DATABASE targetName AT 'url' USER username PASSWORD 'password' [DRIVER "{" setting: value[, ...] "}"] [DEFAULT LANGUAGE CYPHER {5\|25}] [PROPERTIES "{" key: value[, ...] "}"] ------ +---- |=== [NOTE] ==== `[DEFAULT LANGUAGE CYPHER {5|25}]` is available from Neo4j 2025.06 onwards. ==== +====== + +[role=include-with-cypher-25] +====== + +[options="header", width="100%", cols="1m,5a"] +|=== +| Command | Syntax +| CREATE ALIAS +| +[source, syntax, role="noheader"] +---- +CREATE ALIAS name [IF NOT EXISTS] FOR DATABASE targetName +AT 'url' { USER username PASSWORD 'password' \| OIDC CREDENTIAL FORWARDING } +[DRIVER "{" setting: value[, ...] "}"] +[DEFAULT LANGUAGE CYPHER {5\|25}] +[PROPERTIES "{" key: value[, ...] "}"] +---- + +[source, syntax, role="noheader"] +---- +CREATE OR REPLACE ALIAS name FOR DATABASE targetName +AT 'url' { USER username PASSWORD 'password' \| OIDC CREDENTIAL FORWARDING } +[DRIVER "{" setting: value[, ...] "}"] +[DEFAULT LANGUAGE CYPHER {5\|25}] +[PROPERTIES "{" key: value[, ...] "}"] +---- +|=== + +[NOTE] +==== +`[DEFAULT LANGUAGE CYPHER {5|25}]` is available from Neo4j 2025.06 onwards. + +`OIDC CREDENTIAL FORWARDING` is available from Neo4j 2025.x onwards. +==== +====== +===== === Alter a local alias From 3c8951c9fc5c6dc2c6d6d4eaf1257072ec00104c Mon Sep 17 00:00:00 2001 From: Evelina Danielsson Date: Mon, 15 Dec 2025 09:33:10 +0100 Subject: [PATCH 23/24] Apply suggestions from code review Co-authored-by: Reneta Popova --- .../remote-database-alias-configuration.adoc | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index 37684527b..cf41ecb90 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -75,7 +75,7 @@ It is therefore essential to watch of any privilege mismatch that can result fro For example, suppose the shared user on *DBMS B*, who is shared and configured for the remote database alias on the *DBMS A*, is assigned the built-in role `editor`, allowing both read and write access. A local user on *DBMS A* may only have the `reader` role and therefore be limited to read-only operations locally. -However, that user can access the remote database alias, and thus operate on DBMS B using the alias’s credentials and therefore gain the associated write privileges, enabling them to modify data on DBMS B despite their limited local role. +However, that user can access the remote database alias and thus operate on DBMS B using the alias’s credentials, and therefore gain the associated write privileges, enabling them to modify data on *DBMS B* despite their limited local role. ==== === Configure the remote DBMS B (_Bob_) @@ -101,8 +101,8 @@ CREATE ROLE shared_to_remote + [source, Cypher] ---- -GRANT ACCESS ON DATABASE db1 TO remote_access -GRANT MATCH {*} ON GRAPH db1 TO remote_access +GRANT ACCESS ON DATABASE db1 TO shared_to_remote +GRANT MATCH {*} ON GRAPH db1 TO shared_to_remote GRANT ROLE shared_to_remote TO remote_user ---- . Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required. @@ -216,8 +216,9 @@ However, if you want to disable the secure URL scheme, you can set the driver se CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER remote_user PASSWORD 'secretpassword' ---- -.Create a custom role to track all users who have access to the remote database alias (or chose an already existing role): +. Create a custom role to track all users who have access to the remote database alias (or choose an already existing role): ++ [source, Cypher] ---- CREATE ROLE remote_access @@ -303,13 +304,14 @@ However, if you want to disable the secure URL scheme, you can set the driver se CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING ---- -. Create a custom role to track all users who have access to the remote database alias (or chose an already existing role): +. Create a custom role to track all users who have access to the remote database alias (or choose an already existing role): + [source, Cypher] ---- CREATE ROLE remote_access ---- -. Grant the `remote_access` role access to the remote database alias, the role will be assigned to _Carol_ on log in via the mapping of identity provider groups to the Neo4j roles: +. Grant the `remote_access` role access to the remote database alias. +The role will be assigned to _Carol_ on login via the mapping of identity provider groups to the Neo4j roles: + [source, Cypher] ---- @@ -346,13 +348,14 @@ You can create and delete users and grant or deny privileges on the databases ma In this example, you need to ensure that _Carol_ can access `db1` on *DBMS B* using OIDC credential forwarding. -. Create a custom role or chose an existing one, the roles will be assigned to the users on log in via the mapping of identity provider groups to the Neo4j roles: +. Create a custom role or choose an existing one. +The roles will be assigned to the users on login via the mapping of identity provider groups to the Neo4j roles: + [source, Cypher] ---- CREATE ROLE db1_access ---- -. Grant the `db1_access` role access to `db1`. +. Grant the `db1_access` role access to `db1`: + [source, Cypher] ---- From 59bb408b859692218c7fdbc5fde1a0f73d4a6d03 Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Mon, 15 Dec 2025 13:15:41 +0100 Subject: [PATCH 24/24] docs: rewrote caution block --- .../aliases/remote-database-alias-configuration.adoc | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index cf41ecb90..a0dc4d69c 100644 --- a/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc +++ b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc @@ -270,12 +270,11 @@ He also configures the mapping of the identity provider groups to the Neo4j role [CAUTION] ==== -While it is possible to use different OIDC configurations across distinct DBMS instances (DBMS A & B in this example), database administrators must be aware of the resulting privilege disparity. -A user's effective permissions are not dictated by the identity provider groups alone, but by the mapping of those groups to the roles defined within each specific Neo4j DBMS. +A user's effective permissions are not dictated by the identity provider groups alone, but by the mapping of those groups to roles defined within each Neo4j DBMS. See xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. - -Crucially, if the OIDC configuration settings differ between the local DBMS and the target DBMS, the user will have different effective privileges on those systems. -This configuration independence can lead to privilege inconsistency (e.g., over-privileging or unexpected access denial). +As a result, different OIDC configurations across distinct DBMS instances may lead to the same user having different effective privileges on those instances, (DBMS A and DBMS B in this example). +While it is possible to use different OIDC configurations across DBMS instances, database administrators must be aware of any privilege disparity that may arise from this and ensure that group-to-role mappings intended to grant equivalent access remain consistent across DBMSs. +This is to avoid privilege inconsistency, such as over-privileging or unexpected access denial. ==== === Configure the local DBMS A and grant access to Carol (_Alice_)