updated documentation

Author: evelinadanielsson

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]

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.<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_)
@@ -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.<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.
@@ -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.
+====
+