Skip to content

docs: updated and added OIDC credential forwarding #2692

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: dev
Choose a base branch
from
Draft

docs: updated and added OIDC credential forwarding #2692

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0d6f9e3
docs: updated and added OIDC credential forwarding
evelinadanielsson Oct 30, 2025
86463fc
updated documentation
evelinadanielsson Nov 5, 2025
f36bcba
add version tag
evelinadanielsson Nov 5, 2025
8d95871
docs: extending docs on oidc credential forwarding
evelinadanielsson Nov 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 46 additions & 8 deletions ...OT/pages/database-administration/aliases/manage-aliases-standard-databases.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -379,18 +379,25 @@ SHOW ALIAS `northwind-2022` FOR DATABASE YIELD name, properties
[[alias-management-create-remote-database-alias]]
Copy link
Contributor

@l-heemann l-heemann Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page begins with a table for SHOW ALIAS, do we want to update that in this PR or do we want to leave the SHOW update as a separate PR?

Copy link
Contributor Author

@evelinadanielsson evelinadanielsson Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might add this into this PR, but Therese mentioned if we wanted to have the column behind the feature flag or not... Have to think about that one, do you have any preferences? We would return STORED NATIVE CREDENTIALS for remote aliases and null otherwise. We have started to describe OIDC in other places in the documentation so we might just keep it as is and don't have it behind the feature flag

=== Create database aliases for remote databases

A database alias can target a remote database by providing an URL and the credentials of a user on the remote Neo4j DBMS.
A database alias can target a remote database by providing a URL and the credentials of a user on the remote Neo4j DBMS.
See xref:database-administration/aliases/remote-database-alias-configuration.adoc[] for the necessary configurations.

Since remote database aliases target databases that are not in this DBMS, they do not fetch the default Cypher version from their target like the local database aliases.
Instead, they are assigned the version given by xref:configuration/configuration-settings.adoc#config_db.query.default_language[`db.query.default_language`], which is set in the `neo4j.conf` file.
Alternatively, you can specify the version in the `CREATE ALIAS` or `ALTER ALIAS` commands.
See xref:database-administration/aliases/manage-aliases-standard-databases.adoc#set-default-language-for-remote-database-aliases[] and xref:database-administration/aliases/manage-aliases-standard-databases.adoc#alter-default-language-remote-database-alias[] for more information.

When creating a remote database alias, the credentials used to target to the remote DBMS need to be specified and can be either:

