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..d96b28a26 --- /dev/null +++ b/modules/ROOT/images/remote-alias-credential-forwarding-overview.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/modules/ROOT/images/remote-alias-overview.svg b/modules/ROOT/images/remote-alias-overview.svg index d51cdcda9..7da5e4f8e 100644 --- a/modules/ROOT/images/remote-alias-overview.svg +++ b/modules/ROOT/images/remote-alias-overview.svg @@ -1,42 +1,43 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 69a420f25..718e7714b 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 1c6194786..4076852b8 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 @@ -79,20 +79,22 @@ The `YIELD *` clause returns the full set of columns. The required privileges are described in the xref:authentication-authorization/dbms-administration/dbms-alias-management-privileges.adoc[The DBMS ALIAS MANAGEMENT privileges]. .Available columns -[options="header" cols="2m,4a,2m"] +[options="header" cols="2m,4a,2m,2a"] |=== -| Column | Description | Type +| Column | Description | Type | Default output | name -| The fully qualified name of the database alias. label:default-output[] +| The fully qualified name of the database alias. | STRING +| {check-mark} | composite -| The name of the composite database this alias belongs to, or `null` if the alias does not belong to a composite database. label:default-output[] +| The name of the composite database this alias belongs to, or `null` if the alias does not belong to a composite database. | STRING +| {check-mark} | database -| The name of the target database. label:default-output[] +| The name of the target database. This column is filtered according to the `ACCESS` privileges of the user. However, some privileges enable users to see additional databases regardless of their `ACCESS` privileges: @@ -104,33 +106,45 @@ However, some privileges enable users to see additional databases regardless of If a user has not been granted the `ACCESS` privilege to the target database and none of the above special cases apply, then it is not visible to the user and this column will be `null`. | STRING +| {check-mark} | location -| The location of the database, either `local` or `remote`. label:default-output[] +| The location of the database, either `local` or `remote`. | STRING +| {check-mark} | url -| Target location or `null` if the target is local. label:default-output[] +| Target location or `null` if the target is local. | STRING +| {check-mark} + +| credentials +| label:new[Introduced in 2025.x] 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. +| STRING +| {check-mark} | 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[] +| 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. | STRING +| {check-mark} | driver | The driver options for connection to the remote database or `null` if the target database is local. List of xref::database-administration/aliases/manage-aliases-standard-databases.adoc#alias-management-create-remote-database-alias-driver-settings[driver settings] allowed for remote database aliases. | MAP +| | defaultLanguage | label:new[Introduced in 2025.06] The default language for non-constituent remote database aliases or `null` if it is a constituent or local database alias. | STRING +| | properties | Any properties set on the database alias. | MAP +| |=== @@ -148,13 +162,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 +184,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 +204,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 +319,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 @@ -379,7 +393,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,38 +401,83 @@ 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, you need to specify the credentials used to target to the remote DBMS. +You can choose between two types of credentials: + +* `STORED NATIVE CREDENTIALS`, using the credentials of a single native user on the remote DBMS. +* label:new[Introduced in 2025.x] `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local DBMS. +The user must be logged in with an identity provider supporting OIDC. + +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). + +==== Create remote database aliases with stored native credentials + +You can create a remote database alias using stored native credentials by specifying the `USER` and `PASSWORD` clauses when creating the alias. +For example: + .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' ---- -To view the remote database alias details, use the `SHOW ALIASES FOR DATABASE` command: +Verify that the remote database alias has been created correctly using the `SHOW ALIASES FOR DATABASE` command: .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 | credentials | user | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| "remote-northwind-stored-credentilas" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- -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). +==== Create remote database aliases with OIDC credential forwarding + +You can create a remote database alias using OIDC credential forwarding by specifying the `OIDC CREDENTIAL FORWARDING` clause when creating the alias. +The `OIDC CREDENTIAL FORWARDING` clause configures the remote database alias to use the logged-in user's OIDC credentials to authenticate to it. +To use this method for authentication, both the local and remote DBMSs must have SSO authentication and authorization through identity providers that implement the OIDC standard configured. +See the xref:authentication-authorization/sso-integration.adoc[SSO integration] for details 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 uses the credentials of the logged-in user when targeting the remote DBMS, there are no stored credentials, and the user will be `NULL`. + +.Query +[source, cypher] +---- +SHOW ALIAS `remote-northwind-oidc-credential-forwarding` +FOR DATABASE +---- +.Result +[role="queryresult"] +---- ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| 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 | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +---- [[alias-management-create-remote-database-alias-driver-settings]] ==== Create remote database aliases with driver settings @@ -429,7 +488,7 @@ This is the list of the allowed driver settings for remote database aliases: * `ssl_enforced` (Default: `true`) -- SSL for remote database alias drivers is configured through the target URL scheme. If `ssl_enforced` is set to true, a secure URL scheme is enforced. -It is be validated when the command is executed. +It will be validated when the command is executed. * `connection_timeout` (For details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection.connect_timeout[dbms.routing.driver.connection.connect_timeout].) * `connection_max_lifetime` (For details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection.max_lifetime[dbms.routing.driver.connection.max_lifetime].) * connection_pool_acquisition_timeout -- for details, see xref:configuration/configuration-settings.adoc#config_dbms.routing.driver.connection.pool.acquisition_timeout[dbms.routing.driver.connection.pool.acquisition_timeout]. @@ -465,11 +524,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] @@ -603,9 +662,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 @@ -627,6 +686,18 @@ 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 a remote database alias credential type (`STORED NATIVE CREDENTIALS` or `OIDC CREDENTIAL FORWARDING`) using the `ALTER ALIAS` command is currently not supported. +To change the type of credentials, you must drop the remote database alias and replace it with a new one. + +[CAUTION] +==== +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 `{}`. @@ -752,10 +823,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/database-administration/aliases/remote-database-alias-configuration.adoc b/modules/ROOT/pages/database-administration/aliases/remote-database-alias-configuration.adoc index f5321285b..a0dc4d69c 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 @@ -4,66 +4,110 @@ [[manage-remote-aliases]] = Configuring remote database aliases -A remote database alias can be used to provide connection to one or more graphs, on one or more remote standalone servers or clusters. +You can use a remote database alias to connect to a graph located on a remote standalone server or cluster. Although remote database aliases do not store any data, they enable users or applications to perform queries on remote databases as if they were on the local DBMS server. All configurations can be done using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[administrative commands] on a running system. -Any changes are automatically synchronized across all instances of a cluster. +Any changes are automatically synchronized across all members of a cluster. -The following steps describe the setup required to define a remote database alias both for local and remote DBMSs. -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. +When creating the remote database alias, it can be configured to authenticate with either: -== Setup example +* `STORED NATIVE CREDENTIALS`, the credentials of a single native user on the remote DBMS. +* label:new[Introduced in 2025.x] `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. -In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_: +By creating a remote database alias, you define: -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. +* Which credentials to use to authenticate to the remote database. * Where the remote database is located. * How to connect to the remote database using driver settings. [NOTE] ==== +To manage remote database aliases, you must have either xref:authentication-authorization/dbms-administration/dbms-database-management-privileges.adoc[database management] +or xref:authentication-authorization/dbms-administration/dbms-alias-management-privileges.adoc[alias management] privileges. + +For example, the following command grants the permission to create an alias to the `administrator` role: + +[source, Cypher] +---- +GRANT CREATE ALIAS ON DBMS TO administrator +---- +==== + +By granting access to the remote database alias, you define which users can use it to connect to the database on the remote DBMS. + +[CAUTION] +==== +Many of the xref:authentication-authorization/built-in-roles.adoc[built-in roles] that Neo4j provides have access to all databases, this includes any remote database alias. +==== + +The following examples describe how to set up access to a remote database via a remote database alias by using either stored native credentials, or OIDC credential forwarding. +They assume that you have two separate DBMS instances: a local *DBMS A* and a remote *DBMS B*. + +[[setup-example-stored-native-credentials]] +== Setup example with stored native credentials + +In this example, _Alice_ is an administrator of *DBMS A*, _Bob_ is an administrator of *DBMS B*, 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 native credentials", role="middle"] + 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. +In this example, _Bob_ is the administrator responsible for deciding which database (`db1` or `db2`) the remote database 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_ will assign that access to _Carol_. - +In the example, _Alice_ assigns that access to _Carol_. See xref:authentication-authorization/dbms-administration/index.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_) +_Bob_ creates a user profile on *DBMS B*, grants it access to database `db1` and shares the credentials with _Alice_. +Then, _Alice_ creates a remote database alias `db1-remote-alias` on *DBMS A* that connects to `db1` on *DBMS B* using the shared credentials. +After _Alice_ grants _Carol_ access to the remote database alias, _Carol_ can log in to the local *DBMS A*, using her own credentials, and through the remote database alias connect to `db1` on *DBMS B*. +//This configuration will also allow _Carol_ to access `db2` in *DBMS B*, if _Bob_ grants the necessary privileges to the user profile shared with _Alice_. +//See xref:authentication-authorization/index.adoc[Authentication and authorization] for further information. + +[CAUTION] +==== +All operations executed on the remote DBMS are performed under the identity of the user associated with the remote database alias. +When using `STORED NATIVE CREDENTIALS`, the same credentials are used to connect to the remote DBMS regardless of which end-user made the query targeting the remote database alias. +As a result, a user's roles and permissions on the local DBMS do not restrict the actions that are processed on the remote DBMS. +Any local user who can access the remote database alias effectively inherits the permissions granted to the user configured for that alias. +It is therefore essential to watch of any privilege mismatch that can result from this configuration (e.g., over-privileging or under-privileging). + +For example, suppose the shared user on *DBMS B*, who is shared and configured for the remote database alias on the *DBMS A*, is assigned the built-in role `editor`, allowing both read and write access. +A local user on *DBMS A* may only have the `reader` role and therefore be limited to read-only operations locally. +However, that user can access the remote database alias and thus operate on DBMS B using the alias’s credentials, and therefore gain the associated write privileges, enabling them to modify data on *DBMS B* despite their limited local role. +==== + +=== Configure the remote DBMS B (_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: +As _Bob_, you are responsible for the remote *DBMS B*. +You can create and delete users and grant or deny privileges on the databases managed by *DBMS B*. -. 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. +In this example, you create a user called `remote_user`, which will be used by the remote database alias to connect to `db1`, and share the credentials with _Alice_. -[source, Example Setup Administrator B] +. Create the user profile to share with _Alice_: ++ +[source, Cypher] ---- -CREATE USER alice SET PASSWORD 'secretpassword' -CREATE ROLE remote -GRANT ACCESS ON DATABASE neo4j TO remote -GRANT MATCH {*} ON GRAPH neo4j TO remote -GRANT ROLE remote TO alice +CREATE USER remote_user SET PASSWORD 'secretpassword' ---- - -In this case, _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] +. Create a custom role to track all users shared on a remote connection, so that they remain trackable: ++ +[source, Cypher] +---- +CREATE ROLE shared_to_remote +---- +. Grant the `shared_to_remote` role access to `db1` and assign the role to the user profile created for the remote database alias, `remote_user`: ++ +[source, Cypher] +---- +GRANT ACCESS ON DATABASE db1 TO shared_to_remote +GRANT MATCH {*} ON GRAPH db1 TO shared_to_remote +GRANT ROLE shared_to_remote TO remote_user +---- +. 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 @@ -78,15 +122,21 @@ dbms.ssl.policy.bolt.client_auth=NONE # enforcing ssl connection server.bolt.tls_level=REQUIRED ---- +. Securely transmit the credentials to _Alice_, setting up the link to database `db1`. [[remote-alias-config-DBMS_admin-A]] -== Configure a DBMS with a remote database alias (_Alice_) +=== Configure the local DBMS A and grant access to Carol (_Alice_) + +As _Alice_, you are responsible for setting up *DBMS А*. +You can create and delete database aliases and grant or deny users' access to them. -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**. +In this example, you create a remote database alias, called `db1-remote-alias`, which connects to `db1` on *DBMS B* using the credentials shared by _Bob_. -Since the algorithm used is AES/GCM, an AES encryption key needs to be provided. -It should have length 256, and be stored in a password-protected keystore, of format pkcs12. +==== Generate an encryption key + +First, you need to generate an encryption key. +In this case, the credentials of the user `remote_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]: @@ -95,13 +145,15 @@ The key can be generated by using the following keytool command in your terminal keytool -genseckey -keyalg aes -keysize 256 -storetype pkcs12 -keystore [keystore-name] -alias [key-name] -storepass [keystore-password] ---- -[NOTE] +[TIP] ==== -It is recommended to generate the keystore on the same Java version on which Neo4j is run, as the supported encryption algorithms may vary. +It is recommended to generate the keystore using the same Java version as the one on which Neo4j is run, as the supported encryption algorithms may vary. For details on the version of Java required by Neo4j, see link:https://neo4j.com/docs/operations-manual/current/installation/requirements/#deployment-requirements-java[System requirements -> Java]. ==== -The following configuration is necessary for creating a remote database alias: +==== Configure the keystore settings + +After generating the keystore file, you need to configure *DBMS A* to use it by setting the following configuration parameters in the `neo4j.conf` file: [options="header" cols="m,a"] |=== @@ -109,21 +161,20 @@ The following configuration is necessary for creating a remote database alias: | xref:configuration/configuration-settings.adoc#config_dbms.security.keystore.path[`dbms.security.keystore.path`] | The absolute path to the keystore file, including the file name. | xref:configuration/configuration-settings.adoc#config_dbms.security.keystore.password[`dbms.security.keystore.password`] | The password to the keystore file. Use xref:configuration/command-expansion.adoc[Command expansion] to set the password. -| xref:configuration/configuration-settings.adoc#config_dbms.security.key.name[`dbms.security.key.name`] | The name of the secret key +| xref:configuration/configuration-settings.adoc#config_dbms.security.key.name[`dbms.security.key.name`] | The name of the secret key. |=== [CAUTION] ==== -To prevent unauthorized access, the keystore file must be stored in a trusted location. -This is the main way to protect the encrypted passwords which will be stored on the system database. -It shouldn’t be accessible to any user except for the administrator and `neo4j`, for whom the keystore file must be readable. +To prevent unauthorized access, you must store the keystore file in a trusted location. +This is the main way to protect the encrypted passwords that will be stored in the `system` database. +It must not be accessible to any user except for the administrator and `neo4j`, for whom the keystore file must be readable. ==== -In a cluster, _Alice_ needs to share the same keystore file over all instances. - -For example, these would be valid additions to the config when using the suggested keytool command: +In a cluster, you must share the same keystore file among all servers. +For example, these would be valid additions to the configuration when using the suggested keytool command: -[source] +[parameters] ---- dbms.security.keystore.path=/home/secure-folder/keystore-name.pkcs12 dbms.security.keystore.password=$(conf/password.sh) @@ -132,92 +183,248 @@ dbms.security.key.name=key-name Where `password.sh` might look like this: -[source, Password.sh] +[source, bash] ---- #!/bin/bash echo "$KEYSTORE_PASSWORD_ENVIRONMENT_VARIABLE" ---- -Additionally, don’t forget to change the permissions of the configuration file, and start Neo4j with the command expansion flag: +Additionally, do not forget to change the permissions of the configuration file and start Neo4j with the command expansion flag: -[source] +[source, bash] ---- chmod 640 conf/neo4j.conf bin/neo4j start --expand-commands ---- -== Manage remote database aliases +==== Create the remote database alias and grant access to Carol -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. +You create the remote database alias using xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias administrative commands] and grant _Carol_ access to it. -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: +[NOTE] +==== +It is strongly recommended to connect to a remote database alias with a secured connection. +Note that only client-side SSL is supported. +By default, remote database aliases require a secured URI scheme such as `neo4j+s`. +However, if you want to disable the secure URL scheme, you can set the driver setting `ssl_enforced` to `false`. +==== +. Use the following command to create a remote database alias with the stored native credentials shared by _Bob_: ++ [source, Cypher] ---- -CREATE ALIAS `remote-neo4j` FOR DATABASE `neo4j` AT "neo4j+s://location:7687" USER alice PASSWORD 'secretpassword' +CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER remote_user PASSWORD 'secretpassword' ---- -In order to do so, either xref:authentication-authorization/dbms-administration/dbms-database-management-privileges.adoc[database management] -or xref:authentication-authorization/dbms-administration/dbms-alias-management-privileges.adoc[alias management] privileges are required. -The permission to create an alias can be granted using the following command: +. Create a custom role to track all users who have access to the remote database alias (or choose an already existing role): ++ [source, Cypher] ---- -GRANT CREATE ALIAS ON DBMS TO administrator +CREATE ROLE remote_access ---- -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: - +. 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 `remote-neo4j` TO role +GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access +GRANT ROLE remote_access TO carol ---- [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. +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 +==== Changing the encryption key + +If the encryption key in the keystore is changed, the encrypted credentials for all existing remote database aliases requires updating, as they will no longer be readable with the new key. + +[NOTE] +==== +In case of 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 database 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.x] +[[setup-example-credential-forwarding]] +== Setup example with OIDC credential forwarding + +In order to use OIDC credential forwarding, both *DBMS A* and *DBMS B* must 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 of *DBMS A*, _Bob_ is an administrator of *DBMS B*, 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"] + +_Carol_ logs into the local *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 to which the user belongs. + +_Alice_ is the administrator of the local *DBMS A* and sets up SSO for the identity provider and configures the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias, `db1-remote-alias`, to connect to the remote database `db1`. + +_Bob_ configures the remote *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. +He also configures the mapping of the identity provider groups to the Neo4j roles such that the _Carol's_ identity provider groups grant the appropriate privileges to access `db1` on the *DBMS B*. + +[CAUTION] +==== +A user's effective permissions are not dictated by the identity provider groups alone, but by the mapping of those groups to roles defined within each Neo4j DBMS. +See xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. +As a result, different OIDC configurations across distinct DBMS instances may lead to the same user having different effective privileges on those instances, (DBMS A and DBMS B in this example). +While it is possible to use different OIDC configurations across DBMS instances, database administrators must be aware of any privilege disparity that may arise from this and ensure that group-to-role mappings intended to grant equivalent access remain consistent across DBMSs. +This is to avoid privilege inconsistency, such as over-privileging or unexpected access denial. +==== + +=== 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. + +==== 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]. + +[NOTE] +==== +It is strongly recommended to connect to a remote database alias with a secured connection. +Note that only client-side SSL is supported. +By default, remote database aliases require a secured URI scheme such as `neo4j+s`. +However, if you want to disable the secure URL scheme, you can set the driver setting `ssl_enforced` to `false`. +==== -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. +. Use the following command to create a remote database alias using OIDC credential forwarding: ++ +[source, Cypher] +---- +CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING +---- +. Create a custom role to track all users who have access to the remote database alias (or choose an already existing role): ++ +[source, Cypher] +---- +CREATE ROLE remote_access +---- +. Grant the `remote_access` role access to the remote database alias. +The role will be assigned to _Carol_ on login via the mapping of identity provider groups to the Neo4j roles: ++ +[source, Cypher] +---- +GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access +---- ++ [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. ==== +==== 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..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; \ + "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. + +. Create a custom role or choose an existing one. +The roles will be assigned to the users on login via the mapping of identity provider groups to the Neo4j roles: ++ +[source, Cypher] +---- +CREATE ROLE db1_access +---- +. Grant the `db1_access` role access to `db1`: ++ +[source, Cypher] +---- +GRANT ACCESS ON DATABASE db1 TO db1_access +GRANT MATCH {*} ON GRAPH db1 TO db1_access +---- + +. Set up SSO on the remote *DBMS B* 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]. +//If you do not want specific users to access `db2`, here is where you set it. ++ +[parameters] +---- +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; \ + "remote_users" = db1_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 -A user can connect to a remote database alias the same way they would do to a database. -This includes: +You can connect to a remote database alias the same way as you would connect to a standard database using any of the following options: * Connecting directly to the remote database alias. -* The Cypher link:{neo4j-docs-base-uri}/cypher-manual/current/clauses/use[`USE` clause] enables a user to query a remote database alias that they are not directly connected to: - +* Querying a remote database alias that you are not directly connected to using the Cypher link:{neo4j-docs-base-uri}/cypher-manual/current/clauses/use[`USE` clause]: ++ [source, Cypher] ---- -USE `remote-neo4j` MATCH (n) RETURN * +USE `db1-remote-alias` MATCH (n) RETURN * ---- * Connecting to a remote database alias as a home database. -This needs to be set by Administrator A. -See more about xref:authentication-authorization/dbms-administration/dbms-user-management-privileges.adoc[User Management]. - +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 `remote-neo4j` +ALTER USER carol SET HOME DATABASE `db1-remote-alias` ---- -[NOTE] -==== -Remote alias transactions will not be visible in `SHOW TRANSACTIONS` on **DBMS A**. +== Important notes + +When using remote database aliases, keep in mind that: + +* Remote database alias transactions will not be visible in `SHOW TRANSACTIONS` on the local DBMS. However, they can be accessed and terminated on the remote database when connecting with the same user. -==== + +* Actions 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 regardless of which end-user made the query targeting the remote database 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 are used, resulting in per-user audit trails being logged on the remote DBMS. + +* When using a remote database alias with OIDC credential forwarding, the user needs to be logged into the local DBMS with OIDC, otherwise there is no token to forward, and the access to the remote database will be denied with GQLSTATUS link:https://neo4j.com/docs/status-codes/current/errors/gql-errors/42NFF/[`42NFF`]. \ No newline at end of file diff --git a/modules/ROOT/pages/database-administration/syntax.adoc b/modules/ROOT/pages/database-administration/syntax.adoc index 553c36f4a..ca19e48ae 100644 --- a/modules/ROOT/pages/database-administration/syntax.adoc +++ b/modules/ROOT/pages/database-administration/syntax.adoc @@ -392,6 +392,10 @@ CREATE OR REPLACE ALIAS name FOR DATABASE targetName === Create a remote alias +[.tabbed-example] +===== +[role=include-with-cypher-5] +====== [options="header", width="100%", cols="1m,5a"] |=== | Command | Syntax @@ -399,27 +403,63 @@ CREATE OR REPLACE ALIAS name FOR DATABASE targetName | CREATE ALIAS | [source, syntax, role=noheader] ------ +---- CREATE ALIAS name [IF NOT EXISTS] FOR DATABASE targetName AT 'url' USER username PASSWORD 'password' [DRIVER "{" setting: value[, ...] "}"] [DEFAULT LANGUAGE CYPHER {5\|25}] [PROPERTIES "{" key: value[, ...] "}"] ------ +---- [source, syntax, role=noheader] ------ +---- CREATE OR REPLACE ALIAS name FOR DATABASE targetName AT 'url' USER username PASSWORD 'password' [DRIVER "{" setting: value[, ...] "}"] [DEFAULT LANGUAGE CYPHER {5\|25}] [PROPERTIES "{" key: value[, ...] "}"] ------ +---- |=== [NOTE] ==== `[DEFAULT LANGUAGE CYPHER {5|25}]` is available from Neo4j 2025.06 onwards. ==== +====== + +[role=include-with-cypher-25] +====== + +[options="header", width="100%", cols="1m,5a"] +|=== +| Command | Syntax +| CREATE ALIAS +| +[source, syntax, role="noheader"] +---- +CREATE ALIAS name [IF NOT EXISTS] FOR DATABASE targetName +AT 'url' { USER username PASSWORD 'password' \| OIDC CREDENTIAL FORWARDING } +[DRIVER "{" setting: value[, ...] "}"] +[DEFAULT LANGUAGE CYPHER {5\|25}] +[PROPERTIES "{" key: value[, ...] "}"] +---- + +[source, syntax, role="noheader"] +---- +CREATE OR REPLACE ALIAS name FOR DATABASE targetName +AT 'url' { USER username PASSWORD 'password' \| OIDC CREDENTIAL FORWARDING } +[DRIVER "{" setting: value[, ...] "}"] +[DEFAULT LANGUAGE CYPHER {5\|25}] +[PROPERTIES "{" key: value[, ...] "}"] +---- +|=== + +[NOTE] +==== +`[DEFAULT LANGUAGE CYPHER {5|25}]` is available from Neo4j 2025.06 onwards. + +`OIDC CREDENTIAL FORWARDING` is available from Neo4j 2025.x onwards. +==== +====== +===== === Alter a local alias 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 ----