further improvements

Author: renetapopova

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

@@ -18,7 +18,7 @@ The user needs to be logged in with an identity provider supporting OIDC.
 
 By creating a remote database alias, you define:
 
-* Which user credentials of the remote DBMS can access the remote database alias.
+* Which user can access the remote database alias.
 * Where the remote database is located.
 * How to connect to the remote database using driver settings.
 
@@ -46,10 +46,9 @@ In this example, _Alice_ is an administrator of *DBMS A*, _Bob_ is an administra
 image::remote-alias-overview.svg[title="Overview of the required remote database alias setup when using stored native credentials", role="middle"]
 
 A remote database alias is only accessible to users with appropriate privileges.
-In this example, _Bob_ is the administrator responsible for deciding which database (`db1` or `db2`) the remote aliases can write and/or read.
+In this example, _Bob_ is the administrator responsible for deciding which database (`db1` or `db2`) the remote alias can write and/or read.
 Meanwhile, _Alice_ is the administrator that assigns who has access to the privileges set by _Bob_.
 In the example, _Alice_ assigns that access to _Carol_.
-
 See xref:authentication-authorization/dbms-administration/index.adoc[DBMS privileges] for more information.
 
 
@@ -77,7 +76,7 @@ CREATE USER alias_user SET PASSWORD 'secretpassword'
 ----
 CREATE ROLE remote_access
 ----
-. Grant the necessary privileges on `db1` to the custom role and assign the role to the user profile created for the remote database alias:
+. Grant the `remote_access` role access to `db1` and assign the role to the user profile created for the remote database alias, `alias_user`:
 +
 [source, Cypher]
 ----
@@ -103,7 +102,6 @@ dbms.ssl.policy.bolt.client_auth=NONE
 server.bolt.tls_level=REQUIRED
 ----
 . Securely transmit the credentials to _Alice_, setting up the link to database `db1`.
-It is recommended to create a custom role to track all users shared on a remote connection, so that they remain trackable.
 
 [[remote-alias-config-DBMS_admin-A]]
 === Configure the local DBMS A and grant access to Carol (_Alice_)
@@ -116,7 +114,7 @@ In this example, you create a remote database alias, called `db1-remote-alias`,
 ==== Generate an encryption key
 
 First, you need to generate an encryption key.
-In this case, the credentials of a user of *DBMS B* are reversibly encrypted and stored in the `system` database of *DBMS A*.
+In this case, the credentials of the user `alias_user` of *DBMS B* are reversibly encrypted and stored in the `system` database of *DBMS A*.
 Since the algorithm used is AES/GCM, you must provide an AES encryption key of length 256 and store it in a password-protected keystore in the PKCS12 format.
 
 The key can be generated by using the following keytool command in your terminal, which is included in link:https://docs.oracle.com/en/java/javase/11/tools/keytool.html[Java Platform, Standard Edition]:
@@ -197,13 +195,13 @@ However, if you want to disable the secure URL scheme, you can set the driver se
 CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER alias_user PASSWORD 'secretpassword'
 ----
 
-. Grant access to the remote database alias to the `remote_access` role and assign it to _Carol_.
+. Grant the `remote_access` role access to the remote database alias and assign it to _Carol_.
 See xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] for more information.
 +
 [source, Cypher]
 ----
 GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access
-GRANT ROLE remote_access TO Carol
+GRANT ROLE remote_access TO carol
 ----
 
 [NOTE]
@@ -251,73 +249,13 @@ Crucially, if the OIDC configuration settings differ between the local DBMS and
 This configuration independence can lead to privilege inconsistency (e.g., over-privileging or unexpected access denial).
 ====
 
-=== Configure the remote DBMS B (_Bob_)
-
-As _Bob_, you are responsible for setting up the remote *DBMS B*.
-You can create and delete users and grant or deny privileges on the databases managed by *DBMS B*.
-
-In this example, you need to ensure that _Carol_ can access `db1` on *DBMS B* using OIDC credential forwarding.
-
-. Set up SSO for the identity provider _Carol_ uses and map the identity provider groups to the Neo4j roles as done on the local *DBMS A*.
-For details, see the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] and xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles].
-//If you do not want specific users to access `db2`, here is where you set it.
-+
-[parameters]
-----
-# OIDC settings - these should be the same on both DBMSs
-dbms.security.oidc.<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; \
-                                                                   "remote_users" = remote_access
-----
-
-. Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required.
-+
-[parameters]
-----
-# accept non-local connections
-server.default_listen_address=0.0.0.0
-
-# configure ssl for bolt
-dbms.ssl.policy.bolt.enabled=true
-dbms.ssl.policy.bolt.base_directory=certificates/bolt
-dbms.ssl.policy.bolt.private_key=private.key
-dbms.ssl.policy.bolt.public_certificate=public.crt
-dbms.ssl.policy.bolt.client_auth=NONE
-
-# enforcing ssl connection
-server.bolt.tls_level=REQUIRED
-----
-
 === Configure the local DBMS A and grant access to Carol (_Alice_)
 
 As _Alice_, you are responsible for setting up the local *DBMS A*.
 You can create and delete database aliases and grant or deny users' access to them.
 
 In this case, you need to set up a remote database alias that connects to `db1` on *DBMS B* using OIDC credential forwarding and grant _Carol_ access to it.
 