* `STORED NATIVE CREDENTIALS`, using the credentials of a single native user on the remote DBMS.
* `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local DBMS. The user needs to be logged in with an identity provider supporting OIDC. label:new[Introduced in 2025.10]

To use the credentials of a native user on the remote DBMS, `USER` and `PASSWORD` need to be set when creating the alias.

.Query
[source, cypher]
----
CREATE ALIAS `remote-northwind` FOR DATABASE `northwind-graph-2020`
CREATE ALIAS `remote-northwind-stored-credentials` FOR DATABASE `northwind-graph-2020`
AT "neo4j+s://location:7687"
USER alice
PASSWORD 'example_secret'
Expand All @@ -401,20 +408,51 @@ To view the remote database alias details, use the `SHOW ALIASES FOR DATABASE` c
.Query
[source, cypher]
----
SHOW ALIAS `remote-northwind`
SHOW ALIAS `remote-northwind-stored-credentials`
FOR DATABASE
----

.Result
[role="queryresult"]
----
+----------------------------------------------------------------------------------------------------------+
| name | composite | database | location | url | user |
+----------------------------------------------------------------------------------------------------------+
| "remote-northwind" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "alice" |
+----------------------------------------------------------------------------------------------------------+
+-----------------------------------------------------------------------------------------------------------------------------+
| name | composite | database | location | url | user |
+-----------------------------------------------------------------------------------------------------------------------------+
| "remote-northwind-stored-credentilas" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | "alice" |
+-----------------------------------------------------------------------------------------------------------------------------+
----

The `OIDC CREDENTIAL FORWARDING` clause is used to configure a remote database alias to use the logged-in user's OIDC credentials to authenticate to the remote DBMS.
Copy link
Contributor

@l-heemann l-heemann Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should be very clear that this feature only works with OIDC, maybe link to the OIDC docs even? https://neo4j.com/docs/operations-manual/current/authentication-authorization/sso-integration/

Unrelated to the docs:
We should test what happens if you create a credential forwarding alias on a DBMS that doesn't have any OIDC providers. Maybe that should also return the "this has no effect" notification?

We should also test what happens if you attempt to access a credential forwarding alias with native/LDAP auth.

Copy link
Contributor Author

@evelinadanielsson evelinadanielsson Nov 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'v added a note under the Connect to remote database aliases section

In order to use this method to authenticate, the local DBMS and remote DBMS needs to have SSO authentication and authorization through identity providers implementing the OIDC standard configured, see the xref:authentication-authorization/sso-integration.adoc[SSO integration] on how to configure OIDC identity providers.

.Query
[source, cypher]
----
CREATE ALIAS `remote-northwind-oidc-credential-forwarding` FOR DATABASE `northwind-graph-2020`
AT "neo4j+s://location:7687"
OIDC CREDENTIAL FORWARDING
----

Since the alias use the credentials of the logged-in user when targeting the remote DBMS, there are no stored credentials and user will be `NULL`.

.Query
[source, cypher]
----
SHOW ALIAS `remote-northwind-oidc-credential-forwarding`
FOR DATABASE
----

.Result
[role="queryresult"]
----
+-------------------------------------------------------------------------------------------------------------------------------------+
| name | composite | database | location | url | user |
+-------------------------------------------------------------------------------------------------------------------------------------+
| "remote-northwind-oidc-credential-forwarding" | NULL | "northwind-graph-2020" | "remote" | "neo4j+s://location:7687" | NULL |
+-------------------------------------------------------------------------------------------------------------------------------------+
----


You can also use `IF EXISTS` or `OR REPLACE` when creating remote database aliases.
It works the same way as described in the <<_use_if_exists_or_or_replace_when_creating_database_aliases, Use `IF EXISTS` or `OR REPLACE` when creating database aliases>> section.
Both check for any remote or local database aliases (with `IF NOT EXISTS` also checking for databases).
Expand Down
165 changes: 149 additions & 16 deletions .../pages/database-administration/aliases/remote-database-alias-configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,39 +14,46 @@ The following steps describe the setup required to define a remote database alia
They are also useful should there be any changes in the name of the databases or the location of standalone servers and cluster instances.
Additionally, you will also find information here on best practices and additional guidance on any changes in the configuration.

== Setup example

In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_:

image::remote-alias-overview.svg[title="Overview of the required remote database alias setup", role="middle"]

A remote alias defines:

* Which user of the remote **DBMS B** is used.
* Where the remote database is located.
* How to connect to the remote database using driver settings.

When creating the remote database alias, it can be configured to authenticate with either:

* `STORED NATIVE CREDENTIALS`, the credentials of a single native user on the remote **DBMS B**.
* `OIDC CREDENTIAL FORWARDING`, forwarding the bearer authentication token from the logged-in user on the local **DBMS A**. The user needs to be logged in with an identity provider supporting OIDC. label:new[Introduced in 2025.10]


[[setup-example-stored-native-credentials]]
== Setup example with stored native credentials

In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_:

image::remote-alias-overview.svg[title="Overview of the required remote database alias setup when using stored credentials", role="middle"]


[NOTE]
====
A remote database alias is only accessible to users with appropriate privileges.
In the example above, _Bob_ is the administrator responsible for deciding which databases (`Db1` or `Db2`) the remote aliases can write and/or read.
Meanwhile, _Alice_ is the administrator that assigns who has access to the privileges set by _Bob_.
In the example, _Alice_ will assign that access to _Carol_.

See lxref:authentication-authorization/dbms-administration.adoc[DBMS privileges] for more information.
See xref:authentication-authorization/dbms-administration.adoc[DBMS privileges] for more information.
====

_Carol_ can use her own regular credentials to access the remote database `Db1` in DBMS after _Alice_ assigns this privilege to her user profile.
This configuration will also allow _Carol_ to access `Db2` in **DBMS B**.
If the administrators decide this should not be the case, then _Bob_ must define the appropriate privileges (see xref:authentication-authorization/index.adoc[Authentication and authorization] for further information).

== Configure a remote DBMS (_Bob_)
=== Configure a remote DBMS (_Bob_)

In the suggested example, there are two administrators: _Alice_ and _Bob_.
_Bob_ is the administrator responsible for the setup of the remote DBMS, which includes the following steps:

. Create the user profile to share with _Alice_.
Currently, only user and password-based authentication (e.g. native authentication) are supported.
. Define the permissions for the user. If you don’t want this user to access `Db2`, here is where you set it.
. Securely transmit the credentials to _Alice_, setting up the link to database `Db1`.
It is recommended to create a custom role to track all users shared on a remote connection, so that they remain trackable.
Expand Down Expand Up @@ -79,7 +86,7 @@ server.bolt.tls_level=REQUIRED
----

[[remote-alias-config-DBMS_admin-A]]
== Configure a DBMS with a remote database alias (_Alice_)
=== Configure a DBMS with a remote database alias (_Alice_)

As _Alice_, you need to generate an encryption key.
In this case, the credentials of a user of **DBMS B** are reversibly encrypted and stored in the system database of **DBMS A**.
Expand Down Expand Up @@ -145,7 +152,7 @@ chmod 640 conf/neo4j.conf
bin/neo4j start --expand-commands
----

== Manage remote database aliases
=== Manage remote database aliases

You can use the xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias commands] to manage remote database aliases.
In this case, it is strongly recommended to connect to a remote database alias with a secured connection.
Expand All @@ -154,15 +161,15 @@ Please note that only client-side SSL is supported.
By default, remote aliases require a secured URI scheme such as `neo4j+s`.
This can be disabled by setting the driver setting `ssl_enforced` to `false`.

For example, the following command can be used to create a remote database alias:
For example, the following command can be used to create a remote database alias with stored native credentials:

[source, Cypher]
----
CREATE ALIAS `remote-neo4j` FOR DATABASE `neo4j` AT "neo4j+s://location:7687" USER alice PASSWORD 'secretpassword'
----

In order to do so, either lxref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management]
or lxref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges are required.
In order to do so, either xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management]
or xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges are required.
The permission to create an alias can be granted like this:

[source, Cypher]
Expand All @@ -183,7 +190,7 @@ If a transaction modifies an alias (e.g. changing the database targeted on **DBM
This prevents issues such as a transaction executing against multiple target databases for the same alias.
====

== Change the encryption key
=== Change the encryption key

If the encryption key in the keystore is changed, the encrypted credentials for existing remote database aliases will need to be updated as they will no longer be readable.

Expand All @@ -193,6 +200,120 @@ If there is a failure when reading the keystore file, investigate the `debug.log
In case it is not possible to connect to the remote alias after its creation, verify its settings by connecting to the remote database at https://browser.neo4j.io/ or at your local browser.
====

