User Auth Providers (neo4j#1745)

This PR is for the examples and general description of the User Auth
Providers feature. Its currently applicable to native auth, LDAP and
OIDC.

---------

Co-authored-by: Therese Magnusson <[email protected]>
Co-authored-by: Reneta Popova <[email protected]>

Author: 3 people

modules/ROOT/content-nav.adoc

@@ -184,6 +184,7 @@
 *** xref:authentication-authorization/manage-execute-permissions.adoc[]
 ** xref:authentication-authorization/built-in-roles.adoc[]
 ** Integration with auth systems
+*** xref:authentication-authorization/auth-providers.adoc[]
 *** xref:authentication-authorization/ldap-integration.adoc[]
 *** xref:authentication-authorization/sso-integration.adoc[]
 

modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.svg

@@ -0,0 +1,69 @@
+:description: This section explains how to use Cypher to manage authentication and authorization at the user level using Cypher.
+:page-role: enterprise-edition new-5.24
+
+[[access-control-auth-providers]]
+= User auth providers
+
+Authentication and authorization can be controlled on a user level using Cypher by setting auth providers on users.
+
+To use auth providers, you need to set the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true`.
+This setting mandates that users with the relevant auth provider attached to them must exist in the database before they can authenticate and authorize with that auth provider.
+
+User auth providers allow you to link externally-defined users (e.g., in a third-party ID provider like OIDC or LDAP) to the Neo4j internal user model.
+The internal model can define roles (authorization), `SUSPENDED` status, `HOME DATABASE`, and metadata such as the unique displayed name of the user.
+For consistency, you can also define `native` (password-based) auth using the auth provider syntax, including native-only users (i.e., users who can only authenticate with a password).
+
+== Use cases
+
+User auth providers can be used for a variety of use cases, including:
+
+* Provisioning different auth providers (including native username/password auth) for different users.
+* Setting an arbitrary easy username for a user while using an external unique identifier (like `sub` for OIDC auths, which itself is not a user-friendly value).
+* Setting `HOME DATABASE` for externally authenticated users.
+* Setting `SUSPENDED` status for an externally authenticated user.
+* Using native authorization to manage roles for externally authenticated users.
+* Retaining full control of which users can authenticate from within the database.
+
+== How it works
+
+When a user authenticates, their identifying attributes are checked against the relevant property of the auth providers in the database.
+If there is a match, then the user is linked to the Neo4j user and authorized according to the DBMS security configuration settings that match the name of the matching auth provider.
+
+How the matching lookup is done depends on the type of provider.
+For example:
+
+* For an OIDC provider, the claim configured by xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] (default `sub`) is taken from the token and is used to look up an auth provider whose `ID` and `provider` properties match the `sub` and provider respectively of the OIDC provider.
+* For an LDAP provider, the `dn` is used to look up an auth provider with a `provider` property of `ldap` and an `ID` property that matches the supplied `dn`.
+* For the `native` (username/password) provider, the supplied username itself is used to look up the auth provider.
+
+== Enabling user auth providers mode
+
+To enable user auth providers mode, set the configuration setting xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] to `true`.
+This setting mandates that users with the relevant auth provider attached to them must exist in the database before they can authenticate and authorize with that auth provider.
+
+When the user authenticates, Neo4j searches for a user with a matching authentication provider.
+If a match is found, the user can log in and be authorized successfully.
+
+== Migrating to auth providers mode
+
+If you have existing users in the database and want to migrate to auth providers mode, you can use the `ALTER USER ... SET AUTH` command to attach an auth provider to each of them.
+Until you change `dbms.security.require_local_user` to `true`, this will not impact the users' ability to authenticate and authorize as they always have done.
+
+Once the process of adding auth providers to your users finishes, you can set `dbms.security.require_local_user` to `true` and restart the DBMS to complete the migration.
+After this time, only users with a corresponding auth provider in the database will be able to authenticate and authorize.
+
+[NOTE]
+====
+Existing users created using the original `CREATE USER ... SET PASSWORD` command implicitly have the native (username/password) auth provider, so you do not need to add it explicitly using `SET AUTH`.
+
+To verify which auth providers are attached to a user, use the xref:authentication-authorization/manage-users.adoc#access-control-list-users[`SHOW USERS WITH AUTH`] command.
+====
+
+== Examples
+
+For examples of how to use auth providers with different authentication providers, see the following sections:
+
+- xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers]
+- xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]
+- xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[Configure authentication/authorization at the user level using LDAP as an auth provider]
+

modules/ROOT/images/privileges_hierarchy_dbms.svg

@@ -68,9 +68,9 @@ All DBMS privileges are relevant system-wide.
 Like user management, they do not belong to one specific database or graph.
 For more details on the differences between graphs, databases, and the DBMS, refer to link:{neo4j-docs-base-uri}/cypher-manual/{page-version}/introduction/cypher_neo4j/[Cypher Manual -> Cypher and Neo4j].
 
-image::privileges_grant_and_deny_syntax_dbms_privileges.svg[title="Syntax of GRANT and DENY DBMS Privileges"]
+image::privileges_grant_and_deny_syntax_dbms_privileges.svg[width="800", title="Syntax of GRANT and DENY DBMS Privileges"]
 
-image::privileges_hierarchy_dbms.svg[title="DBMS privileges hierarchy"]
+image::privileges_hierarchy_dbms.svg[width="800", title="DBMS privileges hierarchy"]
 
 The xref:authentication-authorization/built-in-roles.adoc#access-control-built-in-roles-admin[`admin` role] has a number of built-in privileges.
 These include:
@@ -466,6 +466,12 @@ GRANT [IMMUTABLE] SET PASSWORD[S]
   TO role[, ...]
 | Enables the specified roles to modify users' passwords and whether those passwords must be changed upon first login.
 
+| [source, syntax, role=noheader]
+GRANT [IMMUTABLE] SET AUTH
+  ON DBMS
+  TO role[, ...]
+| label:new[Introduced in 5.24] Enables the specified roles to `SET` or `REMOVE` users' xref:authentication-authorization/auth-providers.adoc[auth providers].
+
 | [source, syntax, role=noheader]
 GRANT [IMMUTABLE] SET USER HOME DATABASE
   ON DBMS
@@ -571,7 +577,7 @@ SHOW ROLE userModifier PRIVILEGES AS COMMANDS
 a|Rows: 1
 |===
 
-A user that is granted the `ALTER USER` privilege is allowed to run the `ALTER USER` administration command with one or several of the `SET PASSWORD`, `SET PASSWORD CHANGE [NOT] REQUIRED` and `SET STATUS` parts:
+A user that is granted the `ALTER USER` privilege is allowed to run the `ALTER USER` administration command with one or several of the `SET PASSWORD`, `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET AUTH`, `REMOVE AUTH` and `SET STATUS` parts:
 
 [source, cypher, role=noplay]
 ----
@@ -609,6 +615,14 @@ A user that is granted the `SET PASSWORDS` privilege is allowed to run the `ALTE
 ALTER USER jake SET PASSWORD 'abcd5678' CHANGE NOT REQUIRED
 ----
 
+label:new[Introduced in 5.24] A user that is granted the `SET AUTH` privilege is allowed to run the `ALTER USER` administration command with one or both of the `SET AUTH` and `REMOVE AUTH` parts:
+
+[source, cypher, role=noplay]
+----
+ALTER USER jake REMOVE AUTH 'native SET AUTH 'oidc-okta' { SET id 'jakesUniqueOktaUserId' }
+----
+
+
 The ability to modify the account status of users can be granted via the `SET USER STATUS` privilege.
 See an example:
 
@@ -679,7 +693,7 @@ ALTER USER jake REMOVE HOME DATABASE
 
 [NOTE]
 ====
-Note that the combination of the `SET PASSWORDS`, `SET USER STATUS`, and the `SET USER HOME DATABASE` privilege actions is equivalent to the `ALTER USER` privilege action.
+Note that the combination of the `SET PASSWORDS`, `SET AUTH`, `SET USER STATUS`, and the `SET USER HOME DATABASE` privilege actions is equivalent to the `ALTER USER` privilege action.
 ====
 
 The ability to delete users can be granted via the `DROP USER` privilege.

modules/ROOT/pages/authentication-authorization/auth-providers.adoc

@@ -31,6 +31,10 @@ When triggered, Neo4j logs an error containing a timestamp and the message `fail
 For the relevant Cypher commands, see xref:authentication-authorization/manage-users.adoc#access-control-user-syntax[Manage users syntax], xref:authentication-authorization/manage-roles.adoc#access-control-role-syntax[Manage roles syntax], and xref:authentication-authorization/manage-privileges.adoc#access-control-privileges-syntax[Manage privileges syntax].
 Various scenarios that illustrate the use of the native auth provider are available in xref:tutorial/access-control.adoc[].
 
+*User auth providers*::
+User auth providers allow you to link externally-defined users (e.g., in a third-party ID provider like OIDC or LDAP) to the Neo4j internal user model.
+For more information, see xref:authentication-authorization/auth-providers.adoc[User auth providers].
+
 *LDAP auth provider*::
 Controls authentication and authorization through external security software such as Active Directory or OpenLDAP, which is accessed via the built-in LDAP connector.
 A description of the LDAP plugin using Active Directory is available in xref:authentication-authorization/ldap-integration.adoc[Integration with LDAP directory services].
@@ -93,6 +97,15 @@ This is in contrast to a suspended user.
 [[term-administrator]]administrator::
 This is a user who has been assigned the admin role.
 
+[[term-auth-provider]]auth provider::
+Properties attached to a user which define which authentication and authorization config to use for that user.
+
+[[term-authentication]]authentication::
+The process of verifying the identity of a user, typically using credentials like a username and password or a cryptographic token like a JWT.
+
+[[term-authorization]]authorization::
+The process of determining a user's access rights and privileges within Neo4j, based on their verified identity.
+
 [[term-current-user]]current user::
 This is the currently logged-in user invoking the commands.
 

modules/ROOT/pages/authentication-authorization/dbms-administration.adoc

@@ -3,30 +3,6 @@
 = LDAP integration
 :description: This page describes Neo4j support for integrating with LDAP systems.
 
-This page describes Neo4j support for integrating with LDAP systems.
-The following topics are covered:
-
-* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-introduction[Introduction]
-* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-parameters[LDAP configuration parameters]
-* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider[Set Neo4j to use LDAP]
-* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-map-ldap-roles[Map the LDAP groups to the Neo4j roles]
-* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider-ad[Configure Neo4j to use Active Directory]
-** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider-ad-uid[Configure Neo4j to support LDAP user ID authentication]
-** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider-ad-sysaccount[Configure Neo4j to support attribute authentication]
-** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider-ad-nosysaccount[Configure Neo4j to support `sAMAccountName` authentication by setting `user_dn_template`]
-** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-nested-groups[Configure Neo4j to perform nested group lookup]
-* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider-openldap[Configure Neo4j to use OpenLDAP]
-* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-search[Verify the LDAP configuration]
-* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-clear-auth-cache[The auth cache]
-* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-ad-encrypted[Available methods of encryption]
-** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-encrypted-starttls[Use LDAP with encryption via StartTLS]
-** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-encrypted-ldaps[Use LDAP with encrypted LDAPS]
-* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-self-signed-certificate[Use a self-signed certificate (SSL) in a test environment]
-
-
-[[auth-ldap-introduction]]
-== Introduction
-
 Neo4j supports LDAP, which allows for integration with Active Directory (AD), OpenLDAP, or other LDAP-compatible authentication services.
 This means that you use the LDAP service for managing federated users, while the native Neo4j user and role administration are completely turned off.
 
@@ -104,7 +80,7 @@ This way, the LDAP connector is used as a security provider for both authenticat
 If you want, you can still use the `native` provider for mixed-mode authentication and authorization.
 The values are comma-separated and queried in the declared order.
 +
-.Configure Neo4j to use LDAP and the native authentication and authorization provider.
+.Configure Neo4j to use LDAP and the native authentication and authorization provider
 ======
 [source,configuration,role="noheader"]
 ----
@@ -358,6 +334,136 @@ dbms.security.ldap.authorization.access_permitted_group=501
 . Map the groups in the LDAP system to the Neo4j built-in and custom roles.
 For more information, see xref:authentication-authorization/ldap-integration.adoc#auth-ldap-map-ldap-roles[Map the LDAP groups to the Neo4j roles].
 
+[role=label--new-5.24]
+[[auth-ldap-auth-providers]]
+== Configure authentication/authorization at the user level using auth providers
+xref:authentication-authorization/auth-providers.adoc[User auth providers] can be used to determine which users can authenticate and authorize using the configured providers, including LDAP.
+
+You must change the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true` to use auth providers.
+This means that a user with a matching auth provider *must* exist in order to be able to authenticate and authorize.
+This applies to all providers.
+
+Conversely, when xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] is set to `false`, users' auth providers have no bearing on the way that they are authenticated and authorized, instead authentication and authorization is controlled centrally (for all users) by the database configuration.
+
+The following examples show how to configure users with auth provider `ldap` using Cypher.
+
+.Create a user with an auth provider who can authenticate and authorize using `LDAP`
+======
+[source,cypher,role=noplay]
+----
+CREATE USER alice
+SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' }
+----
+
+The command creates the user `alice` who can authenticate and authorize using LDAP provided their LDAP `dn` is `cn=alice,ou=engineering,dc=example,dc=com`.
+======
+
+.Create a user with two auth providers allowing the user to authenticate and authorize with either LDAP or the `mysso` provider
+======
+
+[source,cypher,role=noplay]
+----
+CREATE USER alice
+SET HOME DATABASE anotherDb
+SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' }
+SET AUTH 'oidc-mysso' {SET ID 'alicesUniqueMySsoId'}
+----
+
+The command creates the user `alice` who can authenticate and authorize using `ldap` or `mysso`.
+See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers] for more information on setting up an OIDC provider.
+The example also illustrates that the user can have their home database set even when using only external auth providers.
+======
+
+.Alter a user to remove one of their auth providers
+======
+
+[source,cypher,role=noplay]
+----
+ALTER USER alice
+REMOVE AUTH 'ldap'
+----
+
+The command prevents the user `alice` from being able to authenticate and authorize using `ldap`.
+======
+
+.Alter a user to allow them to authenticate and authorize using username and password
+======
+
+[source,cypher,role=noplay]
+----
+ALTER USER alice
+SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED}
+----
+
+The command allows the user `alice` to authenticate and authorize using the specified username and password (in addition to what they are already configured to use).
+======
+
+
+.Configure the database to allow authentication via `ldap` and authorization via the `native` provider
+======
+
+. Set the following database config:
++
+[source, properties]
+----
+dbms.security.authentication_providers=ldap
+dbms.security.authorization_providers=native
+----
+
+. Create a user with an `ldap` auth provider:
++
+[source,cypher,role=noplay]
+----
+CREATE USER alice
+SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' }
+----
+
+. Natively grant the `READER` role to the user:
++
+[source,cypher,role=noplay]
+----
+GRANT ROLE READER TO alice
+----
++
+The command allows the user `alice` to authenticate using `ldap` and receive the `READER` role from the `native` provider.
+
+. You can also give the user the union of roles from `ldap` *and*  `native` roles by setting `ldap` as an authorization provider too:
++
+[source, properties]
+----
+dbms.security.authentication_providers=ldap
+dbms.security.authorization_providers=native,ldap
+----
+======
+
+.Suspend a user
+======
+[source,cypher,role=noplay]
+----
+ALTER USER alice
+SET STATUS SUSPENDED
+
+----
+The command completely prevents the user from being able to authenticate/authorize by any means.
+======
+
+.Disambiguate users with the same name in different LDAP trees
+======
+
+Suppose there are two users both with the name `alice`, one is part of the `engineering` tree (`cn=alice,ou=engineering,dc=example,dc=com`) and the other is part of the `sales` tree (`cn=alice,ou=sales,dc=example,dc=com`).
+
+To disambiguate these users, you can create two users in the database, each with a different `ID` that corresponds to the `dn` of the user in the LDAP tree.
+
+[source,cypher,role=noplay]
+----
+CREATE USER aliceEngineering
+SET AUTH 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' }
+
+CREATE USER aliceSales
+SET AUTH 'ldap' { SET ID 'cn=alice,ou=sales,dc=example,dc=com' }
+----
+======
+
 [[auth-ldap-search]]
 == Verify the LDAP configuration
 

modules/ROOT/pages/authentication-authorization/index.adoc

@@ -597,7 +597,7 @@ Users can be given access rights by assigning them roles using `GRANT ROLE`:
 GRANT ROLE myrole TO bob
 ----
 
-The roles assigned to each user can be seen on the list provided by `SHOW USERS`:
+The roles assigned to each user can be seen on the list provided by xref:authentication-authorization/manage-users.adoc#access-control-list-users[`SHOW USERS`]:
 
 [source, cypher, role=noplay]
 ----