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

[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

[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 🙂

[NataliaIvakina]

If Carol can access db1 directly, why would she need the access to the remote alias of this db1?

[l-heemann]

I agree, usually* Carol would not have access directly on the remote DBMS B. Carol uses her own regular credentials to log into DBMS A and access db1-remote-alias. The alias then uses the stored credentials (alice/secretpassword)** to log into DBMS B and access the database db1.

* There are edge cases where it is useful to have both types of access, but that is out of scope for these docs.
** It is very confusing that we use alice to reference to the person that is administering DBMS A and also use alice as the stored credentials. We should be using different credentials for this.

[l-heemann]

Why are we updating the docs for the stored native credentials? They need a lot of work, I would prefer if we can get the new credential forwarding docs merged before we start improving the existing docs.

[NataliaIvakina]

tbh, this sentence is confusing. Which configuration are we speaking about?
Is the following correct?:
If Alice assigns necessary privileges to Carol to access both databases on a remote DBMS B, then Bob has to grant the same privileges to Carol. And only after aligning all privileges, Carol will get access to the db2.

On the other hand, earlier we say that "Alice is the administrator that assigns who has access to the privileges set by Bob." See line 38.
So, who is the head here: Alice or Bob? We set access to the databases 1 and 2? Is it even important here, in this guide?

[renetapopova]

I understand it like this: Bob grants privileges for accessing dbs in DBMS B to Carol's user profile, which he shares with Alice. Then, Alice decides which of those privileges to assign to Carol to access via the local DBMS. I am not sure how this will work, given that we have just one remote database alias, and it's for db1.

[l-heemann]

The docs are using alice for both the stored credentials and for the person that administers DBMS A. This is confusing. We should change the name for this user to something like alias_user. I will write the rest here as if the Example setup administrator B has been updated to:

CREATE USER alias_user SET PASSWORD 'secretpassword'
CREATE ROLE remote
GRANT ACCESS ON DATABASE db1 TO remote
GRANT MATCH {*} ON GRAPH db1 TO remote
GRANT ROLE remote TO alias_user

Bob is not granting privileges to either Carol nor Alice. Bob is only granting access to alias_user. Bob then gives the username/password for alias_user to Alice.

Bob stays in control over what happens on DBMS B:

• He can delete alias_user
• He can grant or deny the read and write privileges on db1 / db2 to the group remote

Alice creates a remote alias using the credentials given by Bob:

CREATE ALIAS `db1-remote-alias` FOR DATABASE `db1` AT "neo4j+s://location:7687" USER alias_user PASSWORD 'secretpassword'

Anybody who accesses this alias connects to DBMS B as if they where alias_user.

This alias is specifically for db1 on DBMS B. Alice could create another alias for db2 however alias_user (remote) does not yet have access to db2. Bob would need to do:

GRANT ACCESS ON DATABASE db2 TO remote
GRANT MATCH {*} ON GRAPH db2 TO remote

Alice is in control over what happens on DBMS A:

• She can delete the alias
• She can grant or deny the access privilege on db1-remote-alias

Carol is only able to do anything if:

• She is able to log into DBMS A
• Her user account on DBMS A has the privilege to access db1-remote-alias
• The credentials stored on db1-remote-alias are able to log into DBMS B
• The credentials stored on db1-remote-alias have read or write privileges on db1

[NataliaIvakina]

This section is about Carol, isn’t it? When she gets all privileges, she can manage the remote database alias

[renetapopova]

I think so.

[l-heemann]

No. Alice is the administrator of DBMS A and should be the one that is managing the remote database alias.

Carol is a non-admin user, she only uses the alias that Alice has set up.

[NataliaIvakina]

so, this section is about Carol and how she is going to manage remote database alias for db1.

[renetapopova]

I think so, but I am not sure if the command GRANT CREATE ALIAS ON DBMS TO admin is assigned to her or to Alice. Additionally, there has been no administrator role so far. Do we mean the role admin (the role mapped to engineers, which Carol is part of) or remote (the one Alice is assigned to) here? @l-heemann

[l-heemann]

Ah this is more confusing setup probably copied over from somewhere else.

Carol should not have admin or administrator for this documentation.

Alice technically needs the CREATE ALIAS privilege to execute CREATE ALIAS ....
However I think we can safely assume that Alice and Bob have the default admin role on DBMS A and DBMS B respectively.

[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
• Setting up and using a composite database

[l-heemann]

This should maybe be something along the lines of

CREATE ROLE remote_access
GRANT ACCESS ON DATABASE `db1-remote-alias` TO remote_access
GRANT ROLE remote_access TO CAROL

To disambiguate the remote role on DBMS B from this role on DBMS A.

[l-heemann]

Also this should happen after the

CREATE ALIAS `db1-remote-alias`

below. Otherwise the GRANT ACCESS fails with db1-remote-alias doesn't exist.

[l-heemann]

I don't have time to properly review the entire page today. I believe it would be good to merge the new credential forwarding docs without updating all the existing docs and then re-write the existing docs as a separate cleanup task.

[renetapopova]

I don't have time to properly review the entire page today. I believe it would be good to merge the new credential forwarding docs without updating all the existing docs and then re-write the existing docs as a separate cleanup task.

I wouldn't merge this PR. If we are confused, users will be even more confused. Also, wasn't this feature behind a feature flag? I'll try to accommodate your comments, @l-heemann, and then we'll see.