docs: updated and added OIDC credential forwarding COPS-264, COPS-284, COPS-319

[evelinadanielsson]

We have added OIDC credential forwarding as an additional way to configure a remote database alias. We need to update and add documentation to describe how it is supposed to be used and how it works.

[evelinadanielsson]

Maybe we should have a figure showing the OIDC flow as well... Something like the one bellow. As of now, the added documentation is written as if there is a figure included.

[l-heemann]

We probably need to have one of these version tags somewhere indicating that CREDENTIAL FORWARDING is new.

I believe we would want that to show the version in which we set internal.cypher.enable_oidc_credential_forwarding to default to true. Before we set that flag to true I think we would want the SHOW updates to be done and also have done our manual testing.

Question for the docs reviewer: Do we ever document features that aren't released yet, e.g. "This feature is in beta and you need to set config x.y.z=true to access it"

[evelinadanielsson]

I've added a few labels now

[renetapopova]

Sometimes we do document them; sometimes we don't. If we document them, then we also label them with beta, and the version of the feature is introduced. But I don't know when we do one or the other. I guess it's a PR decision.

[l-heemann]

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.

[evelinadanielsson]

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.

[evelinadanielsson]

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

[l-heemann]

I think it's fine, maybe docs reviewer has a better idea 🤷

[evelinadanielsson]

Included this figure, matching the design of the one for stored credentials on the same page.

[l-heemann]

Included this figure, matching the design of the one for stored credentials on the same page.

I think the "token" arrow should go from IDP to Carol. Do we need the second DB in DBMS B?

[l-heemann]

Starting to look very good I think. Mostly some nit-picks left

[l-heemann]

Maybe this is a good point to link to
https://neo4j.com/docs/operations-manual/current/tutorial/tutorial-sso-configuration/

Same for "Configure local DBMS" below

[evelinadanielsson]

I added SSO tutorials as you mentioned, but I have previously added xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles] in other places of in the docs when talking about the mapping, which links to https://neo4j.com/docs/operations-manual/2025.10/authentication-authorization/sso-integration/#auth-sso-map-idp-roles

[l-heemann]

LGTM

[l-heemann]

I think it's fine, maybe docs reviewer has a better idea 🤷

[renetapopova]

I've made some editorial changes, but I haven't finished reviewing the PR.

[evelinadanielsson]

@renetapopova this feature is not yet GA so we can keep the do not merge tag on til further 🙂

[renetapopova]

I think the page 'Configuring remote database aliases' looks great now! I'm wondering only if we need to add OIDC CREDENTIALS FORWARDING to the page Database management syntax?

That's a very good point! @evelinadanielsson, @l-heemann?

[evelinadanielsson]

@renetapopova Great, I'm having a look at the PR, have some comments on certain things, but over all it starts looking great!

[l-heemann]

I'm handing this over to Evelina to review since I am changing teams. No more objections from my side

[evelinadanielsson]

@renetapopova have made some changes, can you have a look at them. Yes, we should probably add OIDC CREDENTIALS FORWARDING to the page Database management syntax. Will do that in another commit.

[renetapopova]

Thanks, @evelinadanielsson. Just some small editorial suggestions and one comment. Otherwise, I think it looks great!

[renetapopova]

Here, the role is different from the one configured on DBMS A. Don't they need to be the same?

[evelinadanielsson]

They don't need to be the the same no. As the text says in the Caution block. The user belongs to the group remote users in both systems, as they receive this group from the identity provider, this group is then matched to different roles in Neo4j. So there is nothing that stops the user from having the group assigned to different roles in different systems. Now our custom roles are pretty limited to what they can do, but this is more important to think about if one uses the built-in roles of Neo4j. In fact, it is likely that costumers will have different group to role mapping between the systems if custom defined roles are used, since some roles may only exist on one of the systems. This cation tab is more to let the user know that this is a critical thing that they need to think about.

While it is possible to use different OIDC configurations across distinct DBMS instances (DBMS A & B in this example), database administrators 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).

[evelinadanielsson]

Eg, what is DBMS B also have remote aliases and thus also would need a remote_access role, then it would be mapped to users both able to read db1 and to access the remote database alias on DBMS B.

[evelinadanielsson]

Let me know if things are still a bit confusing :)

[renetapopova]

I somehow got confused by these sentences in the admonition: "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. 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)."

[renetapopova]

I understand it as that the mapping should be the same.

[renetapopova]

Maybe we can rewrite the admonition to something like this:

OIDC group-to-role mappings are defined per DBMS, which means 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 (DBMS A and DBMS B in this example) lead to different effective privileges for the same user.
While it is possible to use different OIDC configurations across DBMS instances, database administrators must be aware of the resulting privilege disparity and ensure that group-to-role mappings intended to grant equivalent access remain consistent across DBMSs, to avoid privilege inconsistency (for example, over-privileging or unexpected access denial).

[renetapopova]

Also, when do we plan to merge it?

[evelinadanielsson]

We were planning to make it GA for this last cut off 2025.12, however something technical versin of how the feature is implemented came around last minute, and we decided to revert the PR to release it, so we could discuss the details of the technical implementation first, to see if we want to make any changes.

So we are currently aiming for 2026.01 (if that's how you count the version).

[renetapopova]

Great! Thank you. I'll add a label.

[evelinadanielsson]

@renetapopova I rewrote the part you pointed out, very much like you suggestion. Have a look and see if this makes things more clear.

[neo4j-docops-agent]

This PR includes documentation updates
View the updated docs at https://neo4j-docs-operations-2692.surge.sh

Updated pages:

• Managing database aliases in composite databases
• Managing database aliases for standard databases
• Configuring remote database aliases
• Database management command syntax
• Setting up and using a composite database

[renetapopova]

Looks great! Thank you @evelinadanielsson!