docs: updated and added OIDC credential forwarding

evelinadanielsson · evelinadanielsson · commit f07ae4322f50 · 2025-11-24T15:39:50.000+01:00
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
@@ -379,18 +379,25 @@ 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.
 Instead, they are assigned the version given by xref:configuration/configuration-settings.adoc#config_db.query.default_language[`db.query.default_language`], which is set in the `neo4j.conf` file.
 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
@@ -14,39 +14,46 @@ 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.
 In the example above, _Bob_ is the administrator responsible for deciding which databases (`Db1` or `Db2`) the remote aliases can write and/or read.
 Meanwhile, _Alice_ is the administrator that assigns who has access to the privileges set by _Bob_.
 In the example, _Alice_ will assign that access to _Carol_.
 
-See 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 +86,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,7 +152,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.
@@ -154,15 +161,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 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 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]
@@ -183,7 +190,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.
 
@@ -193,6 +200,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.<provider>.well_known_discovery_uri=http://example.com/.well-known/discovery
+<...>
+dbms.security.oidc.<provider>.claims.groups=groups
+dbms.security.oidc.<provider>.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.<provider>.well_known_discovery_uri=http://example.com/.well-known/discovery
+<...>
+dbms.security.oidc.<provider>.claims.groups=groups
+dbms.security.oidc.<provider>.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.
@@ -208,7 +329,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]
 ----
@@ -220,3 +341,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`.
+====