[role=label--new-2025.10]
[[setup-example-credential-forwarding]]
== Setup example with OIDC credential forwarding

In order to use OIDC credential forwarding, both *DBMS A* and *DBMS B* need to support the same OIDC identity provider, see the xref:authentication-authorization/sso-integration.adoc[SSO integration] on how to enable OIDC.

In this example, _Alice_ is an administrator and _Carol_ is a user who needs access to a database managed by _Bob_:

In the example above, _Carol_ logs in to *DBMS A* through an OIDC compliant identity provider by offering a token from the provider.
The token is used to set the username and determine the identity provider groups of the user.
_Alice_ is the admin of *DBMS A* and has set up SSO for the identity provider and configured the mapping of the identity provider groups to the Neo4j roles, such that _Carol_ can use the remote database alias to connect to the remote database `Db1`.
Additionally, _Bob_ needs to configure the *DBMS B* to support SSO with the same identity provider used by _Carol_ to log in to *DBMS A*. _Bob_ also needs to configure the mapping of the identity provider groups to the Neo4j roles such that the _Carol's_ identity provider groups gives the appropriate privileges to access `Db1` on the *DBMS B*.


[CAUTION]
====
While it is permitted to use different OIDC configurations across distinct DBMS instances (e.g., local vs. target), users must be aware of the resulting privilege disparity.
A user's effective permissions are not dictated by the identity provider groups alone, but by the mapping of those groups to the roles defined within each specific Neo4j DBMS, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles].
Crucially, if the OIDC configuration settings differ between the local DBMS and the target DBMS, the user will have different effective privileges on those systems.
This configuration independence can lead to privilege inconsistency (e.g., over-privileging or unexpected access denial).
====