-==== Set up SSO on the local DBMS and map the identity provider groups to the Neo4j roles
-
-In order for _Carol_ to get access to the remote database alias, she needs to be in an identity provider group that is mapped to a Neo4j role that is granted access to that alias.
-
-You set up SSO on the local *DBMS A* and map the identity provider groups to the Neo4j roles that match those on the remote *DBMS B*.
-For details on how to map identity provider groups to Neo4j roles, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles].
-
-[parameters]
-----
-dbms.security.oidc.<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; \
-                                                                   "remote_users" = remote_access
-----
-+
-This is where the permission to use the remote database alias is set.
-See the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] for more details.
-
 ==== Create the remote database alias and grant access to Carol
 
 You create the remote database alias using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias administrative commands].
@@ -338,18 +276,17 @@ CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687"
 ----
 
 . Create a custom role to track all users shared on a remote connection, so that they remain trackable:
-See the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] for more information.
 +
 [source, Cypher]
 ----
 CREATE ROLE remote_access
 ----
-. Grant access to the remote database alias to the `remote_access` role and assign it to _Carol_.
+. Grant the `remote_access` role access to the remote database alias and assign the role to _Carol_:
 +
 [source, Cypher]
 ----
 GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access
-GRANT ROLE remote_access TO Carol
+GRANT ROLE remote_access TO carol
 ----
 +
 [NOTE]
@@ -358,6 +295,62 @@ If a transaction modifies an alias (e.g. changing the database targeted on *DBMS
 This prevents issues such as a transaction executing against multiple target databases for the same alias.
 ====
 
+==== Set up SSO on the local DBMS and map the identity provider groups to the Neo4j roles
+
+In order for _Carol_ to get access to the remote database alias, she needs to be in an identity provider group that is mapped to a Neo4j role that is granted access to that alias.
+
+You set up SSO on the local *DBMS A* and map the identity provider groups to the Neo4j roles.
+For details, see the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] and xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles].
+
+[parameters]
+----
+dbms.security.oidc.<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; \
+                                                                   "remote_users" = remote_access
+----
+
+=== Configure the remote DBMS B (_Bob_)
+
+As _Bob_, you are responsible for setting up the remote *DBMS B*.
+You can create and delete users and grant or deny privileges on the databases managed by *DBMS B*.
+
+In this example, you need to ensure that _Carol_ can access `db1` on *DBMS B* using OIDC credential forwarding.
+
+. Set up SSO on the remote *DBMS B* and map the identity provider groups to the Neo4j roles.
+The configuration must match the one on the local *DBMS A*.
+For details, see the xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration tutorial] and xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles].
+//If you do not want specific users to access `db2`, here is where you set it.
++
+[parameters]
+----
+dbms.security.oidc.<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; \
+                                                                   "remote_users" = remote_access
+----
+
+. Set up the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts non-local connections if required.
++
+[parameters]
+----
+# accept non-local connections
+server.default_listen_address=0.0.0.0
+
+# configure ssl for bolt
+dbms.ssl.policy.bolt.enabled=true
+dbms.ssl.policy.bolt.base_directory=certificates/bolt
+dbms.ssl.policy.bolt.private_key=private.key
+dbms.ssl.policy.bolt.public_certificate=public.crt
+dbms.ssl.policy.bolt.client_auth=NONE
+
+# enforcing ssl connection
+server.bolt.tls_level=REQUIRED
+----
 
 == Connect to remote database aliases
 
@@ -372,12 +365,12 @@ USE `db1-remote-alias` MATCH (n) RETURN *
 ----
 
 * Connecting to a remote database alias as a home database.
-This needs to be set by an administrator.
+This needs to be set by an administrator, in this case _Alice_.
 See xref:authentication-authorization/dbms-administration/dbms-user-management-privileges.adoc[User Management] for more information.
 +
 [source, Cypher]
 ----
-ALTER USER alice SET HOME DATABASE `db1-remote-alias`
+ALTER USER carol SET HOME DATABASE `db1-remote-alias`
 ----
 
 == Important notes