From 0d6f9e32a64b5bfbcafdb974aa386005b74f3265 Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Thu, 30 Oct 2025 16:20:23 +0100 Subject: [PATCH 1/9] docs: updated and added OIDC credential forwarding --- .../manage-aliases-standard-databases.adoc | 51 ++++++++++-- .../remote-database-alias-configuration.adoc | 77 ++++++++++++++++--- 2 files changed, 110 insertions(+), 18 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 898846c3b..452d746e7 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,15 @@ 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. This can be done by providing the credentials of a native user, or +by forwarding the OIDC credentials of the user logged in to the local DBMS. + +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 +406,50 @@ 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-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. + +.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" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "alice" | -+----------------------------------------------------------------------------------------------------------+ ++-------------------------------------------------------------------------------------------------------------------------------------+ +| 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 d486dd2f1..2cf37a5bb 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,21 @@ 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 either be configured to store the credentials of a single user on the remote **DBMS B**, or to pass on the bearer authentication token from the user who issues the query. + +== 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. @@ -33,20 +36,19 @@ In the example above, _Bob_ is the administrator responsible for deciding which 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 lxref:authentication-authorization/dbms-administration.adoc[DBMS privileges] for more information. +See xref:authentication-authorization/dbms-administration.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 (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. @@ -79,7 +81,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**. @@ -145,6 +147,61 @@ chmod 640 conf/neo4j.conf bin/neo4j start --expand-commands ---- +== 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 built-in roles and custom 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 built-in roles and custom 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 +---- + +=== 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. + + == Manage remote database aliases You can use the xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias commands] to manage remote database aliases. From 86463fcaea0db97a87fb2dce159111d9929883c4 Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Wed, 5 Nov 2025 18:31:36 +0100 Subject: [PATCH 2/9] updated documentation --- .../manage-aliases-standard-databases.adoc | 1 + .../remote-database-alias-configuration.adoc | 108 +++++++++++++++--- 2 files changed, 92 insertions(+), 17 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 452d746e7..4f9ab4aa3 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 @@ -421,6 +421,7 @@ 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. .Query [source, cypher] 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 2cf37a5bb..0e8c64522 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 @@ -20,8 +20,13 @@ A remote alias defines: * Where the remote database is located. * How to connect to the remote database using driver settings. -When creating the remote database alias, it can either be configured to store the credentials of a single user on the remote **DBMS B**, or to pass on the bearer authentication token from the user who issues the query. +When creating the remote database alias, it can be configured to authenticate with either: +* `STORED NATIVE CREDENTIALS`, i.e. the credentials of a single user on the remote **DBMS B**. +* `OIDC CREDENTIAL FORWARDING`, i.e. passing the bearer authentication token from the user who issues the query. In order to use this method to authenticate, the local *DBMS A* and remote *DBMS B* 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. + + +[[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_: @@ -147,6 +152,55 @@ chmod 640 conf/neo4j.conf 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. + +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: + +[source, Cypher] +---- +CREATE ALIAS `remote-neo4j` FOR DATABASE `neo4j` AT "neo4j+s://location:7687" USER alice PASSWORD 'secretpassword' +---- + +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 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. +This prevents issues such as a transaction executing against multiple target databases for the same alias. +==== + +=== Change the encryption key + +If the encryption key in the keystore is changed, the encrypted credentials for existing remote database aliases will need to be updated as they will no longer be readable. + +[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 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. +==== + +[[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. @@ -192,6 +246,13 @@ 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_) @@ -201,8 +262,16 @@ 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. - -== Manage remote database aliases +[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. @@ -211,15 +280,15 @@ 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 OIDC credential forwarding: [source, Cypher] ---- -CREATE ALIAS `remote-neo4j` FOR DATABASE `neo4j` AT "neo4j+s://location:7687" USER alice PASSWORD 'secretpassword' +CREATE ALIAS `remote-neo4j` FOR DATABASE `neo4j` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING ---- -In order to do so, either lxref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management] -or lxref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges are required. +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] @@ -231,25 +300,22 @@ Here is how to grant the xref:authentication-authorization/database-administrati [source, Cypher] ---- -GRANT ACCESS ON DATABASE `remote-neo4j` TO role +GRANT ACCESS ON DATABASE `remote-neo4j` TO admin ---- [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. +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]. ==== -== 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. - [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 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. +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. @@ -265,7 +331,7 @@ USE `remote-neo4j` MATCH (n) RETURN * * Connecting to a remote database alias as a home database. This needs to be set by Administrator A. -See more about lxref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[User Management]. +See more about xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[User Management]. [source, Cypher] ---- @@ -277,3 +343,11 @@ 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. +==== + From f36bcbaf992027ad0af324a7b40190e97f42ff70 Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Wed, 5 Nov 2025 19:53:46 +0100 Subject: [PATCH 3/9] add version tag --- .../aliases/manage-aliases-standard-databases.adoc | 7 +++++-- .../aliases/remote-database-alias-configuration.adoc | 3 ++- 2 files changed, 7 insertions(+), 3 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 4f9ab4aa3..7e2c39bd7 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 @@ -387,8 +387,11 @@ 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. This can be done by providing the credentials of a native user, or -by forwarding the OIDC credentials of the user logged in to the local DBMS. +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`, i.e. the credentials of a single user on the remote DBMS. +* `OIDC CREDENTIAL FORWARDING`, i.e. passing the bearer authentication token from the user logged in through SSO and who issues the query. Introduced in 2025.10 +by forwarding the OIDC credentials of the user logged in to the local DBMS. 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. 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 0e8c64522..b3979a8cf 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 @@ -23,7 +23,7 @@ A remote alias defines: When creating the remote database alias, it can be configured to authenticate with either: * `STORED NATIVE CREDENTIALS`, i.e. the credentials of a single user on the remote **DBMS B**. -* `OIDC CREDENTIAL FORWARDING`, i.e. passing the bearer authentication token from the user who issues the query. In order to use this method to authenticate, the local *DBMS A* and remote *DBMS B* 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. +* `OIDC CREDENTIAL FORWARDING`, i.e. passing the bearer authentication token from the user logged in through SSO and who issues the query. label:new[Introduced in 2025.10] [[setup-example-stored-native-credentials]] @@ -200,6 +200,7 @@ 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 From 8d958719fcf65d2e4e5482a4e2633538b39aaa7c Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Fri, 7 Nov 2025 09:58:05 +0100 Subject: [PATCH 4/9] docs: extending docs on oidc credential forwarding --- .../manage-aliases-standard-databases.adoc | 5 ++--- .../remote-database-alias-configuration.adoc | 19 ++++++++++--------- 2 files changed, 12 insertions(+), 12 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 7e2c39bd7..250a739d3 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 @@ -389,9 +389,8 @@ See xref:database-administration/aliases/manage-aliases-standard-databases.adoc# 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`, i.e. the credentials of a single user on the remote DBMS. -* `OIDC CREDENTIAL FORWARDING`, i.e. passing the bearer authentication token from the user logged in through SSO and who issues the query. Introduced in 2025.10 -by forwarding the OIDC credentials of the user logged in to the local DBMS. label:new[Introduced in 2025.10] +* `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. 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 b3979a8cf..bd72535c3 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,8 +22,8 @@ A remote alias defines: When creating the remote database alias, it can be configured to authenticate with either: -* `STORED NATIVE CREDENTIALS`, i.e. the credentials of a single user on the remote **DBMS B**. -* `OIDC CREDENTIAL FORWARDING`, i.e. passing the bearer authentication token from the user logged in through SSO and who issues the query. label:new[Introduced in 2025.10] +* `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]] @@ -210,8 +210,8 @@ In this example, _Alice_ is an administrator and _Carol_ is a user who needs acc 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 built-in roles and custom 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 built-in roles and custom 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 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] @@ -304,11 +304,8 @@ Here is how to grant the xref:authentication-authorization/database-administrati GRANT ACCESS ON DATABASE `remote-neo4j` TO admin ---- -[NOTE] -==== -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`. +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] ==== @@ -349,6 +346,10 @@ However, they can be accessed and terminated on the remote database when connect ==== 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 `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 82c30c3ac7444bf2fbce606e63daf0a1a5ae939f Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Mon, 10 Nov 2025 08:48:42 +0100 Subject: [PATCH 5/9] docs: include oidc credential forwarding figure --- ...e-alias-credential-forwarding-overview.svg | 56 +++++++++++++++++++ .../remote-database-alias-configuration.adoc | 3 + 2 files changed, 59 insertions(+) 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..a318c46e3 --- /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 bd72535c3..13e595bdf 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 @@ -208,6 +208,9 @@ 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`. From ffd0c895a76b1e59397d82435e78a25fc65a8df6 Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Mon, 10 Nov 2025 13:47:12 +0100 Subject: [PATCH 6/9] 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 203e01e38..d816d65df 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 250a739d3..96ba37690 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 17df8b1e9e57a1bffdc6ac94caa21280013c6302 Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Mon, 17 Nov 2025 08:39:02 +0100 Subject: [PATCH 7/9] fix: fixed figure for arrow to be correctly directed and added links --- .../images/remote-alias-credential-forwarding-overview.svg | 2 +- .../aliases/remote-database-alias-configuration.adoc | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg b/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg index a318c46e3..cfa7cc9f0 100644 --- a/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg +++ b/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg @@ -24,7 +24,7 @@ - + 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 13e595bdf..2148f61e1 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 @@ -219,7 +219,7 @@ Additionally, _Bob_ needs to configure the *DBMS B* to support SSO with the same [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). @@ -232,7 +232,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. @@ -264,7 +264,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 41aaf67a98570f49f7c0f7d319aefe97d7ba3d87 Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Mon, 17 Nov 2025 08:47:03 +0100 Subject: [PATCH 8/9] fix: reference the remote alias as remote-neo4j --- .../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 2148f61e1..715266535 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 @@ -213,7 +213,7 @@ image::remote-alias-credential-forwarding-overview.svg[title="Overview of the re 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*. From 61732935c3ee68d0146feedfb5eaacdaca6bfc04 Mon Sep 17 00:00:00 2001 From: evelinadanielsson Date: Mon, 17 Nov 2025 09:43:01 +0100 Subject: [PATCH 9/9] docs: add info about altering alias command not supporting change of credential type --- .../manage-aliases-standard-databases.adoc | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 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 96ba37690..4f3974f02 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 @@ -593,7 +593,7 @@ SHOW ALIAS `remote-northwind-2021` FOR DATABASE YIELD name, properties You can alter both local and remote database aliases using the `ALTER ALIAS` command. For all aliases, the command allows you to change the target database and properties of the database alias. -For remote aliases, the command also allows you to change the URL, user credentials, default language, or driver settings of the database alias. +For remote aliases, the command also allows you to change the URL, stored native credentials, default language, or driver settings of the database alias. The required privileges are described in the xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[The DBMS ALIAS MANAGEMENT privileges]. Only the clauses used will be altered. @@ -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 `{}`.