docs: updated and added OIDC credential forwarding

Author: evelinadanielsson

modules/ROOT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc

@@ -379,18 +379,23 @@ 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. 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).

modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc

@@ -14,39 +14,41 @@ 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.
 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 +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.