=== Configure a remote DBMS (_Bob_)


In the suggested example, there are two administrators: _Alice_ and _Bob_.
_Bob_ is the administrator responsible for the setup of the remote DBMS, which includes the following steps:

. Set up SSO and support for the identity provider.
. Map the identity provider groups to the Neo4j roles. If you don’t want specific users to access `Db2`, here is where you set it.

Additionally, _Bob_ must do the required setup for the link:https://neo4j.com/docs/operations-manual/current/security/ssl-framework/[SSL framework] and check whether the database accepts a non-local connection if required.

[source, Example of additional configuration]
----
# accept non-local connections
server.default_listen_address=0.0.0.0

# configure ssl for bolt
dbms.ssl.policy.bolt.enabled=true
dbms.ssl.policy.bolt.base_directory=certificates/bolt
dbms.ssl.policy.bolt.private_key=private.key
dbms.ssl.policy.bolt.public_certificate=public.crt
dbms.ssl.policy.bolt.client_auth=NONE

# enforcing ssl connection
server.bolt.tls_level=REQUIRED
Copy link
Contributor

@l-heemann l-heemann Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We may want the OIDC settings here as well, to show that they should be the same on both DBMSs

dbms.security.oidc.<provider>.config=
dbms.security.oidc.<provider>.token_endpoint=
dbms.security.oidc.<provider>.issuer=
dbms.security.oidc.<provider>.params=
dbms.security.oidc.<provider>.audience=
dbms.security.oidc.<provider>.display_name=
dbms.security.oidc.<provider>.well_known_discovery_uri=
dbms.security.oidc.<provider>.claims.groups=

Copy link
Contributor

@l-heemann l-heemann Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although it adds a lot of noise as well, maybe something like this is more useful?

# 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

Copy link
Contributor Author

@evelinadanielsson evelinadanielsson Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Went for the second option here


# OIDC settings - these should be the same on both DBMSs
dbms.security.oidc.<provider>.well_known_discovery_uri=http://example.com/.well-known/discovery
<...>
dbms.security.oidc.<provider>.claims.groups=groups
dbms.security.oidc.<provider>.authorization.group_to_role_mapping= "engineers" = admin; \
"collaborators" = reader
----

=== Configure a DBMS with a remote database alias (_Alice_)

The steps _Alice_, need to take are:

. Set up SSO and support for the identity provider.
. Map the identity provider groups to the Neo4j roles. This is where the permission to use the remote database alias is set.
Comment on lines +263 to +264
Copy link
Contributor

@l-heemann l-heemann Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we might want more details here. I.e. the same OIDC config as for B, and maybe the command to create the alias and the commands to give Carol a role with access on the alias.

Copy link
Contributor Author

@evelinadanielsson evelinadanielsson Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Duplicated and moved the Manage remote database aliases section to be included under both setup examples. A bit of duplicate information but might be a better way of having it, the Connect to remote database aliases still lies outside the two setup examples.


[source, Example of additional configuration]
----
# OIDC settings - these should be the same on both DBMSs
dbms.security.oidc.<provider>.well_known_discovery_uri=http://example.com/.well-known/discovery
<...>
dbms.security.oidc.<provider>.claims.groups=groups
dbms.security.oidc.<provider>.authorization.group_to_role_mapping= "engineers" = admin; \
"collaborators" = reader
----
=== Manage remote database aliases

You can use the xref:database-administration/aliases/manage-aliases-standard-databases.adoc[alias commands] to manage remote database aliases.
In this case, it is strongly recommended to connect to a remote database alias with a secured connection.

Please note that only client-side SSL is supported.
By default, remote aliases require a secured URI scheme such as `neo4j+s`.
This can be disabled by setting the driver setting `ssl_enforced` to `false`.

For example, the following command can be used to create a remote database alias with OIDC credential forwarding:

[source, Cypher]
----
CREATE ALIAS `remote-neo4j` FOR DATABASE `neo4j` AT "neo4j+s://location:7687" OIDC CREDENTIAL FORWARDING
----

In order to do so, either xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[database management]
or xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[alias management] privileges are required.
The permission to create an alias can be granted like this:

[source, Cypher]
----
GRANT CREATE ALIAS ON DBMS TO administrator
----

Here is how to grant the xref:authentication-authorization/database-administration.adoc#access-control-database-administration-access[`ACCESS` privileges] to use the remote database alias:

[source, Cypher]
----
GRANT ACCESS ON DATABASE `remote-neo4j` TO admin
----

In order for _Carol_ to get access to the remote database alias, she needs to be in an identity provider group that is mapped to a Neo4j role that is granted access to alias. In this example, if _Carol_ is in the identity provider group `engineers` which is mapped to the `admin` role, she will get the privileges of an `admin` and access to `remote-neo4j`.
For details on how to map identity provider groups to Neo4j roles, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles].

[NOTE]
====
If a transaction modifies an alias (e.g. changing the database targeted on **DBMS B**), other transactions concurrently executing against that alias may be aborted and rolled back for safety.
This prevents issues such as a transaction executing against multiple target databases for the same alias.
====


== Connect to remote database aliases

A user can connect to a remote database alias the same way they would do to a database.
Expand All @@ -208,7 +329,7 @@ USE `remote-neo4j` MATCH (n) RETURN *

* Connecting to a remote database alias as a home database.
This needs to be set by Administrator A.
See more about lxref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[User Management].
See more about xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[User Management].

[source, Cypher]
----
Expand All @@ -220,3 +341,15 @@ ALTER USER alice SET HOME DATABASE `remote-neo4j`
Remote alias transactions will not be visible in `SHOW TRANSACTIONS` on **DBMS A**.
However, they can be accessed and terminated on the remote database when connecting with the same user.
====

[NOTE]
====
Action on the remote DBMS are all attributed to the user configured for the remote database alias.
In the case of using `STORED NATIVE CREDENTIALS`, the same credentials are used to connect to the remote DBMS independent on which end-user made the query targeting the remote alias. This will result in the stored native user being logged in the audit trails on the remote DBMS for all queries using the remote database alias.
When using `OIDC CREDENTIAL FORWARDING` the actual end-user's credentials and permissions will be used, this will result in per-user audit trails being logged on the remote DBMS.
====

[NOTE]
Copy link
Contributor Author

@evelinadanielsson evelinadanielsson Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A lot of [NOTE] containers after each other, is this ok or should we structure it in a different way?

====
When using a remote database alias with OIDC credential forwarding, the user needs to be logged in to the local DBMS with OIDC, otherwise there is no token to forward and the access to the remote database will be denied with `GQLSTATUS 42NFF`.
====