From 0851f2292978e59e2c7d1bde501ad80d5c38ab4c Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Wed, 24 Jul 2024 16:46:08 +0100 Subject: [PATCH 01/62] Auth Objects docs: adding examples for OIDC, native and LDAP. Adding high-level description --- modules/ROOT/content-nav.adoc | 1 + .../auth-objects.adoc | 39 +++++ .../authentication-authorization/index.adoc | 6 + .../ldap-integration.adoc | 100 ++++++++++++ .../manage-users.adoc | 120 +++++++++++++-- .../sso-integration.adoc | 103 +++++++++++++ .../tutorial/tutorial-sso-configuration.adoc | 142 ++++++++++++++++-- 7 files changed, 479 insertions(+), 32 deletions(-) create mode 100644 modules/ROOT/pages/authentication-authorization/auth-objects.adoc diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 4b8b5493d..38fa5415a 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -185,6 +185,7 @@ *** xref:authentication-authorization/manage-execute-permissions.adoc[] ** xref:authentication-authorization/built-in-roles.adoc[] ** Integration with auth systems +*** xref:authentication-authorization/auth-objects.adoc[] *** xref:authentication-authorization/ldap-integration.adoc[] *** xref:authentication-authorization/sso-integration.adoc[] diff --git a/modules/ROOT/pages/authentication-authorization/auth-objects.adoc b/modules/ROOT/pages/authentication-authorization/auth-objects.adoc new file mode 100644 index 000000000..23a7474f3 --- /dev/null +++ b/modules/ROOT/pages/authentication-authorization/auth-objects.adoc @@ -0,0 +1,39 @@ +:description: This section explains how to use Cypher to manage authentication and authorization at the user level using Cypher. + +[role=label--new-5.24] +[[access-control-auth-objects]] += Auth objects label:enterprise-edition[] + +User Auth Objects provide a way to configure authentication and authorization at the user-level using Cypher. + +Using the database in Auth Object mode mandates that only users with a corresponding Auth Object in the database can authenticate and authorize. This mode is enabled by setting `internal.dbms.security.require_local_user` to `true`. + +This gives us a way to link externally-defined users to the Neo4j internal user model. The internal model can define things such as roles (authorization), `SUSPENDED` status, `HOME DATABASE`, and metadata such as the unique displayed name of the user. + +== Use Cases +. Provisioning different auth providers (including native username/password auth) for different users. +. Setting an arbitrary reader-friendly username for a user whilst using an external unique identifier (like `sub` for OIDC auth, which is itself not a reader-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 Objects 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 which match the provider of the matching Auth Object. + +The way that 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 used to look up the `ID` property of the Auth Object. +- For the `native` (username/password) provider, the username is used to look up the Auth Object. +- For an LDAP provider, the `dn` is used to look up the Auth Object. + +== Enabling Auth Objects mode +When the configuration setting `internal.dbms.security.require_local_user` is set to `true`, the lookups described above will be performed when the user authenticates, and a matching user Auth Object *must* exist in order for a user to be able to successfully authenticate and authorize. + +== Examples +For examples of how to use Auth Objects with different authentication providers, see the following sections: + +- xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[SSO Auth Object Examples] +- xref:authentication-authorization/manage-users.adoc#access-control-create-users[`native` Auth Object Examples] +- xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-objects[LDAP Auth Object Examples] + diff --git a/modules/ROOT/pages/authentication-authorization/index.adoc b/modules/ROOT/pages/authentication-authorization/index.adoc index a837f1b81..615731b88 100644 --- a/modules/ROOT/pages/authentication-authorization/index.adoc +++ b/modules/ROOT/pages/authentication-authorization/index.adoc @@ -93,6 +93,12 @@ This is in contrast to a suspended user. [[term-administrator]]administrator:: This is a user who has been assigned the admin role. +[[term-auth-object]]Auth Object:: +A map object attached to a database user which defines which authentication and authorization settings to use for that user. + +[[term-authentication]]authentication:: + + [[term-current-user]]current user:: This is the currently logged-in user invoking the commands. diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index a1d6e608f..37b47f0ad 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -16,6 +16,7 @@ The following topics are covered: ** 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-auth-objects[Use Auth Objects to configure authentication / authorization at the user level] * 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] @@ -358,6 +359,105 @@ 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-objects]] +== Use Auth Objects to configure authentication / authorization at the user level +xref:authentication-authorization/auth-objects.adoc[Auth Objects] can be used to determine which users can authenticate and authorize using the configured providers, including LDAP. + +[NOTE] +==== +You need to set `internal.dbms.security.require_local_user` to `true` to use Auth Objects. This means that a user with a matching Auth Object *must* exist in order to be able to authenticate and authorize. +==== + +The following examples show how you can use Cypher to do this. + +.Create a user with an Auth Object who can authenticate and authorize using `LDAP`. +====== +---- +CREATE USER alice +SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } +---- +This will create a user who can authenticate and authorize using LDAP provided their LDAP `dn` is `cn=alice,ou=engineering,dc=example,dc=com`. + +When `internal.dbms.security.require_local_user` is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Object which links to the provider that the user is trying to authenticate with. If there is no matching Auth Object, the user will not be able to authenticate or authorize. This applies to all providers. +====== + + +.Create a user with two Auth Objects allowing the user to authenticate and authorize with either LDAP or the `oidc-mysso` provider. +====== +---- +CREATE USER alice +SET HOME DATABASE anotherDb +SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } +SET AUTH 'oidc-mysso1' {SET ID 'alicesUniqueMySso1Id'} +---- +This will create a user who can authenticate and authorize using `ldap` or `oidc-mysso`. See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[SSO integration] for more information on setting up an OIDC provider. +This example also illustrates that the user can have their `HOME` database set even when using an external auth provider. +====== + +.Alter a user to remove one of their Auth Objects. +====== +---- +ALTER USER alice +REMOVE AUTH 'ldap' + +---- +This will prevent the user from being able to authenticate and authorize using `ldap`. +====== + +.Alter a user to allow them to authenticate and authorize using username and password +====== +---- +ALTER USER alice +SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED} + +---- +This will allow the user 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,configuration,role="noheader"] +---- +dbms.security.authentication_providers=ldap +dbms.security.authorization_providers=native +---- + +Then create a user with an `ldap` Auth Object: +---- +CREATE USER alice +SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } +---- + +Then natively grant the `ANALYST` role to the user: +---- +GRANT ROLE ANALYST TO alice +---- + +This will allow the user to authenticate using `ldap` and receive the `ANALYST` role from the `native` provider. + +It would also be possible to give the user the union of roles from `ldap` *and* `native` roles by setting `ldap` as an authorization provider too: + +---- +dbms.security.authentication_providers=ldap +dbms.security.authorization_providers=native,ldap +---- +====== + +.Suspend a user +====== +---- +ALTER USER alice +SET STATUS SUSPENDED + +---- +This will completely prevent the user from being able to authenticate/authorize by any means. +====== + + [[auth-ldap-search]] == Verify the LDAP configuration diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 028734333..015419167 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -147,10 +147,11 @@ a| [source, syntax, role="noheader"] ---- CREATE USER name [IF NOT EXISTS] - SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' + [SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] + [SET AUTH [PROVIDER] 'provider' "{"SET "}"] ---- | Description @@ -180,10 +181,11 @@ a| [source, syntax, role="noheader"] ---- CREATE OR REPLACE USER name - SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' + [SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] + [SET AUTH [PROVIDER] 'provider' "{"SET "}"] ---- | Description @@ -254,7 +256,10 @@ ALTER USER name [IF EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED} ] [SET HOME DATABASE name] + [SET AUTH [PROVIDER] 'provider' "{"SET "}"] [REMOVE HOME DATABASE] + [REMOVE { AUTH [PROVIDER[S]] provider[, ...] } \| { ALL AUTH [PROVIDER[S]] }] + ---- | Description @@ -548,10 +553,11 @@ Users can be created using `CREATE USER`. [source, syntax, role="noheader"] ---- CREATE USER name [IF NOT EXISTS] - SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password' + [SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'] [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE | SUSPENDED}] + [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] + [SET AUTH [PROVIDER] 'provider' "{"SET "}"] ---- Users can be created or replaced using `CREATE OR REPLACE USER`. @@ -559,10 +565,11 @@ Users can be created or replaced using `CREATE OR REPLACE USER`. [source, syntax, role="noheader"] ---- CREATE OR REPLACE USER name - SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password' + [SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'] [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE | SUSPENDED}] + [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] + [SET AUTH [PROVIDER] 'provider' "{"SET "}"] ---- * For `SET PASSWORD`: @@ -585,6 +592,9 @@ The `SET PASSWORD` part is only optional if it directly follows the `SET PASSWOR A home database will be resolved if it is either pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for the user. * The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, and `SET HOME DATABASE` clauses can be applied in any order. +[role=label--new-5.24] +* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-objects.adoc[Auth Objects], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. +Examples can be found below for `native`, xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[here] for OIDC and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-objects[here] for LDAP. [NOTE] ==== @@ -608,10 +618,22 @@ SET STATUS SUSPENDED SET HOME DATABASE anotherDb ---- +The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: + +[source,cypher,role=noplay] +---- +CREATE USER jake +SET STATUS SUSPENDED +SET HOME DATABASE anotherDb +SET AUTH 'native' {SET PASSWORD 'abcd1234' SET PASSWORD CHANGE REQUIRED} +---- + + + ====== -.Create user +.Create user with an encrypted password ====== Or you can create the user `Jake` in an active state, with an encrypted password (taken from the _data/scripts/databasename/restore_metadata.cypher_ of a database backup), and the requirement to not change the password by running: @@ -621,12 +643,21 @@ CREATE USER Jake SET ENCRYPTED PASSWORD '1,6d57a5e0b3317055454e455f96c98c750c77fb371f3f0634a1b8ff2a55c5b825,190ae47c661e0668a0c8be8a21ff78a4a34cdf918cae3c407e907b73932bd16c' CHANGE NOT REQUIRED SET STATUS ACTIVE ---- +[role=label--new-5.24] +The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: + +[source,cypher,role=noplay] +---- +CREATE USER jake +SET STATUS ACTIVE +SET AUTH 'native' {SET ENCRYPTED PASSWORD '1,6d57a5e0b3317055454e455f96c98c750c77fb371f3f0634a1b8ff2a55c5b825,190ae47c661e0668a0c8be8a21ff78a4a34cdf918cae3c407e907b73932bd16c' SET PASSWORD CHANGE NOT REQUIRED} +---- ====== [NOTE, role=label--enterprise-edition] ==== -The `SET STATUS {ACTIVE | SUSPENDED}` and `SET HOME DATABASE` parts of the commands are only available in Neo4j Enterprise Edition. +The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE` and `SET AUTH` parts of the commands are only available in Neo4j Enterprise Edition. ==== The `CREATE USER` command is optionally idempotent, with the default behavior to throw an exception if the user already exists. @@ -641,6 +672,16 @@ CREATE USER jake IF NOT EXISTS SET PLAINTEXT PASSWORD 'abcd1234' ---- +[role=label--new-5.24] +The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: + +[source,cypher,role=noplay] +---- +CREATE USER jake IF NOT EXISTS +SET AUTH 'native' {SET PLAINTEXT PASSWORD 'abcd1234'} +---- + + ====== The `CREATE OR REPLACE USER` command will result in any existing user being deleted and a new one created. @@ -656,6 +697,17 @@ SET PLAINTEXT PASSWORD 'abcd1234' This is equivalent to running `DROP USER jake IF EXISTS` followed by `CREATE USER jake SET PASSWORD 'abcd1234'`. +[role=label--new-5.24] +The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: + +[source,cypher,role=noplay] +---- +CREATE OR REPLACE USER jake +SET AUTH 'native' {SET PLAINTEXT PASSWORD 'abcd1234'} +---- + + + ====== [NOTE] @@ -718,7 +770,9 @@ ALTER USER name [IF EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE | SUSPENDED}] [SET HOME DATABASE name] - [REMOVE HOME DATABASE name] + [SET AUTH [PROVIDER] 'provider' "{"SET "}"] + [REMOVE HOME DATABASE] + [REMOVE { AUTH [PROVIDER[S]] provider[, ...] } \| { ALL AUTH [PROVIDER[S]] }] ---- * At least one `SET` or `REMOVE` clause is required for the command. @@ -743,33 +797,67 @@ The `SET PASSWORD` part is only optional if it directly follows the `SET PASSWOR * `SET HOME DATABASE` can be used to configure a home database for a user. A home database will be resolved if it is either pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for the user. +[role=label--new-5.24] +* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-objects.adoc[Auth Objects], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. TODO: Insert links to the LDAP and OIDC examples. * `REMOVE HOME DATABASE` is used to unset the home database for a user. This results in the DBMS default database being used as the home database for the user. +[role=label--new-5.24] +* `REMOVE AUTH` is used to remove one or many xref:authentication-authorization/auth-objects.adoc[Auth Object(s)] from a user. It cannot be used such that a user would have no Auth Objects. +* `REMOVE ALL AUTH` is used to remove all existing xref:authentication-authorization/auth-objects.adoc[Auth Objects] from a user and replace them with new ones. It must be used in conjunction with at least one `SET AUTH` clause. -For example, you can modify the user `bob` with a new password and active status, and remove the requirement to change his password: -[source, cypher, role=noplay] +.Modify the user `bob` with a new password and active status, and remove the requirement to change his password: +====== +[source,cypher,role=noplay] ---- ALTER USER bob SET PASSWORD 'abcd5678' CHANGE NOT REQUIRED SET STATUS ACTIVE ---- -Or you may decide to assign the user `bob` a different home database: +[role=label--new-5.24] +The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: -[source, cypher, role=noplay] +---- +ALTER USER bob +SET AUTH 'native' {SET PASSWORD 'abcd5678' SET PASSWORD CHANGE NOT REQUIRED} +SET STATUS ACTIVE +---- +====== + +.Modify the user `bob` to expire his current password so that he must change it the next time he logs in: +====== +[source,cypher,role=noplay] +---- +ALTER USER bob +SET PASSWORD CHANGE REQUIRED +---- + +[role=label--new-5.24] +The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: + +---- +ALTER USER bob +SET AUTH 'native' {SET PASSWORD CHANGE REQUIRED} +---- +====== + +.Assign the user `bob` a different home database: +====== +[source,cypher,role=noplay] ---- ALTER USER bob SET HOME DATABASE anotherDbOrAlias ---- -Or remove the home database from the user `bob`: +Or remove the `HOME` database from the user `bob`: -[source, cypher, role=noplay] +[source,cypher,role=noplay] ---- ALTER USER bob REMOVE HOME DATABASE ---- +====== [NOTE] ==== @@ -779,7 +867,7 @@ For example, leaving out the `CHANGE [NOT] REQUIRED` part of the query will leav [NOTE, role=label--enterprise-edition] ==== -The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE`, and `REMOVE HOME DATABASE` parts of the command are only available in Neo4j Enterprise Edition. +The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE`, `REMOVE HOME DATABASE`, `SET AUTH` and `REMOVE AUTH` parts of the command are only available in Neo4j Enterprise Edition. ==== The changes to the user will appear on the list provided by `SHOW USERS`: diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index eafd92cb1..0dc18d537 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -253,6 +253,109 @@ dbms.security.oidc.mysso.claims.groups=roles + See xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the Identity Provider Groups to the Neo4j Roles]. + +[role=label--new-5.24] +[[auth-sso-auth-objects]] +=== Use Auth Objects to configure SSO at the user level +xref:authentication-authorization/auth-objects.adoc[Auth Objects] can be used to determine which users can authenticate and authorize using the configured providers. + +[NOTE] +==== +You need to set `internal.dbms.security.require_local_user` to `true` to use Auth Objects. This means that a user with a matching Auth Object *must* exist in order to be able to authenticate and authorize. +==== + +The following examples show how you can use Cypher to do this. + + +.Create a user with an Auth Object who can authenticate and authorize using `oidc-mysso`. +====== +---- +CREATE USER jake +SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySso1Id'} // this must match the claim that you configured via dbms.security.oidc.mysso.claims.username +---- +This will create a user who can authenticate and authorize using `mysso` if they present a valid token with a `sub` claim of `jakesUniqueMySso1Id`. The claim used for authentication is determined by the xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] config setting (default the default is the `sub` claim). + +When `internal.dbms.security.require_local_user` is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Object which links to the provider that the user is trying to authenticate with. If there is no matching Auth Object, the user will not be able to authenticate or authorize. This applies to all providers. +====== + + +.Create a user with two Auth Objects allowing the user to authenticate and authorize with either of two providers. +====== +---- +CREATE USER jake +SET HOME DATABASE anotherDb +SET AUTH 'oidc-mysso1' {SET ID 'jakesUniqueMySso1Id'} // this must match the claim that you configured via dbms.security.oidc.mysso1.claims.username +SET AUTH 'oidc-mysso2' {SET ID 'jakesUniqueMySso2Id'} // this must match the claim that you configured via dbms.security.oidc.mysso2.claims.username +---- +This will create a user who can authenticate and authorize using `oidc-mysso1` or `oidc-mysso2`. +This example also illustrates that the user can have their `HOME` database set even when using an external auth provider. +====== + + +.Alter a user to remove one of their Auth Objects. +====== +---- +ALTER USER jake +REMOVE AUTH 'oidc-mysso2' + +---- +This will prevent the user from being able to authenticate and authorize with the `oidc-mysso2` provider. +====== + +.Alter a user to allow them to authenticate and authorize using username and password +====== +---- +ALTER USER jake +SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED} + +---- +This will allow the user to authenticate and authorize using the specified username and password +====== + + +.Configure the database to allow authentication via `oidc-mysso` and authorization via the `native` provider. +====== + +Set the following database config: +[source,configuration,role="noheader"] +---- +dbms.security.authentication_providers=oidc-mysso +dbms.security.authorization_providers=native +---- + +Then create a user with a `oidc-mysso` Auth Object: +---- +CREATE USER jake +SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySsoId'} // this must match the claim that you configured via dbms.security.oidc.mysso.claims.username +---- + +Then natively grant the `ANALYST` role to the user: +---- +GRANT ROLE ANALYST TO alice +---- + +This will allow the user to authenticate using `oidc-mysso` and receive the `ANALYST` role from the `native` provider. + +It would also be possible to give the user the union of roles from `oidc-mysso` *and* `native` by setting `oidc-mysso` as an authorization provider too: + +---- +dbms.security.authentication_providers=oidc-mysso +dbms.security.authorization_providers=native,oidc-mysso +---- +====== + + +.Suspend a user +====== +---- +ALTER USER jake +SET STATUS SUSPENDED + +---- +This will completely prevent the user from being able to authenticate/authorize by any means. +====== + + [[auth-sso-configure-provider-userinfo]] === OpenID Connect Fetching Claims from Provider diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index 97be538ce..0232467ba 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -23,6 +23,13 @@ SSO works in the following way: . The client (e.g., Bloom, Neo4j Browser, etc.) asks the user for credentials and contacts the identity provider. . The identity provider responds with a JSON Web Token (JWT), a JSON file containing fields (claims) relative to the user (email, audience, groups, etc.). . The client provides the server with the JWT, and the server verifies its signature with the JWKs. +[role=label--new-5.24] +. By setting `internal.dbms.security.require_local_user` is set to `true`, you can control which users can authenticate and authorize by creating xref:authentication-authorization/auth-objects.adoc[Auth Objects] in the database using Cypher. In this mode, a user with a matching Auth Object must exist in the database for the user to be able to authenticate and authorize using an SSO (or any external) provider. This allows you to do the following in the database, using Cypher: +.. `SUSPEND` SSO users. +.. Set the `HOME DATABASE` for an SSO user. +.. Set a reader-friendly name for an SSO user (rather than relying on the external identifier). + +See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[SSO integration] for examples. + [IMPORTANT] ==== @@ -124,6 +131,19 @@ dbms.security.oidc.okta.config=token_type_principal=id_token;token_type_authenti . You should now find the audience under Okta's sign-on tab: + image::sso-configuration-tutorials/okta-sign-on-tab.svg[title="Okta's sign-on tab"] ++ +[role=label--new-5.24] +. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-objects.adoc[Auth Objects] to achieve this. Set `internal.dbms.security.require_local_user` to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate using native or Okta, and authorize using Okta (as configured in step 3), you can use the following Cypher query: +[source, cypher, role=noplay] +---- +CREATE USER jake +SET HOME DATABASE 'jakesHomeDb' +SET AUTH 'oidc-okta' {SET ID 'jakesUniqueOktaUserId'} // this must match the claim that you configured via dbms.security.oidc.okta.claims.username +SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED} +---- + +See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[SSO integration] for further examples. + == Microsoft Entra ID (formerly Azure Active Directory) @@ -302,6 +322,18 @@ dbms.security.oidc.azure.authorization.group_to_role_mapping= "managers" = admin dbms.security.oidc.azure.claims.groups=roles ---- +[role=label--new-5.24] +. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-objects.adoc[Auth Objects] to achieve this. Set `internal.dbms.security.require_local_user` to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate and authorize using Entra, you can use the following Cypher query: +[source, cypher, role=noplay] +---- +CREATE USER jake +SET HOME DATABASE 'jakesHomeDb' +SET AUTH 'oidc-okta' {SET ID 'jakesUniqueEntraUserId'} // this must match the claim that you configured via dbms.security.oidc.azure.claims.username +---- + +See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[SSO integration] for further examples. + + == Google This example shows how to use Google OpenID Connect for authentication using ID tokens in conjunction with native authorization. @@ -319,14 +351,6 @@ SSO authorization does not work with Google, as the JWT returned by Google does Therefore, it is recommended to use native (or another flavor) authorization by creating a native version of the user in Neo4j. ==== -. The role assigned to the email used to log in with SSO, in this case, `alice@neo4j-test.com`, must have `GRANT ROLE` permissions in the database (`native` authentication temporarily enabled): -+ -[source] ----- -CREATE USER `alice@neo4j-test.com` SET PASSWORD 'secretpassword'; -GRANT ROLE admin to `alice@neo4j-test.com`; ----- - . Configure Neo4j to use Google authentication by configuring the following settings in the _neo4j.conf_ file: + [source, properties] @@ -343,14 +367,100 @@ dbms.security.oidc.google.token_params=client_secret=GOCSPX-v4cGkygPJvm3Sjjbc0hv dbms.security.oidc.google.config=token_type_principal=id_token;token_type_authentication=id_token ---- -. Log in with your Google SSO credentials using the email address and get the `admin` role when doing so: -+ -image::sso-configuration-tutorials/oidc-azure-successful-login.png[title="Entra OIDC successful login"] -+ -[NOTE] -==== -The native authentication is disabled to prevent someone from logging in to _alice@neo4j-test.com_ with the set password. -==== +There are then two ways to create the user in the database (which is required to give the users roles from native authorization): + +. Using Auth Objects +xref:authentication-authorization/auth-objects.adoc[Auth Objects] allow us to specify auth providers at the user-level which is useful in this scenario. This approach allows us to have an `admin` user who can authenticate natively, and can then create less privileged users who may only authenticate using `oidc-google` and will receive the roles granted to them using `native` authorization. + +.. Change the configuration to allow `native` authentication (for use only by the `admin` user): + +[source, properties] +---- +dbms.security.authentication_providers=oidc-google, native +---- + +.. Set the `internal.dbms.security.require_local_user` to `true` in the _neo4j.conf_ file. This will switch to Auth Objects mode whereby users can only authenticate and authorize if they have a corresponding Auth Object in the database. + +[source, properties] +---- +internal.dbms.security.require_local_user=true +---- + + +.. Create a user who can authenticate and authorize using `oidc-google` (they will not be able to authenticate using `native` (username and password) authentication, only `oidc-google`): + +[source, cypher, role=noplay] +---- +CREATE USER jake +SET HOME DATABASE 'jakesHomeDb' +SET AUTH 'oidc-google' {SET ID 'jakesUniqueGoogleUserId'} // this must match the claim that you configured via dbms.security.oidc.google.claims.username +---- + +.. Grant the user roles using native authorization. + +[source, cypher, role=noplay] +---- +GRANT ROLE reader TO jake +---- + +The user will implicitly receive `native` authorization because `native` is in the list of authorization providers and you have explicitly granted the user a `ROLE`. + +You can now disable native authentication for the database completely: + +[source, properties] +---- +dbms.security.authentication_providers=oidc-google +---- + + + +. Alternatively, if you don't use Auth Objects, you can temporarily enable `native` authentication to create an SSO-authenticated admin user `alice` who can then create other users who can only authenticate using SSO. + +To do this we temporarily enable native authentication: + +[source, properties] +---- +dbms.security.authentication_providers=oidc-google, native +---- + +Then, create an SSO-authenticated `admin` user (in this example an equivalent of `alice@neo4j-test.com` must be set up in the Google SSO provider and their credentials must be known): + +[source] +---- +CREATE USER `alice@neo4j-test.com` SET PASSWORD 'secretpassword'; +GRANT ROLE admin to `alice@neo4j-test.com`; +---- + +Disable native authentication for the database to prevent users logging in with username and password: + +[source, properties] +---- +dbms.security.authentication_providers=oidc-google +---- + +. Log via Google SSO as `alice@neo4j-test.com`, the `admin` user + +. Use this admin user to create other users who can only authenticate using `oidc-google` and will receive the roles granted to them using `native` authorization. + + +[source, cypher, role=noplay] +---- +CREATE USER jakesUniqueGoogleUserId // this must match the claim that you configured via dbms.security.oidc.google.claims.username +SET HOME DATABASE 'jakesHomeDb' +SET PASSWORD 'secretpassword' SET PASSWORD CHANGE NOT +REQUIRED +---- + +.. Grant the user roles using native authorization + +[source, cypher, role=noplay] +---- +GRANT ROLE reader TO jakesUniqueGoogleUserId +---- + + + + == FAQ From 3ff49f19f73651e11cc24f9a56719a8f0c553e4a Mon Sep 17 00:00:00 2001 From: Phil Wright <95368282+phil198@users.noreply.github.com> Date: Thu, 22 Aug 2024 15:43:39 +0100 Subject: [PATCH 02/62] Update modules/ROOT/pages/authentication-authorization/auth-objects.adoc Co-authored-by: Therese Magnusson --- .../ROOT/pages/authentication-authorization/auth-objects.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-objects.adoc b/modules/ROOT/pages/authentication-authorization/auth-objects.adoc index 23a7474f3..c28a06986 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-objects.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-objects.adoc @@ -23,7 +23,7 @@ When a user authenticates, their identifying attributes are checked against the The way that 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 used to look up the `ID` property of the Auth Object. +- 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 used to look up the `ID` property of the Auth Object. - For the `native` (username/password) provider, the username is used to look up the Auth Object. - For an LDAP provider, the `dn` is used to look up the Auth Object. From 70c95394db7aa28b964b25ec46e6eff425dec5ab Mon Sep 17 00:00:00 2001 From: Phil Wright <95368282+phil198@users.noreply.github.com> Date: Thu, 22 Aug 2024 17:07:23 +0100 Subject: [PATCH 03/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc Co-authored-by: Therese Magnusson --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 015419167..49f6edf09 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -258,7 +258,7 @@ ALTER USER name [IF EXISTS] [SET HOME DATABASE name] [SET AUTH [PROVIDER] 'provider' "{"SET "}"] [REMOVE HOME DATABASE] - [REMOVE { AUTH [PROVIDER[S]] provider[, ...] } \| { ALL AUTH [PROVIDER[S]] }] + [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }] ---- From 1d9cd7e5482a45c14319ac2aef0a9466a62de43d Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Wed, 24 Jul 2024 16:46:08 +0100 Subject: [PATCH 04/62] Auth Objects docs: adding examples for OIDC, native and LDAP. Adding high-level description --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 49f6edf09..ee7284919 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -259,7 +259,6 @@ ALTER USER name [IF EXISTS] [SET AUTH [PROVIDER] 'provider' "{"SET "}"] [REMOVE HOME DATABASE] [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }] - ---- | Description From 08644702cb586ee03226d45db100b4123dab69a9 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Thu, 22 Aug 2024 17:08:54 +0100 Subject: [PATCH 05/62] pr review comments --- .../auth-objects.adoc | 10 ++++----- .../authentication-authorization/index.adoc | 4 ++++ .../ldap-integration.adoc | 4 ++-- .../manage-users.adoc | 22 +++++++++++++------ .../sso-integration.adoc | 4 ++-- .../tutorial/tutorial-sso-configuration.adoc | 10 ++++----- 6 files changed, 33 insertions(+), 21 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-objects.adoc b/modules/ROOT/pages/authentication-authorization/auth-objects.adoc index c28a06986..855d5f6b8 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-objects.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-objects.adoc @@ -6,7 +6,7 @@ User Auth Objects provide a way to configure authentication and authorization at the user-level using Cypher. -Using the database in Auth Object mode mandates that only users with a corresponding Auth Object in the database can authenticate and authorize. This mode is enabled by setting `internal.dbms.security.require_local_user` to `true`. +Using the database in Auth Object mode mandates that only users with a corresponding Auth Object in the database can authenticate and authorize. This mode is enabled by changing the `dbms.security.require_local_user` configuration setting to `true`. This gives us a way to link externally-defined users to the Neo4j internal user model. The internal model can define things such as roles (authorization), `SUSPENDED` status, `HOME DATABASE`, and metadata such as the unique displayed name of the user. @@ -23,12 +23,12 @@ When a user authenticates, their identifying attributes are checked against the The way that 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 used to look up the `ID` property of the Auth Object. -- For the `native` (username/password) provider, the username is used to look up the Auth Object. -- For an LDAP provider, the `dn` is used to look up the Auth Object. +- 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 Object 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 Auth Object with a `provider` property of `ldap` and an `ID` property which matches the supplied `dn`. +- For the `native` (username/password) provider, the supplied username itself is used to look up the Auth Object. == Enabling Auth Objects mode -When the configuration setting `internal.dbms.security.require_local_user` is set to `true`, the lookups described above will be performed when the user authenticates, and a matching user Auth Object *must* exist in order for a user to be able to successfully authenticate and authorize. +When the configuration setting `dbms.security.require_local_user` is set to `true`, the lookups described above will be performed when the user authenticates, and a matching user Auth Object *must* exist in order for a user to be able to successfully authenticate and authorize. == Examples For examples of how to use Auth Objects with different authentication providers, see the following sections: diff --git a/modules/ROOT/pages/authentication-authorization/index.adoc b/modules/ROOT/pages/authentication-authorization/index.adoc index 615731b88..3b964fc0c 100644 --- a/modules/ROOT/pages/authentication-authorization/index.adoc +++ b/modules/ROOT/pages/authentication-authorization/index.adoc @@ -97,7 +97,11 @@ This is a user who has been assigned the admin role. A map object attached to a database user which defines which authentication and authorization settings 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. diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index 37b47f0ad..54ce5d1d4 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -366,7 +366,7 @@ xref:authentication-authorization/auth-objects.adoc[Auth Objects] can be used to [NOTE] ==== -You need to set `internal.dbms.security.require_local_user` to `true` to use Auth Objects. This means that a user with a matching Auth Object *must* exist in order to be able to authenticate and authorize. +You need to change the `dbms.security.require_local_user` configuration setting to `true` to use Auth Objects. This means that a user with a matching Auth Object *must* exist in order to be able to authenticate and authorize. ==== The following examples show how you can use Cypher to do this. @@ -379,7 +379,7 @@ SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } ---- This will create a user who can authenticate and authorize using LDAP provided their LDAP `dn` is `cn=alice,ou=engineering,dc=example,dc=com`. -When `internal.dbms.security.require_local_user` is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Object which links to the provider that the user is trying to authenticate with. If there is no matching Auth Object, the user will not be able to authenticate or authorize. This applies to all providers. +When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Object which links to the provider that the user is trying to authenticate with. If there is no matching Auth Object, the user will not be able to authenticate or authorize. This applies to all providers. ====== diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index ee7284919..658f0ef19 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -151,13 +151,17 @@ CREATE USER name [IF NOT EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"SET "}"] + {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... ---- | Description a| Creates a new user. +[NOTE] +==== +It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Object. +==== For more information, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. | Required privilege @@ -185,13 +189,16 @@ CREATE OR REPLACE USER name [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"SET "}"] + {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... ---- | Description a| Creates a new user, or if a user with the same name exists, replace it. - +[NOTE] +==== +It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Object. +==== For more information, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. | Required privilege @@ -256,7 +263,7 @@ ALTER USER name [IF EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED} ] [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"SET "}"] + {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... [REMOVE HOME DATABASE] [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }] ---- @@ -556,7 +563,7 @@ CREATE USER name [IF NOT EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"SET "}"] + {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... ---- Users can be created or replaced using `CREATE OR REPLACE USER`. @@ -568,7 +575,7 @@ CREATE OR REPLACE USER name [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"SET "}"] + {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... ---- * For `SET PASSWORD`: @@ -594,6 +601,7 @@ If no home database is set, the DBMS default database is used as the home databa [role=label--new-5.24] * One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-objects.adoc[Auth Objects], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. Examples can be found below for `native`, xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[here] for OIDC and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-objects[here] for LDAP. +* It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Object. [NOTE] ==== @@ -769,7 +777,7 @@ ALTER USER name [IF EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE | SUSPENDED}] [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"SET "}"] + {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... [REMOVE HOME DATABASE] [REMOVE { AUTH [PROVIDER[S]] provider[, ...] } \| { ALL AUTH [PROVIDER[S]] }] ---- diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index 0dc18d537..fcad44860 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -261,7 +261,7 @@ xref:authentication-authorization/auth-objects.adoc[Auth Objects] can be used to [NOTE] ==== -You need to set `internal.dbms.security.require_local_user` to `true` to use Auth Objects. This means that a user with a matching Auth Object *must* exist in order to be able to authenticate and authorize. +You need to set the `dbms.security.require_local_user` configuration setting to `true` to use Auth Objects. This means that a user with a matching Auth Object *must* exist in order to be able to authenticate and authorize. ==== The following examples show how you can use Cypher to do this. @@ -275,7 +275,7 @@ SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySso1Id'} // this must match the clai ---- This will create a user who can authenticate and authorize using `mysso` if they present a valid token with a `sub` claim of `jakesUniqueMySso1Id`. The claim used for authentication is determined by the xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] config setting (default the default is the `sub` claim). -When `internal.dbms.security.require_local_user` is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Object which links to the provider that the user is trying to authenticate with. If there is no matching Auth Object, the user will not be able to authenticate or authorize. This applies to all providers. +When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Object which links to the provider that the user is trying to authenticate with. If there is no matching Auth Object, the user will not be able to authenticate or authorize. This applies to all providers. ====== diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index 0232467ba..aa1a769c3 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -24,7 +24,7 @@ SSO works in the following way: . The identity provider responds with a JSON Web Token (JWT), a JSON file containing fields (claims) relative to the user (email, audience, groups, etc.). . The client provides the server with the JWT, and the server verifies its signature with the JWKs. [role=label--new-5.24] -. By setting `internal.dbms.security.require_local_user` is set to `true`, you can control which users can authenticate and authorize by creating xref:authentication-authorization/auth-objects.adoc[Auth Objects] in the database using Cypher. In this mode, a user with a matching Auth Object must exist in the database for the user to be able to authenticate and authorize using an SSO (or any external) provider. This allows you to do the following in the database, using Cypher: +. By setting the `dbms.security.require_local_user` configuration setting to `true`, you can control which users can authenticate and authorize by creating xref:authentication-authorization/auth-objects.adoc[Auth Objects] in the database using Cypher. In this mode, a user with a matching Auth Object must exist in the database for the user to be able to authenticate and authorize using an SSO (or any external) provider. This allows you to do the following in the database, using Cypher: .. `SUSPEND` SSO users. .. Set the `HOME DATABASE` for an SSO user. .. Set a reader-friendly name for an SSO user (rather than relying on the external identifier). @@ -133,7 +133,7 @@ dbms.security.oidc.okta.config=token_type_principal=id_token;token_type_authenti image::sso-configuration-tutorials/okta-sign-on-tab.svg[title="Okta's sign-on tab"] + [role=label--new-5.24] -. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-objects.adoc[Auth Objects] to achieve this. Set `internal.dbms.security.require_local_user` to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate using native or Okta, and authorize using Okta (as configured in step 3), you can use the following Cypher query: +. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-objects.adoc[Auth Objects] to achieve this. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate using native or Okta, and authorize using Okta (as configured in step 3), you can use the following Cypher query: [source, cypher, role=noplay] ---- CREATE USER jake @@ -323,7 +323,7 @@ dbms.security.oidc.azure.claims.groups=roles ---- [role=label--new-5.24] -. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-objects.adoc[Auth Objects] to achieve this. Set `internal.dbms.security.require_local_user` to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate and authorize using Entra, you can use the following Cypher query: +. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-objects.adoc[Auth Objects] to achieve this. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate and authorize using Entra, you can use the following Cypher query: [source, cypher, role=noplay] ---- CREATE USER jake @@ -379,11 +379,11 @@ xref:authentication-authorization/auth-objects.adoc[Auth Objects] allow us to sp dbms.security.authentication_providers=oidc-google, native ---- -.. Set the `internal.dbms.security.require_local_user` to `true` in the _neo4j.conf_ file. This will switch to Auth Objects mode whereby users can only authenticate and authorize if they have a corresponding Auth Object in the database. +.. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file. This will switch to Auth Objects mode whereby users can only authenticate and authorize if they have a corresponding Auth Object in the database. [source, properties] ---- -internal.dbms.security.require_local_user=true +dbms.security.require_local_user=true ---- From 8c29c866cc06ecb99f2cbd4107a49b6c089db73c Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Tue, 27 Aug 2024 10:55:13 +0100 Subject: [PATCH 06/62] pr review comments --- .../pages/authentication-authorization/manage-users.adoc | 8 -------- 1 file changed, 8 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 658f0ef19..f454e3e88 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -634,9 +634,6 @@ SET STATUS SUSPENDED SET HOME DATABASE anotherDb SET AUTH 'native' {SET PASSWORD 'abcd1234' SET PASSWORD CHANGE REQUIRED} ---- - - - ====== @@ -687,8 +684,6 @@ The equivalent command using the xref:authentication-authorization/auth-objects. CREATE USER jake IF NOT EXISTS SET AUTH 'native' {SET PLAINTEXT PASSWORD 'abcd1234'} ---- - - ====== The `CREATE OR REPLACE USER` command will result in any existing user being deleted and a new one created. @@ -712,9 +707,6 @@ The equivalent command using the xref:authentication-authorization/auth-objects. CREATE OR REPLACE USER jake SET AUTH 'native' {SET PLAINTEXT PASSWORD 'abcd1234'} ---- - - - ====== [NOTE] From 76d8ebbeb15a1693bb3f6b8b4b6303d0c7381ff6 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Tue, 27 Aug 2024 11:24:23 +0100 Subject: [PATCH 07/62] use the term `Auth Provider` instead of `Auth Object` --- modules/ROOT/content-nav.adoc | 2 +- ...{auth-objects.adoc => auth-providers.adoc} | 28 +++++++++---------- .../authentication-authorization/index.adoc | 4 +-- .../ldap-integration.adoc | 22 +++++++-------- .../manage-users.adoc | 28 +++++++++---------- .../sso-integration.adoc | 18 ++++++------ .../tutorial/tutorial-sso-configuration.adoc | 20 ++++++------- 7 files changed, 61 insertions(+), 61 deletions(-) rename modules/ROOT/pages/authentication-authorization/{auth-objects.adoc => auth-providers.adoc} (55%) diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 38fa5415a..a1fb005d4 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -185,7 +185,7 @@ *** xref:authentication-authorization/manage-execute-permissions.adoc[] ** xref:authentication-authorization/built-in-roles.adoc[] ** Integration with auth systems -*** xref:authentication-authorization/auth-objects.adoc[] +*** xref:authentication-authorization/auth-providers.adoc[] *** xref:authentication-authorization/ldap-integration.adoc[] *** xref:authentication-authorization/sso-integration.adoc[] diff --git a/modules/ROOT/pages/authentication-authorization/auth-objects.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc similarity index 55% rename from modules/ROOT/pages/authentication-authorization/auth-objects.adoc rename to modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 855d5f6b8..9056e0b54 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-objects.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -1,12 +1,12 @@ :description: This section explains how to use Cypher to manage authentication and authorization at the user level using Cypher. [role=label--new-5.24] -[[access-control-auth-objects]] -= Auth objects label:enterprise-edition[] +[[access-control-auth-providers]] += User Auth Providers label:enterprise-edition[] -User Auth Objects provide a way to configure authentication and authorization at the user-level using Cypher. +Authentication and authorization can be controlled on a user-level using Cypher by setting Auth Providers on users. -Using the database in Auth Object mode mandates that only users with a corresponding Auth Object in the database can authenticate and authorize. This mode is enabled by changing the `dbms.security.require_local_user` configuration setting to `true`. +Using the database in Auth Provider mode mandates that only users with a corresponding Auth Provider in the database can authenticate and authorize. This mode is enabled by changing the `dbms.security.require_local_user` configuration setting to `true`. This gives us a way to link externally-defined users to the Neo4j internal user model. The internal model can define things such as roles (authorization), `SUSPENDED` status, `HOME DATABASE`, and metadata such as the unique displayed name of the user. @@ -19,21 +19,21 @@ This gives us a way to link externally-defined users to the Neo4j internal user . 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 Objects 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 which match the provider of the matching Auth Object. +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 which match the provider name of the matching Auth Provider. The way that 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 Object 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 Auth Object with a `provider` property of `ldap` and an `ID` property which matches the supplied `dn`. -- For the `native` (username/password) provider, the supplied username itself is used to look up the Auth Object. +- 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 which matches the supplied `dn`. +- For the `native` (username/password) provider, the supplied username itself is used to look up the Auth Provider. -== Enabling Auth Objects mode -When the configuration setting `dbms.security.require_local_user` is set to `true`, the lookups described above will be performed when the user authenticates, and a matching user Auth Object *must* exist in order for a user to be able to successfully authenticate and authorize. +== Enabling Auth Providers mode +When the configuration setting `dbms.security.require_local_user` is set to `true`, the lookups described above will be performed when the user authenticates, and a matching user Auth Provider *must* exist in order for a user to be able to successfully authenticate and authorize. == Examples -For examples of how to use Auth Objects with different authentication providers, see the following sections: +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-objects[SSO Auth Object Examples] -- xref:authentication-authorization/manage-users.adoc#access-control-create-users[`native` Auth Object Examples] -- xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-objects[LDAP Auth Object Examples] +- xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO Auth Provider Examples] +- xref:authentication-authorization/manage-users.adoc#access-control-create-users[`native` Auth Provider Examples] +- xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[LDAP Auth Provider Examples] diff --git a/modules/ROOT/pages/authentication-authorization/index.adoc b/modules/ROOT/pages/authentication-authorization/index.adoc index 3b964fc0c..1b8c70aa7 100644 --- a/modules/ROOT/pages/authentication-authorization/index.adoc +++ b/modules/ROOT/pages/authentication-authorization/index.adoc @@ -93,8 +93,8 @@ This is in contrast to a suspended user. [[term-administrator]]administrator:: This is a user who has been assigned the admin role. -[[term-auth-object]]Auth Object:: -A map object attached to a database user which defines which authentication and authorization settings to use for that user. +[[term-auth-provider]]Auth Provider:: +A map attached to a database user which defines which authentication and authorization config to use for that user. [[term-authentication]]authentication:: The process of verifying the identity of a user, diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index 54ce5d1d4..06d98a76f 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -16,7 +16,7 @@ The following topics are covered: ** 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-auth-objects[Use Auth Objects to configure authentication / authorization at the user level] +* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[Control authentication and authorization at the user-level by setting Auth Providers on users] * 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] @@ -360,18 +360,18 @@ dbms.security.ldap.authorization.access_permitted_group=501 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-objects]] -== Use Auth Objects to configure authentication / authorization at the user level -xref:authentication-authorization/auth-objects.adoc[Auth Objects] can be used to determine which users can authenticate and authorize using the configured providers, including LDAP. +[[auth-ldap-auth-providers]] +== Use Auth Providers to configure authentication / authorization at the user level +xref:authentication-authorization/auth-providers.adoc[Auth Providers] can be used to determine which users can authenticate and authorize using the configured providers, including LDAP. [NOTE] ==== -You need to change the `dbms.security.require_local_user` configuration setting to `true` to use Auth Objects. This means that a user with a matching Auth Object *must* exist in order to be able to authenticate and authorize. +You need to change the `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. ==== The following examples show how you can use Cypher to do this. -.Create a user with an Auth Object who can authenticate and authorize using `LDAP`. +.Create a user with an Auth Provider who can authenticate and authorize using `LDAP`. ====== ---- CREATE USER alice @@ -379,11 +379,11 @@ SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } ---- This will create a user who can authenticate and authorize using LDAP provided their LDAP `dn` is `cn=alice,ou=engineering,dc=example,dc=com`. -When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Object which links to the provider that the user is trying to authenticate with. If there is no matching Auth Object, the user will not be able to authenticate or authorize. This applies to all providers. +When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. If there is no matching Auth Provider, the user will not be able to authenticate or authorize. This applies to all providers. ====== -.Create a user with two Auth Objects allowing the user to authenticate and authorize with either LDAP or the `oidc-mysso` provider. +.Create a user with two Auth Providers allowing the user to authenticate and authorize with either LDAP or the `oidc-mysso` provider. ====== ---- CREATE USER alice @@ -391,11 +391,11 @@ SET HOME DATABASE anotherDb SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } SET AUTH 'oidc-mysso1' {SET ID 'alicesUniqueMySso1Id'} ---- -This will create a user who can authenticate and authorize using `ldap` or `oidc-mysso`. See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[SSO integration] for more information on setting up an OIDC provider. +This will create a user who can authenticate and authorize using `ldap` or `oidc-mysso`. See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for more information on setting up an OIDC provider. This example also illustrates that the user can have their `HOME` database set even when using an external auth provider. ====== -.Alter a user to remove one of their Auth Objects. +.Alter a user to remove one of their Auth Providers. ====== ---- ALTER USER alice @@ -426,7 +426,7 @@ dbms.security.authentication_providers=ldap dbms.security.authorization_providers=native ---- -Then create a user with an `ldap` Auth Object: +Then create a user with an `ldap` Auth Provider: ---- CREATE USER alice SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index f454e3e88..d1d7c74bb 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -160,7 +160,7 @@ Creates a new user. [NOTE] ==== -It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Object. +It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Provider. ==== For more information, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. @@ -197,7 +197,7 @@ a| Creates a new user, or if a user with the same name exists, replace it. [NOTE] ==== -It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Object. +It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Provider. ==== For more information, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. @@ -599,9 +599,9 @@ A home database will be resolved if it is either pointing to a database or a dat If no home database is set, the DBMS default database is used as the home database for the user. * The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, and `SET HOME DATABASE` clauses can be applied in any order. [role=label--new-5.24] -* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-objects.adoc[Auth Objects], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. -Examples can be found below for `native`, xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[here] for OIDC and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-objects[here] for LDAP. -* It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Object. +* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[Auth Providers], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. +Examples can be found below for `native`, xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[here] for OIDC and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[here] for LDAP. +* It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Provider. [NOTE] ==== @@ -625,7 +625,7 @@ SET STATUS SUSPENDED SET HOME DATABASE anotherDb ---- -The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: [source,cypher,role=noplay] ---- @@ -648,7 +648,7 @@ SET ENCRYPTED PASSWORD '1,6d57a5e0b3317055454e455f96c98c750c77fb371f3f0634a1b8ff SET STATUS ACTIVE ---- [role=label--new-5.24] -The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: [source,cypher,role=noplay] ---- @@ -677,7 +677,7 @@ SET PLAINTEXT PASSWORD 'abcd1234' ---- [role=label--new-5.24] -The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: [source,cypher,role=noplay] ---- @@ -700,7 +700,7 @@ SET PLAINTEXT PASSWORD 'abcd1234' This is equivalent to running `DROP USER jake IF EXISTS` followed by `CREATE USER jake SET PASSWORD 'abcd1234'`. [role=label--new-5.24] -The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: [source,cypher,role=noplay] ---- @@ -797,12 +797,12 @@ The `SET PASSWORD` part is only optional if it directly follows the `SET PASSWOR A home database will be resolved if it is either pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for the user. [role=label--new-5.24] -* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-objects.adoc[Auth Objects], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. TODO: Insert links to the LDAP and OIDC examples. +* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[Auth Providers], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. TODO: Insert links to the LDAP and OIDC examples. * `REMOVE HOME DATABASE` is used to unset the home database for a user. This results in the DBMS default database being used as the home database for the user. [role=label--new-5.24] -* `REMOVE AUTH` is used to remove one or many xref:authentication-authorization/auth-objects.adoc[Auth Object(s)] from a user. It cannot be used such that a user would have no Auth Objects. -* `REMOVE ALL AUTH` is used to remove all existing xref:authentication-authorization/auth-objects.adoc[Auth Objects] from a user and replace them with new ones. It must be used in conjunction with at least one `SET AUTH` clause. +* `REMOVE AUTH` is used to remove one or many xref:authentication-authorization/auth-providers.adoc[Auth Provider(s)] from a user. It cannot be used in a way that would mean a user has no Auth Providers. +* `REMOVE ALL AUTH` is used to remove all existing xref:authentication-authorization/auth-providers.adoc[Auth Providers] from a user and replace them with new ones. It must be used in conjunction with at least one `SET AUTH` clause. .Modify the user `bob` with a new password and active status, and remove the requirement to change his password: @@ -815,7 +815,7 @@ SET STATUS ACTIVE ---- [role=label--new-5.24] -The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: ---- ALTER USER bob @@ -833,7 +833,7 @@ SET PASSWORD CHANGE REQUIRED ---- [role=label--new-5.24] -The equivalent command using the xref:authentication-authorization/auth-objects.adoc[Auth Objects] syntax would be: +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: ---- ALTER USER bob diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index fcad44860..d7c7d2485 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -255,19 +255,19 @@ See xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-role [role=label--new-5.24] -[[auth-sso-auth-objects]] -=== Use Auth Objects to configure SSO at the user level -xref:authentication-authorization/auth-objects.adoc[Auth Objects] can be used to determine which users can authenticate and authorize using the configured providers. +[[auth-sso-auth-providers]] +=== Use Auth Providers to configure SSO at the user level +xref:authentication-authorization/auth-providers.adoc[Auth Providers] can be used to determine which users can authenticate and authorize using the configured providers. [NOTE] ==== -You need to set the `dbms.security.require_local_user` configuration setting to `true` to use Auth Objects. This means that a user with a matching Auth Object *must* exist in order to be able to authenticate and authorize. +You need to set the `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. ==== The following examples show how you can use Cypher to do this. -.Create a user with an Auth Object who can authenticate and authorize using `oidc-mysso`. +.Create a user with an Auth Provider who can authenticate and authorize using `oidc-mysso`. ====== ---- CREATE USER jake @@ -275,11 +275,11 @@ SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySso1Id'} // this must match the clai ---- This will create a user who can authenticate and authorize using `mysso` if they present a valid token with a `sub` claim of `jakesUniqueMySso1Id`. The claim used for authentication is determined by the xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] config setting (default the default is the `sub` claim). -When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Object which links to the provider that the user is trying to authenticate with. If there is no matching Auth Object, the user will not be able to authenticate or authorize. This applies to all providers. +When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. If there is no matching Auth Provider, the user will not be able to authenticate or authorize. This applies to all providers. ====== -.Create a user with two Auth Objects allowing the user to authenticate and authorize with either of two providers. +.Create a user with two Auth Providers allowing the user to authenticate and authorize with either of two providers. ====== ---- CREATE USER jake @@ -292,7 +292,7 @@ This example also illustrates that the user can have their `HOME` database set e ====== -.Alter a user to remove one of their Auth Objects. +.Alter a user to remove one of their Auth Providers. ====== ---- ALTER USER jake @@ -323,7 +323,7 @@ dbms.security.authentication_providers=oidc-mysso dbms.security.authorization_providers=native ---- -Then create a user with a `oidc-mysso` Auth Object: +Then create a user with a `oidc-mysso` Auth Provider: ---- CREATE USER jake SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySsoId'} // this must match the claim that you configured via dbms.security.oidc.mysso.claims.username diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index aa1a769c3..3204e82d9 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -24,12 +24,12 @@ SSO works in the following way: . The identity provider responds with a JSON Web Token (JWT), a JSON file containing fields (claims) relative to the user (email, audience, groups, etc.). . The client provides the server with the JWT, and the server verifies its signature with the JWKs. [role=label--new-5.24] -. By setting the `dbms.security.require_local_user` configuration setting to `true`, you can control which users can authenticate and authorize by creating xref:authentication-authorization/auth-objects.adoc[Auth Objects] in the database using Cypher. In this mode, a user with a matching Auth Object must exist in the database for the user to be able to authenticate and authorize using an SSO (or any external) provider. This allows you to do the following in the database, using Cypher: +. By setting the `dbms.security.require_local_user` configuration setting to `true`, you can control which users can authenticate and authorize by creating xref:authentication-authorization/auth-providers.adoc[Auth Providers] in the database using Cypher. In this mode, a user with a matching Auth Provider must exist in the database for the user to be able to authenticate and authorize using an SSO (or any external) provider. This allows you to do the following in the database, using Cypher: .. `SUSPEND` SSO users. .. Set the `HOME DATABASE` for an SSO user. .. Set a reader-friendly name for an SSO user (rather than relying on the external identifier). -See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[SSO integration] for examples. +See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for examples. + [IMPORTANT] ==== @@ -133,7 +133,7 @@ dbms.security.oidc.okta.config=token_type_principal=id_token;token_type_authenti image::sso-configuration-tutorials/okta-sign-on-tab.svg[title="Okta's sign-on tab"] + [role=label--new-5.24] -. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-objects.adoc[Auth Objects] to achieve this. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate using native or Okta, and authorize using Okta (as configured in step 3), you can use the following Cypher query: +. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-providers.adoc[Auth Providers] to achieve this. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate using native or Okta, and authorize using Okta (as configured in step 3), you can use the following Cypher query: [source, cypher, role=noplay] ---- CREATE USER jake @@ -142,7 +142,7 @@ SET AUTH 'oidc-okta' {SET ID 'jakesUniqueOktaUserId'} // this must match the cla SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED} ---- -See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[SSO integration] for further examples. +See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for further examples. @@ -323,7 +323,7 @@ dbms.security.oidc.azure.claims.groups=roles ---- [role=label--new-5.24] -. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-objects.adoc[Auth Objects] to achieve this. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate and authorize using Entra, you can use the following Cypher query: +. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-providers.adoc[Auth Providers] to achieve this. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate and authorize using Entra, you can use the following Cypher query: [source, cypher, role=noplay] ---- CREATE USER jake @@ -331,7 +331,7 @@ SET HOME DATABASE 'jakesHomeDb' SET AUTH 'oidc-okta' {SET ID 'jakesUniqueEntraUserId'} // this must match the claim that you configured via dbms.security.oidc.azure.claims.username ---- -See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-objects[SSO integration] for further examples. +See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for further examples. == Google @@ -369,8 +369,8 @@ dbms.security.oidc.google.config=token_type_principal=id_token;token_type_authen There are then two ways to create the user in the database (which is required to give the users roles from native authorization): -. Using Auth Objects -xref:authentication-authorization/auth-objects.adoc[Auth Objects] allow us to specify auth providers at the user-level which is useful in this scenario. This approach allows us to have an `admin` user who can authenticate natively, and can then create less privileged users who may only authenticate using `oidc-google` and will receive the roles granted to them using `native` authorization. +. Using Auth Providers +xref:authentication-authorization/auth-providers.adoc[Auth Providers] allow us to specify auth providers at the user-level which is useful in this scenario. This approach allows us to have an `admin` user who can authenticate natively, and can then create less privileged users who may only authenticate using `oidc-google` and will receive the roles granted to them using `native` authorization. .. Change the configuration to allow `native` authentication (for use only by the `admin` user): @@ -379,7 +379,7 @@ xref:authentication-authorization/auth-objects.adoc[Auth Objects] allow us to sp dbms.security.authentication_providers=oidc-google, native ---- -.. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file. This will switch to Auth Objects mode whereby users can only authenticate and authorize if they have a corresponding Auth Object in the database. +.. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file. This will switch to Auth Providers mode whereby users can only authenticate and authorize if they have a corresponding Auth Provider in the database. [source, properties] ---- @@ -414,7 +414,7 @@ dbms.security.authentication_providers=oidc-google -. Alternatively, if you don't use Auth Objects, you can temporarily enable `native` authentication to create an SSO-authenticated admin user `alice` who can then create other users who can only authenticate using SSO. +. Alternatively, if you don't use Auth Providers, you can temporarily enable `native` authentication to create an SSO-authenticated admin user `alice` who can then create other users who can only authenticate using SSO. To do this we temporarily enable native authentication: From 89c346b8d1d923017fb727fd75b60c50bbac82da Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Tue, 27 Aug 2024 11:48:52 +0100 Subject: [PATCH 08/62] rewording --- .../pages/authentication-authorization/auth-providers.adoc | 6 +++--- modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 9056e0b54..fa8af3d7f 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -6,9 +6,9 @@ Authentication and authorization can be controlled on a user-level using Cypher by setting Auth Providers on users. -Using the database in Auth Provider mode mandates that only users with a corresponding Auth Provider in the database can authenticate and authorize. This mode is enabled by changing the `dbms.security.require_local_user` configuration setting to `true`. +In order to make use of Auth Providers, you need to set the `dbms.security.require_local_user` configuration setting to `true`. This setting mandates that only users with a corresponding Auth Provider in the database can authenticate and authorize. -This gives us a way to link externally-defined users to the Neo4j internal user model. The internal model can define things such as roles (authorization), `SUSPENDED` status, `HOME DATABASE`, and metadata such as the unique displayed name of the user. +Auth Providers give you a way to link externally-defined users (e.g. in a 3rd party ID provider like OIDC or LDAP) to the Neo4j internal User model. The internal model can define things such as 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. == Use Cases . Provisioning different auth providers (including native username/password auth) for different users. @@ -27,7 +27,7 @@ The way that the matching lookup is done depends on the type of provider. For ex - For an LDAP provider, the `dn` is used to look up an Auth Provider with a `provider` property of `ldap` and an `ID` property which matches the supplied `dn`. - For the `native` (username/password) provider, the supplied username itself is used to look up the Auth Provider. -== Enabling Auth Providers mode +== Enabling User Auth Providers mode When the configuration setting `dbms.security.require_local_user` is set to `true`, the lookups described above will be performed when the user authenticates, and a matching user Auth Provider *must* exist in order for a user to be able to successfully authenticate and authorize. == Examples diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index 3204e82d9..fdcd7b2ab 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -379,7 +379,7 @@ xref:authentication-authorization/auth-providers.adoc[Auth Providers] allow us t dbms.security.authentication_providers=oidc-google, native ---- -.. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file. This will switch to Auth Providers mode whereby users can only authenticate and authorize if they have a corresponding Auth Provider in the database. +.. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file. This will switch to User Auth Providers mode whereby users can only authenticate and authorize if they have a corresponding Auth Provider in the database. [source, properties] ---- From 860bb43810bdd800ee1a1f201a1c84f2cdf7b06d Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Tue, 27 Aug 2024 12:22:05 +0100 Subject: [PATCH 09/62] clarifying what ``s are allowed --- .../manage-users.adoc | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index d1d7c74bb..6655f06d5 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -154,6 +154,19 @@ CREATE USER name [IF NOT EXISTS] {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... ---- +`` pairs for the `SET AUTH` clause could include: +[source, syntax, role="noheader"] +---- +SET AUTH [PROVIDER] 'provider' "{" + { + SET ID 'id' // a unique identifier of the user in an external system + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' + \| SET PASSWORD CHANGE [NOT] REQUIRED + } +"}" +---- + + | Description a| Creates a new user. @@ -191,6 +204,17 @@ CREATE OR REPLACE USER name [SET HOME DATABASE name] {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... ---- +`` pairs for the `SET AUTH` clause could include: +[source, syntax, role="noheader"] +---- +SET AUTH [PROVIDER] 'provider' "{" + { + SET ID 'id' // a unique identifier of the user in an external system + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' + \| SET PASSWORD CHANGE [NOT] REQUIRED + } +"}" +---- | Description a| @@ -267,6 +291,17 @@ ALTER USER name [IF EXISTS] [REMOVE HOME DATABASE] [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }] ---- +`` pairs for the `SET AUTH` clause could include: +[source, syntax, role="noheader"] +---- +SET AUTH [PROVIDER] 'provider' "{" + { + SET ID 'id' // a unique identifier of the user in an external system + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' + \| SET PASSWORD CHANGE [NOT] REQUIRED + } +"}" +---- | Description a| @@ -578,6 +613,18 @@ CREATE OR REPLACE USER name {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... ---- +For both `CREATE` and `CREATE OR REPLACE`, `` pairs for the `SET AUTH` clause could include: + +[source, syntax, role="noheader"] +---- +SET AUTH [PROVIDER] 'provider' "{" + { + SET ID 'id' // a unique identifier of the user in an external system + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' + \| SET PASSWORD CHANGE [NOT] REQUIRED + } +"}" +---- * For `SET PASSWORD`: ** The `password` can either be a string value or a string parameter. ** The default Neo4j password length is at least 8 characters. @@ -773,6 +820,17 @@ ALTER USER name [IF EXISTS] [REMOVE HOME DATABASE] [REMOVE { AUTH [PROVIDER[S]] provider[, ...] } \| { ALL AUTH [PROVIDER[S]] }] ---- +`` pairs for the `SET AUTH` clause could include: +[source, syntax, role="noheader"] +---- +SET AUTH [PROVIDER] 'provider' "{" + { + SET ID 'id' // a unique identifier of the user in an external system + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' + \| SET PASSWORD CHANGE [NOT] REQUIRED + } +"}" +---- * At least one `SET` or `REMOVE` clause is required for the command. * `SET` and `REMOVE` clauses cannot be combined in the same command. From d3f464485ac7c3eecfd1806bf86822a269fedf8f Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Thu, 29 Aug 2024 13:26:10 +0100 Subject: [PATCH 10/62] pr review comments --- .../ROOT/pages/authentication-authorization/auth-providers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index fa8af3d7f..e89de3d77 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -8,7 +8,7 @@ Authentication and authorization can be controlled on a user-level using Cypher In order to make use of Auth Providers, you need to set the `dbms.security.require_local_user` configuration setting to `true`. This setting mandates that only users with a corresponding Auth Provider in the database can authenticate and authorize. -Auth Providers give you a way to link externally-defined users (e.g. in a 3rd party ID provider like OIDC or LDAP) to the Neo4j internal User model. The internal model can define things such as 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. +Auth Providers give you a way to link externally-defined users (e.g. in a 3rd party ID provider like OIDC or LDAP) to the Neo4j internal User model. The internal model can define things such as 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 . Provisioning different auth providers (including native username/password auth) for different users. From cdb1491b8bb7b5729521d0c64acd59da98e17311 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Wed, 4 Sep 2024 11:01:56 +0100 Subject: [PATCH 11/62] add example for multiple ldap trees --- .../ldap-integration.adoc | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index 06d98a76f..bea859ee8 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -457,6 +457,21 @@ SET STATUS SUSPENDED This will completely prevent 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 who is part of the `engineering` tree (`cn=alice,ou=engineering,dc=example,dc=com`) and the other who 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. + +---- +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 From 58ca963a119892e94aea4dcbe3218d85d6d395ed Mon Sep 17 00:00:00 2001 From: Phil Wright <95368282+phil198@users.noreply.github.com> Date: Wed, 4 Sep 2024 11:45:15 +0100 Subject: [PATCH 12/62] Apply suggestions from code review Co-authored-by: Therese Magnusson --- .../auth-providers.adoc | 6 ++++-- .../ldap-integration.adoc | 4 +--- .../manage-users.adoc | 11 +++++++---- .../sso-integration.adoc | 11 +++++------ .../tutorial/tutorial-sso-configuration.adoc | 18 +++++++++++++----- 5 files changed, 30 insertions(+), 20 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index e89de3d77..6914433ca 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -6,7 +6,8 @@ Authentication and authorization can be controlled on a user-level using Cypher by setting Auth Providers on users. -In order to make use of Auth Providers, you need to set the `dbms.security.require_local_user` configuration setting to `true`. This setting mandates that only users with a corresponding Auth Provider in the database can authenticate and authorize. +In order to make use of Auth Providers, you need to set the `dbms.security.require_local_user` configuration setting to `true`. +This setting mandates that only users with a corresponding Auth Provider in the database can authenticate and authorize. Auth Providers give you a way to link externally-defined users (e.g. in a 3rd party ID provider like OIDC or LDAP) to the Neo4j internal User model. The internal model can define things such as 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). @@ -19,7 +20,8 @@ Auth Providers give you a way to link externally-defined users (e.g. in a 3rd pa . 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 which match the provider name of the matching Auth Provider. +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 which match the provider name of the matching Auth Provider. The way that the matching lookup is done depends on the type of provider. For example: diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index bea859ee8..8cabcce62 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -392,7 +392,7 @@ SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } SET AUTH 'oidc-mysso1' {SET ID 'alicesUniqueMySso1Id'} ---- This will create a user who can authenticate and authorize using `ldap` or `oidc-mysso`. See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for more information on setting up an OIDC provider. -This example also illustrates that the user can have their `HOME` database set even when using an external auth provider. +This 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. @@ -400,7 +400,6 @@ This example also illustrates that the user can have their `HOME` database set e ---- ALTER USER alice REMOVE AUTH 'ldap' - ---- This will prevent the user from being able to authenticate and authorize using `ldap`. ====== @@ -410,7 +409,6 @@ This will prevent the user from being able to authenticate and authorize using ` ---- ALTER USER alice SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED} - ---- This will allow the user to authenticate and authorize using the specified username and password (in addition to what they are already configured to use). ====== diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 6655f06d5..855fd0a25 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -287,9 +287,9 @@ ALTER USER name [IF EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED} ] [SET HOME DATABASE name] - {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... [REMOVE HOME DATABASE] - [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }] + [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }]... ---- `` pairs for the `SET AUTH` clause could include: [source, syntax, role="noheader"] @@ -701,7 +701,10 @@ The equivalent command using the xref:authentication-authorization/auth-provider ---- CREATE USER jake SET STATUS ACTIVE -SET AUTH 'native' {SET ENCRYPTED PASSWORD '1,6d57a5e0b3317055454e455f96c98c750c77fb371f3f0634a1b8ff2a55c5b825,190ae47c661e0668a0c8be8a21ff78a4a34cdf918cae3c407e907b73932bd16c' SET PASSWORD CHANGE NOT REQUIRED} +SET AUTH 'native' { + SET ENCRYPTED PASSWORD '1,6d57a5e0b3317055454e455f96c98c750c77fb371f3f0634a1b8ff2a55c5b825,190ae47c661e0668a0c8be8a21ff78a4a34cdf918cae3c407e907b73932bd16c' + SET PASSWORD CHANGE NOT REQUIRED +} ---- ====== @@ -818,7 +821,7 @@ ALTER USER name [IF EXISTS] [SET HOME DATABASE name] {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... [REMOVE HOME DATABASE] - [REMOVE { AUTH [PROVIDER[S]] provider[, ...] } \| { ALL AUTH [PROVIDER[S]] }] + [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }]... ---- `` pairs for the `SET AUTH` clause could include: [source, syntax, role="noheader"] diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index d7c7d2485..5fe769a26 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -271,9 +271,10 @@ The following examples show how you can use Cypher to do this. ====== ---- CREATE USER jake -SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySso1Id'} // this must match the claim that you configured via dbms.security.oidc.mysso.claims.username +SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySso1Id'} // the id must match the claim that you configured via dbms.security.oidc.mysso.claims.username ---- -This will create a user who can authenticate and authorize using `mysso` if they present a valid token with a `sub` claim of `jakesUniqueMySso1Id`. The claim used for authentication is determined by the xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] config setting (default the default is the `sub` claim). +This will create a user who can authenticate and authorize using `mysso` if they present a valid token with a `sub` claim of `jakesUniqueMySso1Id`. +The claim used for authentication is determined by the xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] config setting (default the default is the `sub` claim). When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. If there is no matching Auth Provider, the user will not be able to authenticate or authorize. This applies to all providers. ====== @@ -288,7 +289,7 @@ SET AUTH 'oidc-mysso1' {SET ID 'jakesUniqueMySso1Id'} // this must match the cla SET AUTH 'oidc-mysso2' {SET ID 'jakesUniqueMySso2Id'} // this must match the claim that you configured via dbms.security.oidc.mysso2.claims.username ---- This will create a user who can authenticate and authorize using `oidc-mysso1` or `oidc-mysso2`. -This example also illustrates that the user can have their `HOME` database set even when using an external auth provider. +This example also illustrates that the user can have their home database set even when using only external auth providers. ====== @@ -297,7 +298,6 @@ This example also illustrates that the user can have their `HOME` database set e ---- ALTER USER jake REMOVE AUTH 'oidc-mysso2' - ---- This will prevent the user from being able to authenticate and authorize with the `oidc-mysso2` provider. ====== @@ -307,9 +307,8 @@ This will prevent the user from being able to authenticate and authorize with th ---- ALTER USER jake SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED} - ---- -This will allow the user to authenticate and authorize using the specified username and password +This will allow the user to authenticate and authorize using the specified username and password (in addition to what they are already configured to use). ====== diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index fdcd7b2ab..a7203bab0 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -24,7 +24,9 @@ SSO works in the following way: . The identity provider responds with a JSON Web Token (JWT), a JSON file containing fields (claims) relative to the user (email, audience, groups, etc.). . The client provides the server with the JWT, and the server verifies its signature with the JWKs. [role=label--new-5.24] -. By setting the `dbms.security.require_local_user` configuration setting to `true`, you can control which users can authenticate and authorize by creating xref:authentication-authorization/auth-providers.adoc[Auth Providers] in the database using Cypher. In this mode, a user with a matching Auth Provider must exist in the database for the user to be able to authenticate and authorize using an SSO (or any external) provider. This allows you to do the following in the database, using Cypher: +. By setting the `dbms.security.require_local_user` configuration setting to `true`, you can control which users can authenticate and authorize by creating xref:authentication-authorization/auth-providers.adoc[Auth Providers] in the database using Cypher. +In this mode, a user with a matching Auth Provider must exist in the database for the user to be able to authenticate and authorize using an SSO (or any external) provider. +This allows you to do the following in the database, using Cypher: .. `SUSPEND` SSO users. .. Set the `HOME DATABASE` for an SSO user. .. Set a reader-friendly name for an SSO user (rather than relying on the external identifier). @@ -133,7 +135,9 @@ dbms.security.oidc.okta.config=token_type_principal=id_token;token_type_authenti image::sso-configuration-tutorials/okta-sign-on-tab.svg[title="Okta's sign-on tab"] + [role=label--new-5.24] -. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-providers.adoc[Auth Providers] to achieve this. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate using native or Okta, and authorize using Okta (as configured in step 3), you can use the following Cypher query: +. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-providers.adoc[Auth Providers] to achieve this. +Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. +For example to create a user `jake` who can authenticate using native or Okta, and authorize using Okta (as configured in step 3), you can use the following Cypher query: [source, cypher, role=noplay] ---- CREATE USER jake @@ -323,7 +327,9 @@ dbms.security.oidc.azure.claims.groups=roles ---- [role=label--new-5.24] -. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-providers.adoc[Auth Providers] to achieve this. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate and authorize using Entra, you can use the following Cypher query: +. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-providers.adoc[Auth Providers] to achieve this. +Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. +For example to create a user `jake` who can authenticate and authorize using Entra, you can use the following Cypher query: [source, cypher, role=noplay] ---- CREATE USER jake @@ -370,7 +376,8 @@ dbms.security.oidc.google.config=token_type_principal=id_token;token_type_authen There are then two ways to create the user in the database (which is required to give the users roles from native authorization): . Using Auth Providers -xref:authentication-authorization/auth-providers.adoc[Auth Providers] allow us to specify auth providers at the user-level which is useful in this scenario. This approach allows us to have an `admin` user who can authenticate natively, and can then create less privileged users who may only authenticate using `oidc-google` and will receive the roles granted to them using `native` authorization. +xref:authentication-authorization/auth-providers.adoc[Auth Providers] allow us to specify auth providers at the user-level which is useful in this scenario. +This approach allows us to have an `admin` user who can authenticate natively, and can then create less privileged users who may only authenticate using `oidc-google` and will receive the roles granted to them using `native` authorization. .. Change the configuration to allow `native` authentication (for use only by the `admin` user): @@ -379,7 +386,8 @@ xref:authentication-authorization/auth-providers.adoc[Auth Providers] allow us t dbms.security.authentication_providers=oidc-google, native ---- -.. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file. This will switch to User Auth Providers mode whereby users can only authenticate and authorize if they have a corresponding Auth Provider in the database. +.. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file. +This will switch to User Auth Providers mode whereby users can only authenticate and authorize if they have a corresponding Auth Provider in the database. [source, properties] ---- From e988b8bfc8876880a0d71d77703ab2867486695d Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Wed, 4 Sep 2024 14:55:23 +0100 Subject: [PATCH 13/62] pr review comments --- .../authentication-authorization/auth-providers.adoc | 2 +- .../authentication-authorization/manage-users.adoc | 12 ++++++++---- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 6914433ca..909b99745 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -36,6 +36,6 @@ When the configuration setting `dbms.security.require_local_user` is set to `tru 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[SSO Auth Provider Examples] -- xref:authentication-authorization/manage-users.adoc#access-control-create-users[`native` Auth Provider Examples] +- xref:authentication-authorization/manage-users.adoc#access-control-create-users[Native Auth Provider Examples] - xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[LDAP Auth Provider Examples] diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 855fd0a25..51cfa7feb 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -858,12 +858,15 @@ The `SET PASSWORD` part is only optional if it directly follows the `SET PASSWOR A home database will be resolved if it is either pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for the user. [role=label--new-5.24] -* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[Auth Providers], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. TODO: Insert links to the LDAP and OIDC examples. +* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[Auth Providers], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. +** xref:authentication-authorization/manage-users.adoc#access-control-create-users[Native Auth Provider Examples] +** xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO Auth Provider Examples] +** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[LDAP Auth Provider Examples] * `REMOVE HOME DATABASE` is used to unset the home database for a user. This results in the DBMS default database being used as the home database for the user. [role=label--new-5.24] * `REMOVE AUTH` is used to remove one or many xref:authentication-authorization/auth-providers.adoc[Auth Provider(s)] from a user. It cannot be used in a way that would mean a user has no Auth Providers. -* `REMOVE ALL AUTH` is used to remove all existing xref:authentication-authorization/auth-providers.adoc[Auth Providers] from a user and replace them with new ones. It must be used in conjunction with at least one `SET AUTH` clause. +* `REMOVE ALL AUTH` is used to remove all existing xref:authentication-authorization/auth-providers.adoc[Auth Providers] from a user. It must be used in conjunction with at least one `SET AUTH` clause in order to meet the requirement that a user always has at least one auth provider. .Modify the user `bob` with a new password and active status, and remove the requirement to change his password: @@ -909,9 +912,10 @@ SET AUTH 'native' {SET PASSWORD CHANGE REQUIRED} ALTER USER bob SET HOME DATABASE anotherDbOrAlias ---- +====== -Or remove the `HOME` database from the user `bob`: - +.Remove the home database from the user `bob`: +====== [source,cypher,role=noplay] ---- ALTER USER bob From e4257181bffa6233131ceba75e86d140658d1673 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Wed, 4 Sep 2024 15:24:28 +0100 Subject: [PATCH 14/62] pr review comments --- .../authentication-authorization/ldap-integration.adoc | 6 +++++- .../pages/authentication-authorization/manage-users.adoc | 2 +- .../pages/authentication-authorization/sso-integration.adoc | 6 +++++- 3 files changed, 11 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index 8cabcce62..8f1861e0c 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -379,7 +379,11 @@ SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } ---- This will create a user who can authenticate and authorize using LDAP provided their LDAP `dn` is `cn=alice,ou=engineering,dc=example,dc=com`. -When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. If there is no matching Auth Provider, the user will not be able to authenticate or authorize. This applies to all providers. +When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. + +If there is no matching Auth Provider, the user will not be able to authenticate or authorize. This applies to all providers. + +Conversely, when `internal.dbms.security.require_local_user` is set to `true`, users' Auth Providers will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. ====== diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 51cfa7feb..3fd66dba0 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -318,7 +318,7 @@ a| GRANT SET PASSWORD ---- -[source, privilege, role="noheader" +[source, privilege, role="noheader"] ---- GRANT SET USER STATUS ---- diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index 5fe769a26..d19a8e8fd 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -276,7 +276,11 @@ SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySso1Id'} // the id must match the cl This will create a user who can authenticate and authorize using `mysso` if they present a valid token with a `sub` claim of `jakesUniqueMySso1Id`. The claim used for authentication is determined by the xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] config setting (default the default is the `sub` claim). -When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. If there is no matching Auth Provider, the user will not be able to authenticate or authorize. This applies to all providers. +When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. + +If there is no matching Auth Provider, the user will not be able to authenticate or authorize. This applies to all providers. + +Conversely, when `internal.dbms.security.require_local_user` is set to `true`, users' Auth Providers will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. ====== From 69ce049d2edf3f53070158b799d534afdc90a663 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Wed, 4 Sep 2024 16:08:48 +0100 Subject: [PATCH 15/62] pr review comments --- .../ldap-integration.adoc | 6 ++--- .../manage-users.adoc | 2 +- .../sso-integration.adoc | 26 +++++++++---------- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index 8f1861e0c..710700eac 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -387,15 +387,15 @@ Conversely, when `internal.dbms.security.require_local_user` is set to `true`, u ====== -.Create a user with two Auth Providers allowing the user to authenticate and authorize with either LDAP or the `oidc-mysso` provider. +.Create a user with two Auth Providers allowing the user to authenticate and authorize with either LDAP or the `mysso` provider. ====== ---- CREATE USER alice SET HOME DATABASE anotherDb SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } -SET AUTH 'oidc-mysso1' {SET ID 'alicesUniqueMySso1Id'} +SET AUTH 'oidc-mysso' {SET ID 'alicesUniqueMySsoId'} ---- -This will create a user who can authenticate and authorize using `ldap` or `oidc-mysso`. See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for more information on setting up an OIDC provider. +This will create a user who can authenticate and authorize using `ldap` or `mysso`. See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for more information on setting up an OIDC provider. This example also illustrates that the user can have their home database set even when using only external auth providers. ====== diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 3fd66dba0..795e6f421 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -671,7 +671,7 @@ SET PASSWORD 'abcd1234' CHANGE REQUIRED SET STATUS SUSPENDED SET HOME DATABASE anotherDb ---- - +[role=label--new-5.24] The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: [source,cypher,role=noplay] diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index d19a8e8fd..732e78e4f 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -267,13 +267,13 @@ You need to set the `dbms.security.require_local_user` configuration setting to The following examples show how you can use Cypher to do this. -.Create a user with an Auth Provider who can authenticate and authorize using `oidc-mysso`. +.Create a user with an Auth Provider who can authenticate and authorize using `mysso`. ====== ---- CREATE USER jake -SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySso1Id'} // the id must match the claim that you configured via dbms.security.oidc.mysso.claims.username +SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySsoId'} // the id must match the claim that you configured via dbms.security.oidc.mysso.claims.username ---- -This will create a user who can authenticate and authorize using `mysso` if they present a valid token with a `sub` claim of `jakesUniqueMySso1Id`. +This will create a user who can authenticate and authorize using `mysso` if they present a valid token with a `sub` claim of `jakesUniqueMySsoId`. The claim used for authentication is determined by the xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] config setting (default the default is the `sub` claim). When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. @@ -289,10 +289,10 @@ Conversely, when `internal.dbms.security.require_local_user` is set to `true`, u ---- CREATE USER jake SET HOME DATABASE anotherDb -SET AUTH 'oidc-mysso1' {SET ID 'jakesUniqueMySso1Id'} // this must match the claim that you configured via dbms.security.oidc.mysso1.claims.username -SET AUTH 'oidc-mysso2' {SET ID 'jakesUniqueMySso2Id'} // this must match the claim that you configured via dbms.security.oidc.mysso2.claims.username +SET AUTH 'oidc-mysso1' {SET ID 'jakesUniqueMySso1Id'} // `jakesUniqueMySso1Id` must match the value of the claim that you configured via dbms.security.oidc.mysso1.claims.username +SET AUTH 'oidc-mysso2' {SET ID 'jakesUniqueMySso2Id'} // `jakesUniqueMySso2Id` must match the value of the claim that you configured via dbms.security.oidc.mysso2.claims.username ---- -This will create a user who can authenticate and authorize using `oidc-mysso1` or `oidc-mysso2`. +This will create a user who can authenticate and authorize using `mysso1` or `mysso2`. This example also illustrates that the user can have their home database set even when using only external auth providers. ====== @@ -303,7 +303,7 @@ This example also illustrates that the user can have their home database set eve ALTER USER jake REMOVE AUTH 'oidc-mysso2' ---- -This will prevent the user from being able to authenticate and authorize with the `oidc-mysso2` provider. +This will prevent the user from being able to authenticate and authorize with the `mysso2` provider. ====== .Alter a user to allow them to authenticate and authorize using username and password @@ -316,7 +316,7 @@ This will allow the user to authenticate and authorize using the specified usern ====== -.Configure the database to allow authentication via `oidc-mysso` and authorization via the `native` provider. +.Configure the database to allow authentication via `mysso` and authorization via the `native` provider. ====== Set the following database config: @@ -326,20 +326,20 @@ dbms.security.authentication_providers=oidc-mysso dbms.security.authorization_providers=native ---- -Then create a user with a `oidc-mysso` Auth Provider: +Then create a user with a `mysso` Auth Provider: ---- CREATE USER jake SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySsoId'} // this must match the claim that you configured via dbms.security.oidc.mysso.claims.username ---- -Then natively grant the `ANALYST` role to the user: +Then natively grant the `READER` role to the user: ---- -GRANT ROLE ANALYST TO alice +GRANT ROLE READER TO alice ---- -This will allow the user to authenticate using `oidc-mysso` and receive the `ANALYST` role from the `native` provider. +This will allow the user to authenticate using `mysso` and receive the `READER` role from the `native` provider. -It would also be possible to give the user the union of roles from `oidc-mysso` *and* `native` by setting `oidc-mysso` as an authorization provider too: +It would also be possible to give the user the union of roles from `mysso` *and* `native` by setting `mysso` as an authorization provider too: ---- dbms.security.authentication_providers=oidc-mysso From 16c330d9d999fea62a92f3ba362dc74d0a00a942 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Wed, 4 Sep 2024 16:18:47 +0100 Subject: [PATCH 16/62] pr review comments --- .../authentication-authorization/ldap-integration.adoc | 6 +++--- .../authentication-authorization/sso-integration.adoc | 2 +- .../ROOT/pages/tutorial/tutorial-sso-configuration.adoc | 8 ++++---- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index 710700eac..f0277900a 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -434,12 +434,12 @@ CREATE USER alice SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } ---- -Then natively grant the `ANALYST` role to the user: +Then natively grant the `READER` role to the user: ---- -GRANT ROLE ANALYST TO alice +GRANT ROLE READER TO alice ---- -This will allow the user to authenticate using `ldap` and receive the `ANALYST` role from the `native` provider. +This will allow the user to authenticate using `ldap` and receive the `READER` role from the `native` provider. It would also be possible to give the user the union of roles from `ldap` *and* `native` roles by setting `ldap` as an authorization provider too: diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index 732e78e4f..aff7b8888 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -329,7 +329,7 @@ dbms.security.authorization_providers=native Then create a user with a `mysso` Auth Provider: ---- CREATE USER jake -SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySsoId'} // this must match the claim that you configured via dbms.security.oidc.mysso.claims.username +SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySsoId'} // `jakesUniqueMySsoId` must match the value of the claim that you configured via dbms.security.oidc.mysso.claims.username ---- Then natively grant the `READER` role to the user: diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index a7203bab0..c0639d3f2 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -142,7 +142,7 @@ For example to create a user `jake` who can authenticate using native or Okta, a ---- CREATE USER jake SET HOME DATABASE 'jakesHomeDb' -SET AUTH 'oidc-okta' {SET ID 'jakesUniqueOktaUserId'} // this must match the claim that you configured via dbms.security.oidc.okta.claims.username +SET AUTH 'oidc-okta' {SET ID 'jakesUniqueOktaUserId'} // `jakesUniqueOktaUserId` must match the value of the claim that you configured via dbms.security.oidc.okta.claims.username SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED} ---- @@ -334,7 +334,7 @@ For example to create a user `jake` who can authenticate and authorize using Ent ---- CREATE USER jake SET HOME DATABASE 'jakesHomeDb' -SET AUTH 'oidc-okta' {SET ID 'jakesUniqueEntraUserId'} // this must match the claim that you configured via dbms.security.oidc.azure.claims.username +SET AUTH 'oidc-okta' {SET ID 'jakesUniqueEntraUserId'} // `jakesUniqueEntraUserId` must match the value of the claim that you configured via dbms.security.oidc.azure.claims.username ---- See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for further examples. @@ -401,7 +401,7 @@ dbms.security.require_local_user=true ---- CREATE USER jake SET HOME DATABASE 'jakesHomeDb' -SET AUTH 'oidc-google' {SET ID 'jakesUniqueGoogleUserId'} // this must match the claim that you configured via dbms.security.oidc.google.claims.username +SET AUTH 'oidc-google' {SET ID 'jakesUniqueGoogleUserId'} // `jakesUniqueGoogleUserId` must match the value of the claim that you configured via dbms.security.oidc.google.claims.username ---- .. Grant the user roles using native authorization. @@ -453,7 +453,7 @@ dbms.security.authentication_providers=oidc-google [source, cypher, role=noplay] ---- -CREATE USER jakesUniqueGoogleUserId // this must match the claim that you configured via dbms.security.oidc.google.claims.username +CREATE USER jakesUniqueGoogleUserId // `jakesUniqueGoogleUserId` must match the value of the claim that you configured via dbms.security.oidc.google.claims.username SET HOME DATABASE 'jakesHomeDb' SET PASSWORD 'secretpassword' SET PASSWORD CHANGE NOT REQUIRED From 303608bf192a75b27dcd11ba5bf1eb7f849348ff Mon Sep 17 00:00:00 2001 From: Phil Wright <95368282+phil198@users.noreply.github.com> Date: Wed, 4 Sep 2024 16:33:11 +0100 Subject: [PATCH 17/62] Apply suggestions from code review Co-authored-by: Therese Magnusson --- .../pages/authentication-authorization/ldap-integration.adoc | 2 +- .../ROOT/pages/authentication-authorization/manage-users.adoc | 3 ++- .../pages/authentication-authorization/sso-integration.adoc | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index f0277900a..8da06d6ff 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -383,7 +383,7 @@ When the `dbms.security.require_local_user` configuration setting is set to `tru If there is no matching Auth Provider, the user will not be able to authenticate or authorize. This applies to all providers. -Conversely, when `internal.dbms.security.require_local_user` is set to `true`, users' Auth Providers will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. +Conversely, when `dbms.security.require_local_user` is set to `false`, users' Auth Providers will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. ====== diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 795e6f421..5e69d0a2f 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -858,7 +858,8 @@ The `SET PASSWORD` part is only optional if it directly follows the `SET PASSWOR A home database will be resolved if it is either pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for the user. [role=label--new-5.24] -* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[Auth Providers], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. +* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[Auth Providers], which define authentication / authorization providers for the user. +This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. ** xref:authentication-authorization/manage-users.adoc#access-control-create-users[Native Auth Provider Examples] ** xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO Auth Provider Examples] ** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[LDAP Auth Provider Examples] diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index aff7b8888..a2b7f40c6 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -280,7 +280,7 @@ When the `dbms.security.require_local_user` configuration setting is set to `tru If there is no matching Auth Provider, the user will not be able to authenticate or authorize. This applies to all providers. -Conversely, when `internal.dbms.security.require_local_user` is set to `true`, users' Auth Providers will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. +Conversely, when `dbms.security.require_local_user` is set to `false`, users' Auth Providers will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. ====== From 3bb38ccf74ae74e582b38a12e795d93ea5a4aa57 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Fri, 6 Sep 2024 15:57:42 +0100 Subject: [PATCH 18/62] pr review comments --- .../auth-providers.adoc | 6 ++++- .../authentication-authorization/index.adoc | 2 +- .../manage-users.adoc | 22 +++++++++--------- .../tutorial/tutorial-sso-configuration.adoc | 23 ++++++++++--------- 4 files changed, 29 insertions(+), 24 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 909b99745..413dd51f2 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -9,7 +9,11 @@ Authentication and authorization can be controlled on a user-level using Cypher In order to make use of Auth Providers, you need to set the `dbms.security.require_local_user` configuration setting to `true`. This setting mandates that only users with a corresponding Auth Provider in the database can authenticate and authorize. -Auth Providers give you a way to link externally-defined users (e.g. in a 3rd party ID provider like OIDC or LDAP) to the Neo4j internal User model. The internal model can define things such as 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). +Auth Providers give you a way to link externally-defined users (e.g. in a 3rd party ID provider like OIDC or LDAP) to the Neo4j internal User model. + +The internal model can define things such as 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 . Provisioning different auth providers (including native username/password auth) for different users. diff --git a/modules/ROOT/pages/authentication-authorization/index.adoc b/modules/ROOT/pages/authentication-authorization/index.adoc index 1b8c70aa7..8350a43bd 100644 --- a/modules/ROOT/pages/authentication-authorization/index.adoc +++ b/modules/ROOT/pages/authentication-authorization/index.adoc @@ -94,7 +94,7 @@ This is in contrast to a suspended user. This is a user who has been assigned the admin role. [[term-auth-provider]]Auth Provider:: -A map attached to a database user which defines which authentication and authorization config to use for that user. +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, diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 5e69d0a2f..e46a56d64 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -160,8 +160,8 @@ CREATE USER name [IF NOT EXISTS] SET AUTH [PROVIDER] 'provider' "{" { SET ID 'id' // a unique identifier of the user in an external system - \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' - \| SET PASSWORD CHANGE [NOT] REQUIRED + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider + \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider } "}" ---- @@ -210,8 +210,8 @@ CREATE OR REPLACE USER name SET AUTH [PROVIDER] 'provider' "{" { SET ID 'id' // a unique identifier of the user in an external system - \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' - \| SET PASSWORD CHANGE [NOT] REQUIRED + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider + \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider } "}" ---- @@ -297,8 +297,8 @@ ALTER USER name [IF EXISTS] SET AUTH [PROVIDER] 'provider' "{" { SET ID 'id' // a unique identifier of the user in an external system - \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' - \| SET PASSWORD CHANGE [NOT] REQUIRED + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider + \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider } "}" ---- @@ -551,7 +551,7 @@ SHOW USERS |=== When first starting a Neo4j DBMS, there is always a single default user `neo4j` with administrative privileges. -It is possible to set the initial password using xref:configuration/set-initial-password[`neo4j-admin dbms set-initial-password `], otherwise it is necessary to change the password after the first login. +It is possible to set the initial password using xref:configuration/set-initial-password.adoc[`neo4j-admin dbms set-initial-password `], otherwise it is necessary to change the password after the first login. .Show user ====== @@ -620,8 +620,8 @@ For both `CREATE` and `CREATE OR REPLACE`, `` pairs for the `SET AUT SET AUTH [PROVIDER] 'provider' "{" { SET ID 'id' // a unique identifier of the user in an external system - \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' - \| SET PASSWORD CHANGE [NOT] REQUIRED + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider + \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider } "}" ---- @@ -829,8 +829,8 @@ ALTER USER name [IF EXISTS] SET AUTH [PROVIDER] 'provider' "{" { SET ID 'id' // a unique identifier of the user in an external system - \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' - \| SET PASSWORD CHANGE [NOT] REQUIRED + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider + \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider } "}" ---- diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index c0639d3f2..c27089959 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -334,7 +334,7 @@ For example to create a user `jake` who can authenticate and authorize using Ent ---- CREATE USER jake SET HOME DATABASE 'jakesHomeDb' -SET AUTH 'oidc-okta' {SET ID 'jakesUniqueEntraUserId'} // `jakesUniqueEntraUserId` must match the value of the claim that you configured via dbms.security.oidc.azure.claims.username +SET AUTH 'oidc-azure' {SET ID 'jakesUniqueAzureUserId'} // `jakesUniqueAzureUserId` must match the value of the claim that you configured via dbms.security.oidc.azure.claims.username ---- See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for further examples. @@ -375,9 +375,14 @@ dbms.security.oidc.google.config=token_type_principal=id_token;token_type_authen There are then two ways to create the user in the database (which is required to give the users roles from native authorization): -. Using Auth Providers -xref:authentication-authorization/auth-providers.adoc[Auth Providers] allow us to specify auth providers at the user-level which is useful in this scenario. -This approach allows us to have an `admin` user who can authenticate natively, and can then create less privileged users who may only authenticate using `oidc-google` and will receive the roles granted to them using `native` authorization. +. Using Auth Providers. +xref:authentication-authorization/auth-providers.adoc[Auth Providers] allow us to specify authentication and authorization providers at the user-level which is useful in this scenario. +This approach relies on the existence of an `admin` user who can authenticate natively, and can themselves create less privileged users who may only authenticate using `oidc-google` and who will receive the roles granted to them using `native` authorization. + +[NOTE] +==== +An admin user with the name `neo4j` is created by default when the database is xref:configuration/set-initial-password.adoc[first started]. +==== .. Change the configuration to allow `native` authentication (for use only by the `admin` user): @@ -387,7 +392,7 @@ dbms.security.authentication_providers=oidc-google, native ---- .. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file. -This will switch to User Auth Providers mode whereby users can only authenticate and authorize if they have a corresponding Auth Provider in the database. +This will switch to __User Auth Providers__ mode whereby users can only authenticate and authorize if they have a corresponding Auth Provider in the database. [source, properties] ---- @@ -411,9 +416,9 @@ SET AUTH 'oidc-google' {SET ID 'jakesUniqueGoogleUserId'} // `jakesUniqueGoogleU GRANT ROLE reader TO jake ---- -The user will implicitly receive `native` authorization because `native` is in the list of authorization providers and you have explicitly granted the user a `ROLE`. +The user will implicitly receive `native` authorization because `native` is in the list of authorization providers and you have explicitly granted the user a role. -You can now disable native authentication for the database completely: +Once you have set up your users in this way, you can now disable native authentication for the database completely: [source, properties] ---- @@ -466,10 +471,6 @@ REQUIRED GRANT ROLE reader TO jakesUniqueGoogleUserId ---- - - - - == FAQ === When should `pkce` be used as auth flow? From c7bf5e3de590dcd90e64a812ca6b43481c6ac8c7 Mon Sep 17 00:00:00 2001 From: Phil Wright <95368282+phil198@users.noreply.github.com> Date: Mon, 9 Sep 2024 13:45:16 +0100 Subject: [PATCH 19/62] Apply suggestions from code review Co-authored-by: Therese Magnusson --- .../auth-providers.adoc | 2 -- .../authentication-authorization/manage-users.adoc | 14 ++++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 413dd51f2..683699be9 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -10,9 +10,7 @@ In order to make use of Auth Providers, you need to set the `dbms.security.requi This setting mandates that only users with a corresponding Auth Provider in the database can authenticate and authorize. Auth Providers give you a way to link externally-defined users (e.g. in a 3rd party ID provider like OIDC or LDAP) to the Neo4j internal User model. - The internal model can define things such as 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 diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index e46a56d64..d86c2afd1 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -151,7 +151,7 @@ CREATE USER name [IF NOT EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] - {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... ---- `` pairs for the `SET AUTH` clause could include: @@ -166,7 +166,6 @@ SET AUTH [PROVIDER] 'provider' "{" "}" ---- - | Description a| Creates a new user. @@ -175,6 +174,7 @@ Creates a new user. ==== It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Provider. ==== + For more information, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. | Required privilege @@ -202,7 +202,7 @@ CREATE OR REPLACE USER name [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] - {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... ---- `` pairs for the `SET AUTH` clause could include: [source, syntax, role="noheader"] @@ -219,10 +219,12 @@ SET AUTH [PROVIDER] 'provider' "{" | Description a| Creates a new user, or if a user with the same name exists, replace it. + [NOTE] ==== It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Provider. ==== + For more information, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. | Required privilege @@ -598,7 +600,7 @@ CREATE USER name [IF NOT EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] - {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... ---- Users can be created or replaced using `CREATE OR REPLACE USER`. @@ -610,7 +612,7 @@ CREATE OR REPLACE USER name [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] - {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... ---- For both `CREATE` and `CREATE OR REPLACE`, `` pairs for the `SET AUTH` clause could include: @@ -819,7 +821,7 @@ ALTER USER name [IF EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE | SUSPENDED}] [SET HOME DATABASE name] - {[SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]}... + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... [REMOVE HOME DATABASE] [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }]... ---- From 44d473eb123d2dcb21331136c92741cfceff8d5d Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Mon, 9 Sep 2024 14:53:57 +0100 Subject: [PATCH 20/62] pr review comments --- .../manage-users.adoc | 16 ++++++---------- .../tutorial/tutorial-sso-configuration.adoc | 4 ++-- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index d86c2afd1..e8043273e 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -309,7 +309,6 @@ SET AUTH [PROVIDER] 'provider' "{" a| Modifies the settings for an existing user. At least one `SET` or `REMOVE` clause is required. -`SET` and `REMOVE` clauses cannot be combined in the same command. For more information, see xref:authentication-authorization/manage-users.adoc#access-control-alter-users[Modifying users]. @@ -641,16 +640,16 @@ With `ENCRYPTED`, the password string is expected to be in the format of ` Date: Mon, 9 Sep 2024 15:38:32 +0100 Subject: [PATCH 21/62] pr review comments --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index e8043273e..02b983a03 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -649,7 +649,7 @@ If no home database is set, the DBMS default database is used as the home databa * One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[Auth Providers], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. Examples can be found below for `native`, xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[here] for OIDC and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[here] for LDAP. * It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Provider. -* The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, `SET AUTH`, and `SET HOME DATABASE` clauses can be applied in any order. +* The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, `SET AUTH`, and `SET HOME DATABASE` clauses can be applied in any order, as can their `REMOVE` counterparts where applicable. However, all `REMOVE` clauses must come before the first `SET` clause. [NOTE] ==== @@ -865,7 +865,7 @@ This results in the DBMS default database being used as the home database for th [role=label--new-5.24] * `REMOVE AUTH` is used to remove one or many xref:authentication-authorization/auth-providers.adoc[Auth Provider(s)] from a user. It cannot be used in a way that would mean a user has no Auth Providers. * `REMOVE ALL AUTH` is used to remove all existing xref:authentication-authorization/auth-providers.adoc[Auth Providers] from a user. It must be used in conjunction with at least one `SET AUTH` clause in order to meet the requirement that a user always has at least one auth provider. -* The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, `SET AUTH`, and `SET HOME DATABASE` clauses can be applied in any order. +* The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, `SET AUTH`, and `SET HOME DATABASE` clauses can be applied in any order, as can their `REMOVE` counterparts where applicable. However, all `REMOVE` clauses must come before the first `SET` clause. .Modify the user `bob` with a new password and active status, and remove the requirement to change his password: From a2e27f3b81f64bdb037e856c5243f87201e7d517 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Mon, 9 Sep 2024 15:58:21 +0100 Subject: [PATCH 22/62] document and link to the `require_local_user` setting --- .../auth-providers.adoc | 4 ++-- .../ldap-integration.adoc | 4 ++-- .../sso-integration.adoc | 6 +++--- .../configuration/configuration-settings.adoc | 15 +++++++++++++++ .../tutorial/tutorial-sso-configuration.adoc | 8 ++++---- 5 files changed, 26 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 683699be9..2cca04176 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -6,7 +6,7 @@ Authentication and authorization can be controlled on a user-level using Cypher by setting Auth Providers on users. -In order to make use of Auth Providers, you need to set the `dbms.security.require_local_user` configuration setting to `true`. +In order to make use of 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 only users with a corresponding Auth Provider in the database can authenticate and authorize. Auth Providers give you a way to link externally-defined users (e.g. in a 3rd party ID provider like OIDC or LDAP) to the Neo4j internal User model. @@ -32,7 +32,7 @@ The way that the matching lookup is done depends on the type of provider. For ex - For the `native` (username/password) provider, the supplied username itself is used to look up the Auth Provider. == Enabling User Auth Providers mode -When the configuration setting `dbms.security.require_local_user` is set to `true`, the lookups described above will be performed when the user authenticates, and a matching user Auth Provider *must* exist in order for a user to be able to successfully authenticate and authorize. +When the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting is set to `true`, the lookups described above will be performed when the user authenticates, and a matching user Auth Provider *must* exist in order for a user to be able to successfully authenticate and authorize. == Examples For examples of how to use Auth Providers with different authentication providers, see the following sections: diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index 8da06d6ff..67cd2b1df 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -379,11 +379,11 @@ SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } ---- This will create a user who can authenticate and authorize using LDAP provided their LDAP `dn` is `cn=alice,ou=engineering,dc=example,dc=com`. -When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. +When the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. If there is no matching Auth Provider, the user will not be able to authenticate or authorize. This applies to all providers. -Conversely, when `dbms.security.require_local_user` is set to `false`, users' Auth Providers will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. +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 will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. ====== diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index a2b7f40c6..c3bb02d5b 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -261,7 +261,7 @@ xref:authentication-authorization/auth-providers.adoc[Auth Providers] can be use [NOTE] ==== -You need to set the `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. +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` 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. ==== The following examples show how you can use Cypher to do this. @@ -276,11 +276,11 @@ SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySsoId'} // the id must match the cla This will create a user who can authenticate and authorize using `mysso` if they present a valid token with a `sub` claim of `jakesUniqueMySsoId`. The claim used for authentication is determined by the xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] config setting (default the default is the `sub` claim). -When the `dbms.security.require_local_user` configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. +When the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. If there is no matching Auth Provider, the user will not be able to authenticate or authorize. This applies to all providers. -Conversely, when `dbms.security.require_local_user` is set to `false`, users' Auth Providers will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. +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 will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. ====== diff --git a/modules/ROOT/pages/configuration/configuration-settings.adoc b/modules/ROOT/pages/configuration/configuration-settings.adoc index dd35db08f..4bf979327 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -4615,6 +4615,21 @@ m|++++++ |=== +[[config_dbms.security.require_local_user]] +=== `dbms.security.require_local_user` + +.dbms.security.require_local_user +[frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] +|=== +|Description +a|When set to `true`, users can *only* authenticate when there is a user in the database with an xref:authentication-authorization/auth-providers.adoc[Auth Provider] which links to the provider that the user is trying to authenticate with. If there is no matching xref:authentication-authorization/auth-providers.adoc[Auth Provider], the user will not be able to authenticate or authorize. This applies to all providers. Conversely, when set to `false`, users' xref:authentication-authorization/auth-providers.adoc[Auth Providers] will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. +|Valid values +a|A boolean. +|Default value +m|+++true+++ +|=== + + [[config_dbms.netty.ssl.provider]] === `dbms.netty.ssl.provider` diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index cb5859a6e..23c3524bd 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -24,7 +24,7 @@ SSO works in the following way: . The identity provider responds with a JSON Web Token (JWT), a JSON file containing fields (claims) relative to the user (email, audience, groups, etc.). . The client provides the server with the JWT, and the server verifies its signature with the JWKs. [role=label--new-5.24] -. By setting the `dbms.security.require_local_user` configuration setting to `true`, you can control which users can authenticate and authorize by creating xref:authentication-authorization/auth-providers.adoc[Auth Providers] in the database using Cypher. +. By setting the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true`, you can control which users can authenticate and authorize by creating xref:authentication-authorization/auth-providers.adoc[Auth Providers] in the database using Cypher. In this mode, a user with a matching Auth Provider must exist in the database for the user to be able to authenticate and authorize using an SSO (or any external) provider. This allows you to do the following in the database, using Cypher: .. `SUSPEND` SSO users. @@ -136,7 +136,7 @@ image::sso-configuration-tutorials/okta-sign-on-tab.svg[title="Okta's sign-on ta + [role=label--new-5.24] . (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-providers.adoc[Auth Providers] to achieve this. -Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. +Set the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate using native or Okta, and authorize using Okta (as configured in step 3), you can use the following Cypher query: [source, cypher, role=noplay] ---- @@ -328,7 +328,7 @@ dbms.security.oidc.azure.claims.groups=roles [role=label--new-5.24] . (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-providers.adoc[Auth Providers] to achieve this. -Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file to enable this mode. +Set the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true` in the _neo4j.conf_ file to enable this mode. For example to create a user `jake` who can authenticate and authorize using Azure, you can use the following Cypher query: [source, cypher, role=noplay] ---- @@ -391,7 +391,7 @@ An admin user with the name `neo4j` is created by default when the database is x dbms.security.authentication_providers=oidc-google, native ---- -.. Set the `dbms.security.require_local_user` configuration setting to `true` in the _neo4j.conf_ file. +.. Set the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true` in the _neo4j.conf_ file. This will switch to __User Auth Providers__ mode whereby users can only authenticate and authorize if they have a corresponding Auth Provider in the database. [source, properties] From 491f9dcd1c7ca1ceeafc5283031b471f679085f7 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Mon, 9 Sep 2024 16:06:29 +0100 Subject: [PATCH 23/62] pr review comments --- .../pages/authentication-authorization/manage-users.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 02b983a03..71bb9b278 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -649,7 +649,7 @@ If no home database is set, the DBMS default database is used as the home databa * One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[Auth Providers], which define authentication / authorization providers for the user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. Examples can be found below for `native`, xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[here] for OIDC and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[here] for LDAP. * It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Provider. -* The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, `SET AUTH`, and `SET HOME DATABASE` clauses can be applied in any order, as can their `REMOVE` counterparts where applicable. However, all `REMOVE` clauses must come before the first `SET` clause. +* The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, `SET AUTH`, and `SET HOME DATABASE` clauses can be applied in any order. [NOTE] ==== @@ -712,7 +712,7 @@ SET AUTH 'native' { [NOTE, role=label--enterprise-edition] ==== -The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE` parts of the commands are only available in Neo4j Enterprise Edition. The `{SET | REMOVE} AUTH` clause for external providers is only available in Neo4j Enterprise Edition. `{SET | REMOVE} AUTH 'native'` can be used in Neo4j Community Edition. +The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE` parts of the commands are only available in Neo4j Enterprise Edition. The `SET AUTH` clause for external providers is only available in Neo4j Enterprise Edition. However, `SET AUTH 'native'` can be used in Neo4j Community Edition. ==== The `CREATE USER` command is optionally idempotent, with the default behavior to throw an exception if the user already exists. @@ -930,7 +930,7 @@ For example, leaving out the `CHANGE [NOT] REQUIRED` part of the query will leav [NOTE, role=label--enterprise-edition] ==== -The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE`, `REMOVE HOME DATABASE` parts of the command are only available in Neo4j Enterprise Edition. The `{SET | REMOVE} AUTH` clause for external providers is only available in Neo4j Enterprise Edition. `{SET | REMOVE} AUTH 'native'` can be used in Neo4j Community Edition. +The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE`, `REMOVE HOME DATABASE` parts of the command are only available in Neo4j Enterprise Edition. The `{SET | REMOVE} AUTH` clause for external providers is only available in Neo4j Enterprise Edition. However, `SET AUTH 'native'` can be used in Neo4j Community Edition. ==== The changes to the user will appear on the list provided by `SHOW USERS`: From f81fd915d131793bb17e684be63d33666f2cecd7 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Mon, 9 Sep 2024 16:09:03 +0100 Subject: [PATCH 24/62] pr review comments --- modules/ROOT/pages/configuration/configuration-settings.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/configuration/configuration-settings.adoc b/modules/ROOT/pages/configuration/configuration-settings.adoc index 4bf979327..b632272e7 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -4618,6 +4618,8 @@ m|++++++ [[config_dbms.security.require_local_user]] === `dbms.security.require_local_user` +// label:enterprise-edition[Enterprise Edition] label:new[Introduced in 5.24] + .dbms.security.require_local_user [frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] |=== @@ -4626,7 +4628,7 @@ a|When set to `true`, users can *only* authenticate when there is a user in the |Valid values a|A boolean. |Default value -m|+++true+++ +m|+++false+++ |=== From 4404e2abdfb4d0b52bb50cdda1c67ebb3129e49a Mon Sep 17 00:00:00 2001 From: Phil Wright <95368282+phil198@users.noreply.github.com> Date: Mon, 9 Sep 2024 16:22:36 +0100 Subject: [PATCH 25/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc Co-authored-by: Therese Magnusson --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 71bb9b278..29761b10d 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -930,7 +930,7 @@ For example, leaving out the `CHANGE [NOT] REQUIRED` part of the query will leav [NOTE, role=label--enterprise-edition] ==== -The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE`, `REMOVE HOME DATABASE` parts of the command are only available in Neo4j Enterprise Edition. The `{SET | REMOVE} AUTH` clause for external providers is only available in Neo4j Enterprise Edition. However, `SET AUTH 'native'` can be used in Neo4j Community Edition. +The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE`, `REMOVE HOME DATABASE`, and `REMOVE AUTH` parts of the command are only available in Neo4j Enterprise Edition. The `SET AUTH` clause for external providers is only available in Neo4j Enterprise Edition. However, `SET AUTH 'native'` can be used in Neo4j Community Edition. ==== The changes to the user will appear on the list provided by `SHOW USERS`: From e56f30c8e3e07f8b33211fae3af3a4e8efd896fa Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Mon, 9 Sep 2024 16:39:48 +0100 Subject: [PATCH 26/62] unifiying config description --- modules/ROOT/pages/configuration/configuration-settings.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/configuration/configuration-settings.adoc b/modules/ROOT/pages/configuration/configuration-settings.adoc index b632272e7..5a37e62ca 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -4624,7 +4624,7 @@ m|++++++ [frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] |=== |Description -a|When set to `true`, users can *only* authenticate when there is a user in the database with an xref:authentication-authorization/auth-providers.adoc[Auth Provider] which links to the provider that the user is trying to authenticate with. If there is no matching xref:authentication-authorization/auth-providers.adoc[Auth Provider], the user will not be able to authenticate or authorize. This applies to all providers. Conversely, when set to `false`, users' xref:authentication-authorization/auth-providers.adoc[Auth Providers] will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. +a|This controls if a local user has to be created for external authentication. "If set to the default (`false`), no user has to be created to authenticate with an external authentication provider. If set to `true`, a user representing the external user must be created before they can authenticate successfully. |Valid values a|A boolean. |Default value From 519f254f61fcf0ac43c8896d1aea2b76d97dc1d2 Mon Sep 17 00:00:00 2001 From: Phil Wright <95368282+phil198@users.noreply.github.com> Date: Tue, 10 Sep 2024 09:23:52 +0100 Subject: [PATCH 27/62] Update modules/ROOT/pages/configuration/configuration-settings.adoc Co-authored-by: Therese Magnusson --- modules/ROOT/pages/configuration/configuration-settings.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/configuration/configuration-settings.adoc b/modules/ROOT/pages/configuration/configuration-settings.adoc index 5a37e62ca..eed1dcc05 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -4624,7 +4624,7 @@ m|++++++ [frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] |=== |Description -a|This controls if a local user has to be created for external authentication. "If set to the default (`false`), no user has to be created to authenticate with an external authentication provider. If set to `true`, a user representing the external user must be created before they can authenticate successfully. +a|This controls if a local user has to be created for external authentication. If set to the default (`false`), no user has to be created to authenticate with an external authentication provider. If set to `true`, a user representing the external user must be created before they can authenticate successfully. |Valid values a|A boolean. |Default value From 701cd54d0c0d10f1d0db16acccfc5273502af9cd Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Wed, 11 Sep 2024 16:43:32 +0100 Subject: [PATCH 28/62] pr review comments --- .../pages/authentication-authorization/sso-integration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index c3bb02d5b..e83d6726a 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -334,7 +334,7 @@ SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySsoId'} // `jakesUniqueMySsoId` must Then natively grant the `READER` role to the user: ---- -GRANT ROLE READER TO alice +GRANT ROLE READER TO jake ---- This will allow the user to authenticate using `mysso` and receive the `READER` role from the `native` provider. From c0cef00a775db02a6ac4d8b0d640bc6639c4d792 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Thu, 12 Sep 2024 12:28:59 +0100 Subject: [PATCH 29/62] adding "migrating" note --- .../authentication-authorization/auth-providers.adoc | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 2cca04176..7eaf6ee67 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -34,6 +34,18 @@ The way that the matching lookup is done depends on the type of provider. For ex == Enabling User Auth Providers mode When the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting is set to `true`, the lookups described above will be performed when the user authenticates, and a matching user Auth Provider *must* exist in order for a user to be able to successfully authenticate and authorize. +== Migrating to Auth Providers mode +If you have existing users in the database and you want to migrate to Auth Providers mode, you can use the `ALTER USER ... SET AUTH` command to attach Auth Provider(s) to an existing user. Until you change `dbms.security.require_local_user` to `true`, this will have no impact on the users' ability to authenticate and authorize as they always have done. + +Once the process of adding Auth Providers to your users is completed, you can then 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 which were created using the original `CREATE USER ... SET PASSWORD` syntax, will implicitly have the native (username / password) Auth Provider, so that would not need to be added explicitly using `SET AUTH`. + +To be certain about which Auth Providers are attached to a user, you can use the xref:authentication-authorization/manage-users.adoc#access-control-list-users[`SHOW USERS WITH AUTH`] command to see the Auth Providers attached to a user. +==== + == Examples For examples of how to use Auth Providers with different authentication providers, see the following sections: From 340488f31ddbc4b8e873ffc611d30414d8d057a5 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Thu, 12 Sep 2024 17:14:14 +0100 Subject: [PATCH 30/62] adding SHOW USERS WITH AUTH description --- .../dbms-administration.adoc | 6 + .../manage-roles.adoc | 2 +- .../manage-users.adoc | 108 +++++++++++++++++- 3 files changed, 111 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc index 1b7ef3ba9..cd4ce8aa4 100644 --- a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc +++ b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc @@ -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[, ...] +| 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 diff --git a/modules/ROOT/pages/authentication-authorization/manage-roles.adoc b/modules/ROOT/pages/authentication-authorization/manage-roles.adoc index d6d48e55e..f4fcf6c18 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-roles.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-roles.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] ---- diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 29761b10d..87523638c 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -71,6 +71,7 @@ a| [source, syntax, role="noheader"] ---- SHOW USER[S] + [WITH AUTH] [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] [WHERE expression] [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] @@ -329,6 +330,11 @@ GRANT SET USER STATUS GRANT SET USER HOME DATABASE ---- +[source, privilege, role="noheader"] +---- +GRANT SET AUTH +---- + (see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) |=== @@ -479,7 +485,7 @@ This command is only supported for a logged-in user and will return an empty res [[access-control-list-users]] == Listing users -Available users can be seen using `SHOW USERS`, which will produce a table of users with the following columns: +Available users can be seen using `SHOW USERS`, which will produce a table containing a single row per user with the following columns: [options="header", width="100%", cols="2a,4,2m,^.^,^.^"] |=== @@ -496,7 +502,11 @@ Available users can be seen using `SHOW USERS`, which will produce a table of us | {check-mark} | roles -| Roles granted to the user. +| Native roles granted to the user using the `GRANT ROLE` command. + +This is not necessarily the set of roles that a user will receive in practice. The latter depends on DMBS configuration as well as the user's xref:authentication-authorization/auth-providers.adoc[Auth Providers]. + +Examples of where a user would receive a different set of roles from that which appears in this column would include cases where they use external (e.g. LDAP or OIDC) auth, or where they do not have the `native` xref:authentication-authorization/auth-providers.adoc[Auth Provider]. Will return `null` in community edition. | LIST OF STRING @@ -504,7 +514,7 @@ Will return `null` in community edition. | {check-mark} | passwordChangeRequired -| If `true`, the user must change their password at the next login. +| If `true`, the user must change their password at the next login. This will be null if the user has `native` auth disabled. | BOOLEAN | {check-mark} | {check-mark} @@ -528,6 +538,7 @@ Will return `null` in community edition. | {check-mark} |=== + [source, cypher, role=noplay] ---- SHOW USERS @@ -547,12 +558,91 @@ SHOW USERS |false |false | +|"jake" +|["PUBLIC"] +|false +|false +| +5+a|Rows: 2 +|=== -5+a|Rows: 1 +To inspect users' xref:authentication-authorization/auth-providers.adoc[Auth Providers], use `SHOW USERS WITH AUTH`. This command will produce a row per user per Auth Provider and will yield the following two columns in addition to those output by `SHOW USERS`: + +[options="header", width="100%", cols="2a,4,2m,^.^,^.^"] +|=== +| Column +| Description +| Type +| Community Edition +| Enterprise Edition + +| provider +| The name of the auth provider. +| STRING +| {check-mark} +| {check-mark} + +| auth +| A map containing configuration for the user. E.g. dn of the user for an `ldap` auth provider, the unique external identifier for an `oidc` auth provider, or password status for a native auth provider. + +| MAP +| {check-mark} +| {check-mark} +|=== + + +[source, cypher, role=noplay] +---- +SHOW USERS WITH AUTH +---- + +.Result +[role="queryresult" options="header,footer", width="100%", cols="2m,3m,3m,2m,2m,3m,4m"] +|=== +|user +|roles +|passwordChangeRequired +|suspended +|home +|provider +|auth +|"neo4j" +|["admin","PUBLIC"] +|false +|false +| +|"native" +|{ +"password": "***", +"changeRequired": false +} +|"jack" +|["PUBLIC"] +|false +|false +| +|"native" +|{ +"password": "***", +"changeRequired": false +} +|"jack" +|["PUBLIC"] +|false +|false +| +|"oidc1" +|{ +"id": "jacksIdForOidc1" +} +7+a|Rows: 1 |=== +[NOTE] +==== When first starting a Neo4j DBMS, there is always a single default user `neo4j` with administrative privileges. It is possible to set the initial password using xref:configuration/set-initial-password.adoc[`neo4j-admin dbms set-initial-password `], otherwise it is necessary to change the password after the first login. +==== .Show user ====== @@ -581,6 +671,16 @@ RETURN user AS adminUser ---- ====== +.Show user with auth +====== +Show all of the users with the `oidc` Auth Provider. +[source,cypher,role=noplay] +---- +SHOW USERS WITH AUTH +WHERE provider = 'oidc1' +---- +====== + [NOTE] ==== The `SHOW USER name PRIVILEGES` command is described in xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. From 6f266a210c8e283f3bffb1e6c5dc6ddb05a7c38b Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Fri, 13 Sep 2024 10:39:02 +0100 Subject: [PATCH 31/62] pr review comments --- .../manage-users.adoc | 126 +++++++++++++----- 1 file changed, 90 insertions(+), 36 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 87523638c..52655aec8 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -506,7 +506,7 @@ Available users can be seen using `SHOW USERS`, which will produce a table conta This is not necessarily the set of roles that a user will receive in practice. The latter depends on DMBS configuration as well as the user's xref:authentication-authorization/auth-providers.adoc[Auth Providers]. -Examples of where a user would receive a different set of roles from that which appears in this column would include cases where they use external (e.g. LDAP or OIDC) auth, or where they do not have the `native` xref:authentication-authorization/auth-providers.adoc[Auth Provider]. +Examples of where a user would receive a different set of roles from that which appears in this column would include where they use external (e.g. LDAP or OIDC) auth, or where `native` is not listed in the xref:configuration/configuration-settings.adoc#config_dbms.security.authorization_providers[`dbms.security.authorization_providers`] configuration setting. Will return `null` in community edition. | LIST OF STRING @@ -538,7 +538,14 @@ Will return `null` in community edition. | {check-mark} |=== +[NOTE] +==== +When first starting a Neo4j DBMS, there is always a single default user `neo4j` with administrative privileges. +It is possible to set the initial password using xref:configuration/set-initial-password.adoc[`neo4j-admin dbms set-initial-password `], otherwise it is necessary to change the password after the first login. +==== +.Show users +====== [source, cypher, role=noplay] ---- SHOW USERS @@ -565,6 +572,61 @@ SHOW USERS | 5+a|Rows: 2 |=== +====== + +.Show user with column reorder and filtering +====== +This example shows how to: + +* Reorder the columns using a `YIELD` clause. +* Filter the results using a `WHERE` clause. + +[source, cypher, role=noplay] +---- +SHOW USER YIELD user, suspended, passwordChangeRequired, roles, home +WHERE user = 'jake' +---- + +.Result +[role="queryresult" options="header,footer", width="100%", cols="2m,3m,3m,2m,2m"] +|=== +|user +|suspended +|passwordChangeRequired +|roles +|home +|"jake" +|false +|false +|["PUBLIC"] +| +5+a|Rows: 1 +|=== + +====== + +.Show user with return clause +====== +It is possible to add a `RETURN` clause to further manipulate the results after filtering. +In this example, the `RETURN` clause is used to filter out the `roles` column and rename the `user` column to `adminUser`. + +[source,cypher,role=noplay] +---- +SHOW USERS YIELD roles, user +WHERE 'admin' IN roles +RETURN user AS adminUser +---- +.Result +[role="queryresult" options="header,footer", width="100%", cols="2m"] +|=== +|adminUser +|"neo4j" +1+a|Rows: 1 +|=== +====== + +[[access-control-list-user-auth-providers]] +=== Listing User Auth Providers To inspect users' xref:authentication-authorization/auth-providers.adoc[Auth Providers], use `SHOW USERS WITH AUTH`. This command will produce a row per user per Auth Provider and will yield the following two columns in addition to those output by `SHOW USERS`: @@ -590,7 +652,8 @@ To inspect users' xref:authentication-authorization/auth-providers.adoc[Auth Pro | {check-mark} |=== - +.Show users with auth +====== [source, cypher, role=noplay] ---- SHOW USERS WITH AUTH @@ -635,43 +698,11 @@ SHOW USERS WITH AUTH |{ "id": "jacksIdForOidc1" } -7+a|Rows: 1 +7+a|Rows: 3 |=== - -[NOTE] -==== -When first starting a Neo4j DBMS, there is always a single default user `neo4j` with administrative privileges. -It is possible to set the initial password using xref:configuration/set-initial-password.adoc[`neo4j-admin dbms set-initial-password `], otherwise it is necessary to change the password after the first login. -==== - -.Show user -====== -This example shows how to: - -* Reorder the columns using a `YIELD` clause. -* Filter the results using a `WHERE` clause. - -[source, cypher, role=noplay] ----- -SHOW USER YIELD user, suspended, passwordChangeRequired, roles, home -WHERE user = 'jake' ----- ====== -.Show user -====== -It is possible to add a `RETURN` clause to further manipulate the results after filtering. -In this example, the `RETURN` clause is used to filter out the `roles` column and rename the `user` column to `adminUser`. - -[source,cypher,role=noplay] ----- -SHOW USERS YIELD roles, user -WHERE 'admin' IN roles -RETURN user AS adminUser ----- -====== - -.Show user with auth +.Show user with auth using filtering ====== Show all of the users with the `oidc` Auth Provider. [source,cypher,role=noplay] @@ -679,6 +710,29 @@ Show all of the users with the `oidc` Auth Provider. SHOW USERS WITH AUTH WHERE provider = 'oidc1' ---- + +.Result +[role="queryresult" options="header,footer", width="100%", cols="2m,3m,3m,2m,2m,3m,4m"] +|=== +|user +|roles +|passwordChangeRequired +|suspended +|home +|provider +|auth +|"jack" +|["PUBLIC"] +|false +|false +| +|"oidc1" +|{ +"id": "jacksIdForOidc1" +} +7+a|Rows: 1 +|=== + ====== [NOTE] From 3fde3c226c645d335fb40c534a9a4bdebe4dbb76 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Fri, 13 Sep 2024 11:19:07 +0100 Subject: [PATCH 32/62] updating privilege svgs --- ...ivileges_grant_and_deny_syntax_dbms_privileges.svg | 10 +--------- modules/ROOT/images/privileges_hierarchy_dbms.svg | 11 +---------- 2 files changed, 2 insertions(+), 19 deletions(-) diff --git a/modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.svg b/modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.svg index f713d5d6f..9c2b8ab2b 100644 --- a/modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.svg +++ b/modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.svg @@ -1,9 +1 @@ - - - - - - - - - + \ No newline at end of file diff --git a/modules/ROOT/images/privileges_hierarchy_dbms.svg b/modules/ROOT/images/privileges_hierarchy_dbms.svg index 025c39d36..49f5f22f0 100644 --- a/modules/ROOT/images/privileges_hierarchy_dbms.svg +++ b/modules/ROOT/images/privileges_hierarchy_dbms.svg @@ -1,10 +1 @@ - - - - - - - - - - + \ No newline at end of file From a30d8a6da21dd55abfb46a6cee781bd376bc3bbf Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Fri, 13 Sep 2024 12:04:21 +0100 Subject: [PATCH 33/62] updating privilege svg width adding stuff about `SET AUTH` privileges --- .../dbms-administration.adoc | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc index cd4ce8aa4..52ce1b14d 100644 --- a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc +++ b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc @@ -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: @@ -577,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] ---- @@ -615,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 ---- +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' { SET id 'jakesUniqueOktaUserId' } +---- + + The ability to modify the account status of users can be granted via the `SET USER STATUS` privilege. See an example: @@ -685,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. From d461462b1950d22039a90ad621df8efebe186a63 Mon Sep 17 00:00:00 2001 From: Phil Wright <95368282+phil198@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:18:01 +0100 Subject: [PATCH 34/62] Apply suggestions from code review Co-authored-by: Therese Magnusson --- .../pages/authentication-authorization/dbms-administration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc index 52ce1b14d..4ed06b122 100644 --- a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc +++ b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc @@ -619,7 +619,7 @@ A user that is granted the `SET AUTH` privilege is allowed to run the `ALTER USE [source, cypher, role=noplay] ---- -ALTER USER jake REMOVE AUTH 'native SET AUTH 'oidc' { SET id 'jakesUniqueOktaUserId' } +ALTER USER jake REMOVE AUTH 'native SET AUTH 'oidc-okta' { SET id 'jakesUniqueOktaUserId' } ---- From c087c8c138bef6f62947a90928da1422b55cb0c4 Mon Sep 17 00:00:00 2001 From: Phil Wright <95368282+phil198@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:21:13 +0100 Subject: [PATCH 35/62] Apply suggestions from code review Co-authored-by: Therese Magnusson --- .../manage-users.adoc | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 52655aec8..0237b9b90 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -800,10 +800,11 @@ With `ENCRYPTED`, the password string is expected to be in the format of ` Date: Mon, 16 Sep 2024 11:18:16 +0100 Subject: [PATCH 36/62] pr review comments --- .../pages/authentication-authorization/dbms-administration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc index 4ed06b122..e8d677719 100644 --- a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc +++ b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc @@ -470,7 +470,7 @@ GRANT [IMMUTABLE] SET PASSWORD[S] GRANT [IMMUTABLE] SET AUTH ON DBMS TO role[, ...] -| Enables the specified roles to SET or REMOVE users' xref:authentication-authorization/auth-providers.adoc[Auth Providers]. +| 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 From 89636eae08b04b3c3e7efa090fe23584bed1f6a3 Mon Sep 17 00:00:00 2001 From: philipwright <95368282+phil198@users.noreply.github.com> Date: Mon, 16 Sep 2024 11:52:44 +0100 Subject: [PATCH 37/62] pr review comments --- .../manage-users.adoc | 45 +++++++++++++++---- 1 file changed, 37 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 0237b9b90..5c3d7e95e 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -286,13 +286,13 @@ a| [source, syntax, role="noheader"] ---- ALTER USER name [IF EXISTS] + [REMOVE HOME DATABASE] + [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }]... [SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED} ] [SET HOME DATABASE name] [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... - [REMOVE HOME DATABASE] - [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }]... ---- `` pairs for the `SET AUTH` clause could include: [source, syntax, role="noheader"] @@ -309,7 +309,10 @@ SET AUTH [PROVIDER] 'provider' "{" | Description a| Modifies the settings for an existing user. -At least one `SET` or `REMOVE` clause is required. + +* At least one `SET` or `REMOVE` clause is required. +* Any `REMOVE` clause(s) must appear before the first `SET` clause. + For more information, see xref:authentication-authorization/manage-users.adoc#access-control-alter-users[Modifying users]. @@ -676,7 +679,7 @@ SHOW USERS WITH AUTH | |"native" |{ -"password": "***", +"password": "*********", "changeRequired": false } |"jack" @@ -686,7 +689,7 @@ SHOW USERS WITH AUTH | |"native" |{ -"password": "***", +"password": "*********", "changeRequired": false } |"jack" @@ -973,13 +976,13 @@ Users can be modified with `ALTER USER`. [source, syntax, role="noheader"] ---- ALTER USER name [IF EXISTS] + [REMOVE HOME DATABASE] + [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }]... [SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password'] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE | SUSPENDED}] [SET HOME DATABASE name] [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... - [REMOVE HOME DATABASE] - [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }]... ---- `` pairs for the `SET AUTH` clause could include: [source, syntax, role="noheader"] @@ -1061,6 +1064,31 @@ SET AUTH 'native' {SET PASSWORD CHANGE REQUIRED} ---- ====== +[role=label--new-5.24] +[role=label--enterprise-edition] +.Modify the user `bob` to remove his native (username / password) auth and add an external OIDC Auth Provider: +====== +[source,cypher,role=noplay] +---- +ALTER USER bob +REMOVE AUTH 'native' +SET AUTH 'oidc-mysso1' {SET ID 'bobsUniqueMySso1Id'} +---- +====== + +[role=label--new-5.24] +[role=label--enterprise-edition] +.Modify the user `bob` to remove any/all of his existing Auth Providers and add two external OIDC Auth Providers: +====== +[source,cypher,role=noplay] +---- +ALTER USER bob +REMOVE ALL AUTH +SET AUTH 'oidc-mysso1' {SET ID 'bobsUniqueMySso1Id'} +SET AUTH 'oidc-mysso2' {SET ID 'bobsUniqueMySso2Id'} +---- +====== + .Assign the user `bob` a different home database: ====== [source,cypher,role=noplay] @@ -1070,12 +1098,13 @@ SET HOME DATABASE anotherDbOrAlias ---- ====== -.Remove the home database from the user `bob`: +.Remove the home database from the user `bob` and set their status to suspended: ====== [source,cypher,role=noplay] ---- ALTER USER bob REMOVE HOME DATABASE +SET STATUS SUSPENDED ---- ====== From 8cfad89b17430e0ad995030d20da4e86b7bfbcba Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Mon, 16 Sep 2024 15:00:35 +0100 Subject: [PATCH 38/62] convert the label to a role --- modules/ROOT/pages/configuration/configuration-settings.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/modules/ROOT/pages/configuration/configuration-settings.adoc b/modules/ROOT/pages/configuration/configuration-settings.adoc index eed1dcc05..22be9afdc 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -4614,12 +4614,10 @@ a|A comma-separated list where each element is a string. m|++++++ |=== - +[[role=label--enterprise-edition label--new-5.24]] [[config_dbms.security.require_local_user]] === `dbms.security.require_local_user` -// label:enterprise-edition[Enterprise Edition] label:new[Introduced in 5.24] - .dbms.security.require_local_user [frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] |=== From 9647b0d21a4131685431b23ee6e6c658364cfb44 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 20 Sep 2024 20:53:28 +0100 Subject: [PATCH 39/62] editorial review of the PR --- .../auth-providers.adoc | 78 ++-- .../dbms-administration.adoc | 4 +- .../authentication-authorization/index.adoc | 9 +- .../ldap-integration.adoc | 105 +++--- .../manage-users.adoc | 344 +++++++++--------- .../sso-integration.adoc | 117 +++--- .../configuration/configuration-settings.adoc | 2 +- modules/ROOT/pages/tutorial/index.adoc | 2 +- .../tutorial/tutorial-sso-configuration.adoc | 144 ++++---- 9 files changed, 423 insertions(+), 382 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 7eaf6ee67..327e33c13 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -1,55 +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 -[role=label--new-5.24] [[access-control-auth-providers]] -= User Auth Providers label:enterprise-edition[] += User auth providers -Authentication and authorization can be controlled on a user-level using Cypher by setting Auth Providers on users. +Authentication and authorization can be controlled on a user level using Cypher by setting auth providers on users. -In order to make use of 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 only users with a corresponding Auth Provider in the database can authenticate and authorize. +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 representing the corresponding auth provider must exist in the database before they can authenticate and authorize. -Auth Providers give you a way to link externally-defined users (e.g. in a 3rd party ID provider like OIDC or LDAP) to the Neo4j internal User model. -The internal model can define things such as 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). +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 -. Provisioning different auth providers (including native username/password auth) for different users. -. Setting an arbitrary reader-friendly username for a user whilst using an external unique identifier (like `sub` for OIDC auth, which is itself not a reader-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. +== 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 which match the provider name of the matching Auth Provider. -The way that the matching lookup is done depends on the type of provider. For example: +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 provider's 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. -- 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 which 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 -== Enabling User Auth Providers mode -When the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting is set to `true`, the lookups described above will be performed when the user authenticates, and a matching user Auth Provider *must* exist in order for a user to be able to successfully authenticate and authorize. +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 ensures that users from the authentication provider must exist in the database before they can log in and be authorized. -== Migrating to Auth Providers mode -If you have existing users in the database and you want to migrate to Auth Providers mode, you can use the `ALTER USER ... SET AUTH` command to attach Auth Provider(s) to an existing user. Until you change `dbms.security.require_local_user` to `true`, this will have no impact on the users' ability to authenticate and authorize as they always have done. +When the user authenticates, Neo4j searches for the user's authentication provider. +If a matching authentication provider is found for that user, the user can log in and be authorized successfully. -Once the process of adding Auth Providers to your users is completed, you can then 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. +== 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 which were created using the original `CREATE USER ... SET PASSWORD` syntax, will implicitly have the native (username / password) Auth Provider, so that would not need to be added explicitly using `SET AUTH`. +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 be certain about which Auth Providers are attached to a user, you can use the xref:authentication-authorization/manage-users.adoc#access-control-list-users[`SHOW USERS WITH AUTH`] command to see the Auth Providers attached to a user. +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[SSO Auth Provider Examples] -- xref:authentication-authorization/manage-users.adoc#access-control-create-users[Native Auth Provider Examples] -- xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[LDAP Auth Provider 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] diff --git a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc index e8d677719..b861c3b44 100644 --- a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc +++ b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc @@ -470,7 +470,7 @@ GRANT [IMMUTABLE] SET PASSWORD[S] GRANT [IMMUTABLE] SET AUTH ON DBMS TO role[, ...] -| Enables the specified roles to `SET` or `REMOVE` users' xref:authentication-authorization/auth-providers.adoc[Auth Providers]. +| 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 @@ -615,7 +615,7 @@ A user that is granted the `SET PASSWORDS` privilege is allowed to run the `ALTE ALTER USER jake SET PASSWORD 'abcd5678' CHANGE NOT REQUIRED ---- -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: +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] ---- diff --git a/modules/ROOT/pages/authentication-authorization/index.adoc b/modules/ROOT/pages/authentication-authorization/index.adoc index 8350a43bd..5db485a8e 100644 --- a/modules/ROOT/pages/authentication-authorization/index.adoc +++ b/modules/ROOT/pages/authentication-authorization/index.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,12 +97,11 @@ 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:: +[[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. +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. diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index 67cd2b1df..afdd3ea83 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -3,31 +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-auth-providers[Control authentication and authorization at the user-level by setting Auth Providers on users] -* 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. @@ -105,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"] ---- @@ -361,88 +336,100 @@ For more information, see xref:authentication-authorization/ldap-integration.ado [role=label--new-5.24] [[auth-ldap-auth-providers]] -== Use Auth Providers to configure authentication / authorization at the user level -xref:authentication-authorization/auth-providers.adoc[Auth Providers] can be used to determine which users can authenticate and authorize using the configured providers, including LDAP. +== 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. -[NOTE] -==== -You need to change the `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. -==== +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 you can use Cypher to do this. +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`. +.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' } ---- -This will create a user who can authenticate and authorize using LDAP provided their LDAP `dn` is `cn=alice,ou=engineering,dc=example,dc=com`. - -When the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. -If there is no matching Auth Provider, the user will not be able to authenticate or 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 will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. +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. +.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'} ---- -This will create a user who can authenticate and authorize using `ldap` or `mysso`. See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for more information on setting up an OIDC provider. -This example also illustrates that the user can have their home database set even when using only external auth providers. + +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. +.Alter a user to remove one of their auth providers. ====== + +[source,cypher,role=noplay] ---- ALTER USER alice REMOVE AUTH 'ldap' ---- -This will prevent the user from being able to authenticate and authorize using `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} ---- -This will allow the user to authenticate and authorize using the specified username and password (in addition to what they are already configured to use). + +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. +.Configure the database to allow authentication via `ldap` and authorization via the `native` provider ====== -Set the following database config: -[source,configuration,role="noheader"] +. Set the following database config: ++ +[source, properties] ---- dbms.security.authentication_providers=ldap dbms.security.authorization_providers=native ---- -Then create a user with an `ldap` Auth Provider: +. 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' } ---- -Then natively grant the `READER` role to the user: +. 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. -This will allow the user to authenticate using `ldap` and receive the `READER` role from the `native` provider. - -It would also be possible to give the user the union of roles from `ldap` *and* `native` roles by setting `ldap` as an authorization provider too: - +. 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 @@ -451,21 +438,23 @@ dbms.security.authorization_providers=native,ldap .Suspend a user ====== +[source,cypher,role=noplay] ---- ALTER USER alice SET STATUS SUSPENDED ---- -This will completely prevent the user from being able to authenticate/authorize by any means. +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 who is part of the `engineering` tree (`cn=alice,ou=engineering,dc=example,dc=com`) and the other who is part of the `sales` tree (`cn=alice,ou=sales,dc=example,dc=com`). +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' } diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 5c3d7e95e..2b3ae6263 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -92,7 +92,7 @@ a| GRANT SHOW USER ---- -(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) +For more information, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]. |=== @@ -118,7 +118,7 @@ Lists the privileges granted to the specified users or the current user if no us When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. -For more information, see xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. +The `SHOW USER name PRIVILEGES` command is described in xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. | Required privilege a| @@ -127,14 +127,14 @@ a| GRANT SHOW PRIVILEGE ---- -(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[DBMS PRIVILEGE MANAGEMENT privileges]) +For more information, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[DBMS PRIVILEGE MANAGEMENT privileges]. [source, privilege, role="noheader"] ---- GRANT SHOW USER ---- -(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) +For more information, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]. |=== @@ -152,7 +152,7 @@ CREATE USER name [IF NOT EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... # Introduced in Neo4j 5.24 ---- `` pairs for the `SET AUTH` clause could include: @@ -161,8 +161,8 @@ CREATE USER name [IF NOT EXISTS] SET AUTH [PROVIDER] 'provider' "{" { SET ID 'id' // a unique identifier of the user in an external system - \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider - \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' # only applicable to the 'native' provider + \| SET PASSWORD CHANGE [NOT] REQUIRED # only applicable to the 'native' provider } "}" ---- @@ -173,7 +173,7 @@ Creates a new user. [NOTE] ==== -It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Provider. +It is mandatory to specify a `SET PASSWORD` or a `SET AUTH` clause or both because users must have at least one auth provider. ==== For more information, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. @@ -185,7 +185,7 @@ a| GRANT CREATE USER ---- -(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) +For more information, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]. |=== @@ -203,16 +203,16 @@ CREATE OR REPLACE USER name [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}] [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... # Introduced in Neo4j 5.24 ---- `` pairs for the `SET AUTH` clause could include: [source, syntax, role="noheader"] ---- SET AUTH [PROVIDER] 'provider' "{" { - SET ID 'id' // a unique identifier of the user in an external system - \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider - \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider + SET ID 'id' # a unique identifier of the user in an external system + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' # only applicable to the 'native' provider + \| SET PASSWORD CHANGE [NOT] REQUIRED # only applicable to the 'native' provider } "}" ---- @@ -223,7 +223,7 @@ Creates a new user, or if a user with the same name exists, replace it. [NOTE] ==== -It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Provider. +It is mandatory to specify a `SET PASSWORD` or a `SET AUTH` clause or both because users must have at least one auth provider. ==== For more information, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. @@ -235,7 +235,7 @@ a| GRANT CREATE USER ---- -(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) +For more information, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]. [source, privilege, role="noheader"] @@ -243,7 +243,7 @@ GRANT CREATE USER GRANT DROP USER ---- -(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) +For more information, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]. |=== @@ -272,7 +272,7 @@ a| GRANT RENAME USER ---- -(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) +For more information, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]. |=== @@ -292,16 +292,16 @@ ALTER USER name [IF EXISTS] [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED} ] [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... # Introduced in Neo4j 5.24 ---- `` pairs for the `SET AUTH` clause could include: [source, syntax, role="noheader"] ---- SET AUTH [PROVIDER] 'provider' "{" { - SET ID 'id' // a unique identifier of the user in an external system - \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider - \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider + SET ID 'id' # a unique identifier of the user in an external system + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' # PASSWORD clauses are only applicable to the 'native' provider + \| SET PASSWORD CHANGE [NOT] REQUIRED # PASSWORD clauses are only applicable to the 'native' provider } "}" ---- @@ -338,7 +338,7 @@ GRANT SET USER HOME DATABASE GRANT SET AUTH ---- -(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) +For more information, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]. |=== @@ -394,21 +394,22 @@ a| GRANT DROP USER ---- -(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) +For more information, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]. |=== [NOTE,role=label--enterprise-edition] ==== -The `SHOW USER[S] PRIVILEGES` command is only available in Neo4j Enterprise Edition. +The `SHOW USER[S] PRIVILEGES` command is described in xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. ==== [[access-control-current-users]] == Listing current user -The currently logged-in user can be seen using `SHOW CURRENT USER`, which will produce a table with the following columns: +You can view the currently logged-in user using the Cypher command `SHOW CURRENT USER`. +It produces a table with the following columns: [options="header", width="100%", cols="2a,4,2m,^.^,^.^"] |=== @@ -441,7 +442,7 @@ Will return `null` in community edition. | suspended | If `true`, the user is currently suspended. -Will return `null` in community edition. +It returns `null` in Community edition. | BOOLEAN | {cross-mark} | {check-mark} @@ -450,7 +451,7 @@ Will return `null` in community edition. | The home database configured by the user, or `null` if no home database has been configured. If this database is unavailable and the user does not specify a database to use, they will not be able to log in. -Will return `null` in community edition. +It returns `null` in Community edition. | STRING | {cross-mark} | {check-mark} @@ -481,14 +482,15 @@ SHOW CURRENT USER [NOTE] ==== -This command is only supported for a logged-in user and will return an empty result if authorization has been disabled. +This command is only supported for a logged-in user and returns an empty result if authorization has been disabled. ==== [[access-control-list-users]] == Listing users -Available users can be seen using `SHOW USERS`, which will produce a table containing a single row per user with the following columns: +You can list all available users using the Cypher command `SHOW USERS`. +It produces a table containing a single row per user with the following columns: [options="header", width="100%", cols="2a,4,2m,^.^,^.^"] |=== @@ -507,17 +509,19 @@ Available users can be seen using `SHOW USERS`, which will produce a table conta | roles | Native roles granted to the user using the `GRANT ROLE` command. -This is not necessarily the set of roles that a user will receive in practice. The latter depends on DMBS configuration as well as the user's xref:authentication-authorization/auth-providers.adoc[Auth Providers]. +The set of roles a user receives in practice may differ from those in this column. +It depends on DMBS configuration and the user's xref:authentication-authorization/auth-providers.adoc[auth providers]. -Examples of where a user would receive a different set of roles from that which appears in this column would include where they use external (e.g. LDAP or OIDC) auth, or where `native` is not listed in the xref:configuration/configuration-settings.adoc#config_dbms.security.authorization_providers[`dbms.security.authorization_providers`] configuration setting. +For example, if they use external (e.g. LDAP or OIDC) auth, or if `native` is not listed in the xref:configuration/configuration-settings.adoc#config_dbms.security.authorization_providers[`dbms.security.authorization_providers`] configuration setting. -Will return `null` in community edition. +It returns `null` in Community edition. | LIST OF STRING | {cross-mark} | {check-mark} | passwordChangeRequired -| If `true`, the user must change their password at the next login. This will be null if the user has `native` auth disabled. +| If `true`, the user must change their password at the next login. +This is `null` if the user has `native` auth disabled. | BOOLEAN | {check-mark} | {check-mark} @@ -525,17 +529,17 @@ Will return `null` in community edition. | suspended | If `true`, the user is currently suspended. -Will return `null` in community edition. +It returns `null` in Community edition. | BOOLEAN | {cross-mark} | {check-mark} | home -| The home database configured by the user, or `null` if no home database has been configured. -A home database will be resolved if it is either pointing to a database or a database alias. -If this database is unavailable and the user does not specify a database to use, they will not be able to log in. +| The home database configured by the user, otherwise `null`. +A home database is resolved if it is pointing to a database or a database alias. +If this database is unavailable or no database is specified, the login will fail. -Will return `null` in community edition. +It returns `null` in Community edition. | STRING | {cross-mark} | {check-mark} @@ -544,7 +548,7 @@ Will return `null` in community edition. [NOTE] ==== When first starting a Neo4j DBMS, there is always a single default user `neo4j` with administrative privileges. -It is possible to set the initial password using xref:configuration/set-initial-password.adoc[`neo4j-admin dbms set-initial-password `], otherwise it is necessary to change the password after the first login. +It is possible to set the initial password using xref:configuration/set-initial-password.adoc[`neo4j-admin dbms set-initial-password `], otherwise you must change the password after the first login. ==== .Show users @@ -608,7 +612,7 @@ WHERE user = 'jake' ====== -.Show user with return clause +.Show user with `RETURN` clause ====== It is possible to add a `RETURN` clause to further manipulate the results after filtering. In this example, the `RETURN` clause is used to filter out the `roles` column and rename the `user` column to `adminUser`. @@ -628,12 +632,14 @@ RETURN user AS adminUser |=== ====== +[role=label--new-5.24] [[access-control-list-user-auth-providers]] -=== Listing User Auth Providers +== Listing user auth providers -To inspect users' xref:authentication-authorization/auth-providers.adoc[Auth Providers], use `SHOW USERS WITH AUTH`. This command will produce a row per user per Auth Provider and will yield the following two columns in addition to those output by `SHOW USERS`: +To inspect users' xref:authentication-authorization/auth-providers.adoc#access-control-list-user-auth-providers[auth providers], use `SHOW USERS WITH AUTH`. +The command produces a row per user per auth provider and yields the following two columns in addition to those output by `SHOW USERS`: -[options="header", width="100%", cols="2a,4,2m,^.^,^.^"] +[options="header", width="100%", cols="1a,4,1m,^.^,^.^"] |=== | Column | Description @@ -648,7 +654,8 @@ To inspect users' xref:authentication-authorization/auth-providers.adoc[Auth Pro | {check-mark} | auth -| A map containing configuration for the user. E.g. dn of the user for an `ldap` auth provider, the unique external identifier for an `oidc` auth provider, or password status for a native auth provider. +| A map containing configuration for the user. +For example, dn of the user for an `ldap` auth provider, the unique external identifier for an `oidc` auth provider, or password status for a `native` auth provider. | MAP | {check-mark} @@ -707,7 +714,7 @@ SHOW USERS WITH AUTH .Show user with auth using filtering ====== -Show all of the users with the `oidc` Auth Provider. +Show all users with the `oidc` auth provider. [source,cypher,role=noplay] ---- SHOW USERS WITH AUTH @@ -738,80 +745,78 @@ WHERE provider = 'oidc1' ====== -[NOTE] -==== -The `SHOW USER name PRIVILEGES` command is described in xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. -==== - - [[access-control-create-users]] == Creating users -Users can be created using `CREATE USER`. +You can create users using one of the following Cypher commands, depending on whether you want to create a new user or replace an existing one. +In both cases, you can specify the user's password, whether they must change it at the next login, their status, home database, and auth provider settings. +The `SET` clauses can be applied in any order. +It is mandatory to specify a `SET PASSWORD` or a `SET AUTH` clause or both because users must have at least one auth provider. +`SET AUTH` is available from Neo4j 5.24 onwards. +.`CREATE USER` syntax [source, syntax, role="noheader"] ---- -CREATE USER name [IF NOT EXISTS] - [SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'] - [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE \| SUSPENDED}] - [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... +CREATE USER name [IF NOT EXISTS] # <1> + [SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'] # <2> + [[SET PASSWORD] CHANGE [NOT] REQUIRED] # <3> + [SET STATUS {ACTIVE \| SUSPENDED}] # <4> + [SET HOME DATABASE name] # <5> + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... # <6> ---- -Users can be created or replaced using `CREATE OR REPLACE USER`. - +.`CREATE OR REPLACE USER` syntax [source, syntax, role="noheader"] ---- -CREATE OR REPLACE USER name - [SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'] - [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE \| SUSPENDED}] - [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... ----- +CREATE OR REPLACE USER name # <1> + [SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'] # <2> + [[SET PASSWORD] CHANGE [NOT] REQUIRED] # <3> + [SET STATUS {ACTIVE \| SUSPENDED}] # <4> + [SET HOME DATABASE name] # <5> + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... # <6> +---- +Where: + +<1> Specifies the command to create a user. +<2> Specifies the password for the user. +The `'password'` can either be a string value or a string parameter with default value length of at least 8 characters. + +The `PLAINTEXT` and `ENCRYPTED` keywords are optional and can be used to specify the format of the password, i.e. whether Neo4j needs to hash it or it has already been hashed. +By default, all passwords are encrypted (hashed) when stored in the Neo4j `system` database. +* The optional `PLAINTEXT` in `SET PLAINTEXT PASSWORD` has the same behavior as `SET PASSWORD`. +* The optional `ENCRYPTED` is used to recreate an existing user when the plaintext password is unknown, but the encrypted password is available in the _data/scripts/databasename/restore_metadata.cypher_ file of a database backup. +See xref:backup-restore/restore-backup#_restore_users_and_roles_metadata[Restore users and roles metadata]. + +With `ENCRYPTED`, the password string is expected to be in the format of `,,`, where, for example: +** `0` is the first version and refers to the `SHA-256` cryptographic hash function with iterations `1`. +** `1` is the second version and refers to the `SHA-256` cryptographic hash function with iterations `1024`. + +<3> Specifies whether the user must change their password at the next login. +If omitted, the default is `CHANGE REQUIRED`. +The `SET PASSWORD` prefix of the `CHANGE [NOT] REQUIRED` clause is only optional if it directly follows the `SET PASSWORD 'password'` clause and is not part of a `SET AUTH` clause. -For both `CREATE` and `CREATE OR REPLACE`, `` pairs for the `SET AUTH` clause could include: +<4> The default for `SET STATUS` is `ACTIVE`. +<5> Specifies a home database for a user. +A home database is resolved if it is pointing to a database or a database alias. +If no home database is set, the DBMS default database is used as the home database for that user. + +<6> label:new[Introduced in 5.24] One or more `SET AUTH` clause can be used to configure external xref:authentication-authorization/auth-providers.adoc[auth providers], such as LDAP or OIDC, which define authentication/authorization providers for that user. +`SET AUTH` can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. +For examples, see xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers] for OIDC and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[Configure authentication/authorization at the user level using auth providers] for LDAP. ++ [source, syntax, role="noheader"] ---- SET AUTH [PROVIDER] 'provider' "{" { - SET ID 'id' // a unique identifier of the user in an external system - \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider - \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider + SET ID 'id' # a unique identifier of the user in an external system. + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' # only applicable to the 'native' provider. + \| SET PASSWORD CHANGE [NOT] REQUIRED # only applicable to the 'native' provider. } "}" ---- -* For `SET PASSWORD`: -** The `password` can either be a string value or a string parameter. -** The default Neo4j password length is at least 8 characters. -** All passwords are encrypted (hashed) when stored in the Neo4j `system` database. -`PLAINTEXT` and `ENCRYPTED` just refer to the format of the password in the Cypher command, i.e. whether Neo4j needs to hash it or it has already been hashed. -Consequently, it is never possible to get the plaintext of a password back out of the database. -A password can be set in either fashion at any time. -** The optional `PLAINTEXT` in `SET PLAINTEXT PASSWORD` has the same behavior as `SET PASSWORD`. -** The optional `ENCRYPTED` is used to recreate an existing user when the plaintext password is unknown, but the encrypted password is available in the _data/scripts/databasename/restore_metadata.cypher_ file of a database backup. -See xref:backup-restore/restore-backup#restore-backup-example[Restore a database backup -> Example]. + -With `ENCRYPTED`, the password string is expected to be in the format of `,,`, where, for example: -*** `0` is the first version and refers to the `SHA-256` cryptographic hash function with iterations `1`. -*** `1` is the second version and refers to the `SHA-256` cryptographic hash function with iterations `1024`. -* If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted, the default is `CHANGE REQUIRED`. -* The `SET PASSWORD` prefix of the `CHANGE [NOT] REQUIRED` clause is only optional if it directly follows the `SET PASSWORD 'password'` clause and is not part of a `SET AUTH` clause. -* The default for `SET STATUS` is `ACTIVE`. -* `SET HOME DATABASE` can be used to configure a home database for a user. -A home database will be resolved if it is either pointing to a database or a database alias. -If no home database is set, the DBMS default database is used as the home database for the user. -[role=label--new-5.24] -* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[Auth Providers], which define authentication / authorization providers for the user. -This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. -Examples can be found below for `native`, xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[here] for OIDC and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[here] for LDAP. -* It is mandatory to specify at least either a `SET PASSWORD` or a `SET AUTH` clause because users must have at least one Auth Provider. -* The `SET` clauses can be applied in any order. [NOTE] ==== -User names are case sensitive. +Usernames are case sensitive. The created user will appear on the list provided by `SHOW USERS`. * In Neo4j Community Edition there are no roles, but all users have implied administrator privileges. @@ -830,8 +835,9 @@ SET PASSWORD 'abcd1234' CHANGE REQUIRED SET STATUS SUSPENDED SET HOME DATABASE anotherDb ---- + [role=label--new-5.24] -The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[auth providers] syntax would be: [source,cypher,role=noplay] ---- @@ -853,9 +859,10 @@ CREATE USER Jake SET ENCRYPTED PASSWORD '1,6d57a5e0b3317055454e455f96c98c750c77fb371f3f0634a1b8ff2a55c5b825,190ae47c661e0668a0c8be8a21ff78a4a34cdf918cae3c407e907b73932bd16c' CHANGE NOT REQUIRED SET STATUS ACTIVE ---- -[role=label--new-5.24] -The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: +[role=label--new-5.24] +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[auth providers] syntax would be: +. [source,cypher,role=noplay] ---- CREATE USER jake @@ -888,7 +895,7 @@ SET PLAINTEXT PASSWORD 'abcd1234' ---- [role=label--new-5.24] -The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[auth providers] syntax would be: [source,cypher,role=noplay] ---- @@ -911,7 +918,7 @@ SET PLAINTEXT PASSWORD 'abcd1234' This is equivalent to running `DROP USER jake IF EXISTS` followed by `CREATE USER jake SET PASSWORD 'abcd1234'`. [role=label--new-5.24] -The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[auth providers] syntax would be: [source,cypher,role=noplay] ---- @@ -936,6 +943,8 @@ Users can be renamed with the `RENAME USER` command. RENAME USER jake TO bob ---- +To verify the change, you can use the `SHOW USERS` command: + [source, cypher, role=noplay] ---- SHOW USERS @@ -971,65 +980,66 @@ The `RENAME USER` command is only available when using native authentication and [[access-control-alter-users]] == Modifying users -Users can be modified with `ALTER USER`. +You can modify users with the `ALTER USER` command. +The command allows you to change the user's password, status, home database, and auth provider settings. +The `SET` and `REMOVE` clauses can be applied in any order. +However, all `REMOVE` clauses must come before the first `SET` clause and at least one `SET` or `REMOVE` clause is required for the command. [source, syntax, role="noheader"] ---- -ALTER USER name [IF EXISTS] - [REMOVE HOME DATABASE] - [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }]... - [SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password'] - [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE | SUSPENDED}] - [SET HOME DATABASE name] - [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... ----- -`` pairs for the `SET AUTH` clause could include: +ALTER USER name [IF EXISTS] # <1> + [REMOVE HOME DATABASE] # <2> + [REMOVE { AUTH [PROVIDER[S]] provider[, ...] \| ALL AUTH [PROVIDER[S]] }]... # <3> + [SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password'] # <4> + [[SET PASSWORD] CHANGE [NOT] REQUIRED] # <5> + [SET STATUS {ACTIVE | SUSPENDED}] # <6> + [SET HOME DATABASE name] # <7> + [SET AUTH [PROVIDER] 'provider' "{"{SET }..."}"]... # <8> +---- +Where: + +<1> Specifies the command to alter a user. +<2> Removes the home database for the user. +As a result, the DBMS default database will be used as the home database for that user. +<3> label:new[Introduced in 5.24] Removes one, several, or all existing xref:authentication-authorization/auth-providers.adoc[auth provider(s)] from a user. +However, a user must always have at least one auth provider. +Therefore, `REMOVE ALL AUTH` must be used in conjunction with at least one `SET AUTH` clause in order to meet this requirement. +<4> Specifies the password for the user. +The `'password'` can either be a string value or a string parameter with default value length of at least 8 characters. + +The `PLAINTEXT` and `ENCRYPTED` keywords are optional and can be used to specify the format of the password, i.e. whether Neo4j needs to hash it or it has already been hashed. +By default, all passwords are encrypted (hashed) when stored in the Neo4j `system` database. +* The optional `PLAINTEXT` in `SET PLAINTEXT PASSWORD` has the same behavior as `SET PASSWORD`. +* The optional `ENCRYPTED` is used to recreate an existing user when the plaintext password is unknown, but the encrypted password is available in the _data/scripts/databasename/restore_metadata.cypher_ file of a database backup. +See xref:backup-restore/restore-backup#_restore_users_and_roles_metadata[Restore users and roles metadata]. + +With `ENCRYPTED`, the password string is expected to be in the format of `,,`, where, for example: +** `0` is the first version and refers to the `SHA-256` cryptographic hash function with iterations `1`. +** `1` is the second version and refers to the `SHA-256` cryptographic hash function with iterations `1024`. +<5> Specifies whether the user must change their password at the next login. +If omitted, the default is `CHANGE REQUIRED`. +The `SET PASSWORD` prefix of the `CHANGE [NOT] REQUIRED` clause is only optional if it directly follows the `SET PASSWORD 'password'` clause and is not part of a `SET AUTH` clause. +<6> The default for `SET STATUS` is `ACTIVE`. +<7> Specifies a home database for a user. A home database is resolved if it is pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for that user. + +<8> label:new[Introduced in 5.24] One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[auth providers], which define authentication / authorization providers for that user. +This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. +For examples, see <>, xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers], and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[Configure authentication/authorization at the user level using auth providers]. ++ [source, syntax, role="noheader"] ---- SET AUTH [PROVIDER] 'provider' "{" { - SET ID 'id' // a unique identifier of the user in an external system - \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' // PASSWORD clauses are only applicable to the 'native' provider - \| SET PASSWORD CHANGE [NOT] REQUIRED // PASSWORD clauses are only applicable to the 'native' provider + SET ID 'id' # a unique identifier of the user in an external system + \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' # only applicable to the 'native' provider + \| SET PASSWORD CHANGE [NOT] REQUIRED # only applicable to the 'native' provider } "}" ---- -* At least one `SET` or `REMOVE` clause is required for the command. -* For `SET PASSWORD`: -** The `password` can either be a string value or a string parameter. -** All passwords are encrypted (hashed) when stored in the Neo4j `system` database. -`PLAINTEXT` and `ENCRYPTED` just refer to the format of the password in the Cypher command, i.e. whether Neo4j needs to hash it or it has already been hashed. -Consequently, it is never possible to get the plaintext of a password back out of the database. -A password can be set in either fashion at any time. -** The optional `PLAINTEXT` in `SET PLAINTEXT PASSWORD` has the same behavior as `SET PASSWORD`. -** The optional `ENCRYPTED` is used to update an existing user's password when the plaintext password is unknown, but the encrypted password is available in the _data/scripts/databasename/restore_metadata.cypher_ file of a database backup. -See xref:backup-restore/restore-backup#restore-backup-example[Restore a database backup -> Example]. + -With `ENCRYPTED`, the password string is expected to be in the format of `,,`, where, for example: -*** `0` is the first version and refers to the `SHA-256` cryptographic hash function with iterations `1`. -*** `1` is the second version and refers to the `SHA-256` cryptographic hash function with iterations `1024`. -* If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted, the default is `CHANGE REQUIRED`. -* The `SET PASSWORD` prefix of the `CHANGE [NOT] REQUIRED` clause is only optional if it directly follows the `SET PASSWORD 'password'` clause and is not part of a `SET AUTH` clause. -* `SET HOME DATABASE` can be used to configure a home database for a user. -A home database will be resolved if it is either pointing to a database or a database alias. -If no home database is set, the DBMS default database is used as the home database for the user. -[role=label--new-5.24] -* One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[Auth Providers], which define authentication / authorization providers for the user. -This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. -** xref:authentication-authorization/manage-users.adoc#access-control-create-users[Native Auth Provider Examples] -** xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO Auth Provider Examples] -** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[LDAP Auth Provider Examples] -* `REMOVE HOME DATABASE` is used to unset the home database for a user. -This results in the DBMS default database being used as the home database for the user. -[role=label--new-5.24] -* `REMOVE AUTH` is used to remove one or many xref:authentication-authorization/auth-providers.adoc[Auth Provider(s)] from a user. It cannot be used in a way that would mean a user has no Auth Providers. -* `REMOVE ALL AUTH` is used to remove all existing xref:authentication-authorization/auth-providers.adoc[Auth Providers] from a user. It must be used in conjunction with at least one `SET AUTH` clause in order to meet the requirement that a user always has at least one auth provider. -* All of the `SET` and `REMOVE` clauses can be applied in any order among themselves. However, all `REMOVE` clauses must come before the first `SET` clause. - -.Modify the user `bob` with a new password and active status, and remove the requirement to change his password: +.Modify a user's password and status ====== +For example, you can modify the user `bob` by setting a new password and active status, and removing the requirement to change his password by running: + [source,cypher,role=noplay] ---- ALTER USER bob @@ -1038,7 +1048,7 @@ SET STATUS ACTIVE ---- [role=label--new-5.24] -The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[auth providers] syntax would be: ---- ALTER USER bob @@ -1047,8 +1057,10 @@ SET STATUS ACTIVE ---- ====== -.Modify the user `bob` to expire his current password so that he must change it the next time he logs in: +.Modify a user to expire their current password ====== +For example, you can modify the user `bob` to expire his current password so that he must change it the next time he logs in: + [source,cypher,role=noplay] ---- ALTER USER bob @@ -1056,7 +1068,7 @@ SET PASSWORD CHANGE REQUIRED ---- [role=label--new-5.24] -The equivalent command using the xref:authentication-authorization/auth-providers.adoc[Auth Providers] syntax would be: +The equivalent command using the xref:authentication-authorization/auth-providers.adoc[auth providers] syntax would be: ---- ALTER USER bob @@ -1064,10 +1076,11 @@ SET AUTH 'native' {SET PASSWORD CHANGE REQUIRED} ---- ====== -[role=label--new-5.24] -[role=label--enterprise-edition] -.Modify the user `bob` to remove his native (username / password) auth and add an external OIDC Auth Provider: +[role=label--enterprise-edition label--new-5.24] +.Modify a user to use an external OIDC auth provider ====== +For example, you can modify the user `bob` by removing his native auth provider and adding an external OIDC auth provider: + [source,cypher,role=noplay] ---- ALTER USER bob @@ -1076,10 +1089,11 @@ SET AUTH 'oidc-mysso1' {SET ID 'bobsUniqueMySso1Id'} ---- ====== -[role=label--new-5.24] -[role=label--enterprise-edition] -.Modify the user `bob` to remove any/all of his existing Auth Providers and add two external OIDC Auth Providers: +[role=label--enterprise-edition label--new-5.24] +.Modify a user to use multiple external OIDC auth providers ====== +For example, you can modify the user `bob` by removing all of his existing auth providers and adding two external OIDC auth providers: + [source,cypher,role=noplay] ---- ALTER USER bob @@ -1089,8 +1103,10 @@ SET AUTH 'oidc-mysso2' {SET ID 'bobsUniqueMySso2Id'} ---- ====== -.Assign the user `bob` a different home database: +.Assign a user a different home database ====== +For example, you can modify the user `bob` by assigning him a different home database: + [source,cypher,role=noplay] ---- ALTER USER bob @@ -1098,8 +1114,10 @@ SET HOME DATABASE anotherDbOrAlias ---- ====== -.Remove the home database from the user `bob` and set their status to suspended: +.Remove the home database from a user and set their status to suspended ====== +For example, you can modify the user `bob` by removing his home database and setting his status to suspended: + [source,cypher,role=noplay] ---- ALTER USER bob @@ -1111,12 +1129,12 @@ SET STATUS SUSPENDED [NOTE] ==== When altering a user, it is only necessary to specify the changes required. -For example, leaving out the `CHANGE [NOT] REQUIRED` part of the query will leave that unchanged. +For example, leaving out the `CHANGE [NOT] REQUIRED` part of the query leaves that unchanged. ==== [NOTE, role=label--enterprise-edition] ==== -The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE`, `REMOVE HOME DATABASE`, and `REMOVE AUTH` parts of the command are only available in Neo4j Enterprise Edition. +The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE`, `REMOVE HOME DATABASE`, and `REMOVE AUTH` parts of the command are only available in Neo4j Enterprise Edition. The `SET AUTH` clause for external providers is only available in Neo4j Enterprise Edition. However, `SET AUTH 'native'` can be used in Neo4j Community Edition. ==== @@ -1189,9 +1207,9 @@ Users can be deleted with `DROP USER`. DROP USER bob ---- -Deleting a user will not automatically terminate associated connections, sessions, transactions, or queries. +Deleting a user does not automatically terminate associated connections, sessions, transactions, or queries. -However, when a user has been deleted, it will no longer appear on the list provided by `SHOW USERS`: +However, when a user is deleted, it no longer appears on the list provided by `SHOW USERS`: [source, cypher, role=noplay] ---- diff --git a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc index e83d6726a..05f9a9d44 100644 --- a/modules/ROOT/pages/authentication-authorization/sso-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/sso-integration.adoc @@ -154,7 +154,7 @@ If a proxy is required, this can be https://docs.oracle.com/en/java/javase/17/do Proxies that require credentials are not supported. [[auth-sso-map-idp-roles]] -== Map the Identity Provider Groups to the Neo4j Roles +== Map the identity provider groups to the Neo4j roles Before identity provider managed groups can be used with Neo4j, you have to decide on an approach for mapping identity provider groups to Neo4j roles. The simplest approach is to create identity provider groups with the same names as Neo4j roles. @@ -186,15 +186,15 @@ See xref:authentication-authorization/manage-roles.adoc[Manage roles]. ==== [[auth-sso-configure-provider]] -== Configure Neo4j to use an OpenID Connect Identity Provider +== Configure Neo4j to use an OpenID Connect identity provider This option allows users to log in through an OIDC compliant identity provider by offering a token from the provider instead of a username and password. Typically, these tokens take the form of a signed JSON Web Token (JWT). -In the configuration examples below, we are using `mysso` as our provider name. +The following configuration examples use `mysso` as the provider's name. It is recommended to use a name describing the provider that is being integrated. [[auth-sso-configure-provider-jwt]] -=== OpenID Connect Using JWT Claims +=== OpenID Connect using JWT claims In this configuration, Neo4j receives a JWT from the identity provider containing claims representing the database username (e.g. email), and the Neo4j roles. @@ -206,7 +206,7 @@ In the _neo4j.conf_ file, uncomment and configure the following settings: ---- dbms.security.oidc.mysso.display_name=SSO Provider ---- -This is displayed on a button on the login page of clients such as Neo4j Browser and Bloom, so that users can identify the provider they are using to login. +This is displayed on a button on the login page of clients, such as Neo4j Browser and Bloom so that you can identify the provider you are using to login. . Configure discovery. + @@ -216,7 +216,7 @@ Uncomment and configure the following settings: ---- dbms.security.oidc.mysso.well_known_discovery_uri=https://my-idp.example.com/.well-known/openid-configuration ---- -The `well_known_discovery` endpoint of the identity provider supplies the OpenID Provider Metadata to allow Neo4j to interact with a provider. +The `well_known_discovery` endpoint of the identity provider supplies the OpenID provider metadata to allow Neo4j to interact with that provider. It is also possible to configure the provider settings manually: + [source, properties] @@ -251,130 +251,135 @@ dbms.security.oidc.mysso.claims.groups=roles . Optionally, map the groups in the OIDC groups claim to the Neo4j built-in and custom roles. + -See xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the Identity Provider Groups to the Neo4j Roles]. +See <> +[[auth-sso-configure-provider-userinfo]] +=== OpenID Connect fetching claims from a provider + +In this configuration, Neo4j receives a token from the identity provider and uses that token to call back to the identity provider using its _UserInfo_ endpoint to retrieve claims for the database username and Neo4j roles. + +. Configure Neo4j for xref:authentication-authorization/sso-integration.adoc#auth-sso-configure-provider-jwt[OpenID Connect Using JWT Claims]. + +. Configure the claims to fetch from the _UserInfo_ endpoint: ++ +[source, properties] +---- +dbms.security.oidc.mysso.get_username_from_user_info=true +dbms.security.oidc.mysso.get_groups_from_user_info=true +---- ++ +It is possible to fetch just the username, just the groups, or both from the userinfo endpoint. + [role=label--new-5.24] [[auth-sso-auth-providers]] -=== Use Auth Providers to configure SSO at the user level -xref:authentication-authorization/auth-providers.adoc[Auth Providers] can be used to determine which users can authenticate and authorize using the configured providers. +=== Configure SSO 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. -[NOTE] -==== -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` 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. -==== +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. -The following examples show how you can use Cypher to do this. +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 using Cypher. -.Create a user with an Auth Provider who can authenticate and authorize using `mysso`. +.Create a user with an auth provider who can authenticate and authorize using `mysso` ====== +[source,cypher,role=noplay] ---- CREATE USER jake SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySsoId'} // the id must match the claim that you configured via dbms.security.oidc.mysso.claims.username ---- -This will create a user who can authenticate and authorize using `mysso` if they present a valid token with a `sub` claim of `jakesUniqueMySsoId`. -The claim used for authentication is determined by the xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] config setting (default the default is the `sub` claim). -When the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting is set to `true`, users can *only* authenticate when there is a user in the database with an Auth Provider which links to the provider that the user is trying to authenticate with. - -If there is no matching Auth Provider, the user will not be able to authenticate or 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 will have no bearing on the way that they are authenticated and authorized, instead authentication and authorization will be controlled centrally (for all users) by the database configuration. +The command creates the user `jake` who can authenticate and authorize using `mysso` provided they present a valid token with a `sub` claim of `jakesUniqueMySsoId`. +The claim used for authentication is determined by the xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] config setting (the default is the `sub` claim). ====== -.Create a user with two Auth Providers allowing the user to authenticate and authorize with either of two providers. +.Create a user with two auth providers allowing the user to authenticate and authorize with one of them ====== +[source,cypher,role=noplay] ---- CREATE USER jake SET HOME DATABASE anotherDb SET AUTH 'oidc-mysso1' {SET ID 'jakesUniqueMySso1Id'} // `jakesUniqueMySso1Id` must match the value of the claim that you configured via dbms.security.oidc.mysso1.claims.username SET AUTH 'oidc-mysso2' {SET ID 'jakesUniqueMySso2Id'} // `jakesUniqueMySso2Id` must match the value of the claim that you configured via dbms.security.oidc.mysso2.claims.username ---- -This will create a user who can authenticate and authorize using `mysso1` or `mysso2`. -This example also illustrates that the user can have their home database set even when using only external auth providers. +The command creates the user `jake` who can authenticate and authorize using `mysso1` or `mysso2`. +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. +.Alter a user to remove one of their auth providers ====== +[source,cypher,role=noplay] ---- ALTER USER jake REMOVE AUTH 'oidc-mysso2' ---- -This will prevent the user from being able to authenticate and authorize with the `mysso2` provider. +The command prevents the user `jake` from being able to authenticate and authorize with the `mysso2` provider. ====== .Alter a user to allow them to authenticate and authorize using username and password ====== +[source,cypher,role=noplay] ---- ALTER USER jake SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED} ---- -This will allow the user to authenticate and authorize using the specified username and password (in addition to what they are already configured to use). +The command allows the user `jake` 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 `mysso` and authorization via the `native` provider. +.Configure the database to allow authentication via `mysso` and authorization via the `native` provider ====== -Set the following database config: -[source,configuration,role="noheader"] +. Set the following database config: ++ +[source, properties] ---- dbms.security.authentication_providers=oidc-mysso dbms.security.authorization_providers=native ---- -Then create a user with a `mysso` Auth Provider: +. Create a user with a `mysso` auth provider: ++ +[source,cypher,role=noplay] ---- CREATE USER jake SET AUTH 'oidc-mysso' {SET ID 'jakesUniqueMySsoId'} // `jakesUniqueMySsoId` must match the value of the claim that you configured via dbms.security.oidc.mysso.claims.username ---- -Then natively grant the `READER` role to the user: +. Natively grant the `READER` role to the user: ++ +[source,cypher,role=noplay] ---- GRANT ROLE READER TO jake ---- ++ +The command allows the user `jake` to authenticate using `mysso` and receive the `READER` role from the `native` provider. -This will allow the user to authenticate using `mysso` and receive the `READER` role from the `native` provider. - -It would also be possible to give the user the union of roles from `mysso` *and* `native` by setting `mysso` as an authorization provider too: - +. You can also give the user the union of roles from `mysso` *and* `native` by setting `mysso` as an authorization provider too: ++ +[source, properties] ---- dbms.security.authentication_providers=oidc-mysso dbms.security.authorization_providers=native,oidc-mysso ---- ====== - .Suspend a user ====== +[source,cypher,role=noplay] ---- ALTER USER jake SET STATUS SUSPENDED ---- -This will completely prevent the user from being able to authenticate/authorize by any means. +The command completely prevents the user from being able to authenticate/authorize by any means. ====== - -[[auth-sso-configure-provider-userinfo]] -=== OpenID Connect Fetching Claims from Provider - -In this configuration, Neo4j receives a token from the identity provider and uses that token to call back to the identity provider using its _UserInfo_ endpoint to retrieve claims for the database username and Neo4j roles. - -. Configure Neo4j for xref:authentication-authorization/sso-integration.adoc#auth-sso-configure-provider-jwt[OpenID Connect Using JWT Claims]. - -. Configure the claims to fetch from the _UserInfo_ endpoint: -+ -[source, properties] ----- -dbms.security.oidc.mysso.get_username_from_user_info=true -dbms.security.oidc.mysso.get_groups_from_user_info=true ----- -It is possible to fetch just the username, just the groups, or both from the userinfo endpoint. - [[auth-sso-self-signed-certificate]] == Use a self-signed certificate (SSL) in a test environment diff --git a/modules/ROOT/pages/configuration/configuration-settings.adoc b/modules/ROOT/pages/configuration/configuration-settings.adoc index 22be9afdc..4632700ac 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -4614,7 +4614,7 @@ a|A comma-separated list where each element is a string. m|++++++ |=== -[[role=label--enterprise-edition label--new-5.24]] +[role=label--enterprise-edition label--new-5.24] [[config_dbms.security.require_local_user]] === `dbms.security.require_local_user` diff --git a/modules/ROOT/pages/tutorial/index.adoc b/modules/ROOT/pages/tutorial/index.adoc index 332a00aa7..2dd79272a 100644 --- a/modules/ROOT/pages/tutorial/index.adoc +++ b/modules/ROOT/pages/tutorial/index.adoc @@ -10,6 +10,6 @@ The following step-by-step tutorials cover common operational tasks or otherwise * xref:tutorial/neo4j-admin-import.adoc[Neo4j Admin import] -- This tutorial provides detailed examples to illustrate the capabilities of importing data from CSV files with the command `neo4j-admin database import`. * xref:tutorial/tutorial-composite-database.adoc[Set up and use a Composite database] -- This tutorial walks through the basics of setting up and using Composite databases. * xref:tutorial/access-control.adoc[Fine-grained access control (example)] -- This tutorial presents an example that illustrates various aspects of security and fine-grained access control. -* xref:tutorial/tutorial-sso-configuration.adoc[SSO configuration] -- This tutorial presents examples and solutions to common problems when configuring SSO. +* xref:tutorial/tutorial-sso-configuration.adoc[Configuring Neo4j Single Sign-On (SSO)] -- This tutorial presents examples and solutions to common problems when configuring SSO. * xref:tutorial/tutorial-immutable-privileges.adoc[Administering immutable privileges] -- This tutorial describes methods for administering immutable privileges. * xref:tutorial/tutorial-clustering-docker.adoc[Deploy a Neo4j cluster in a Docker container] -- This tutorial walks through setting up a Neo4j cluster on your local computer for testing purposes. diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index 23c3524bd..066aeaf37 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -1,6 +1,6 @@ [role=enterprise-edition] [[tutorial-sso-configuration]] -= Neo4j Single Sign-On (SSO) configuration += Configuring Neo4j Single Sign-On (SSO) :description: Detailed examples of how to configure Single Sign-On (SSO) for several identity providers. It also presents frequently asked questions and solutions to common problems encountered when configuring SSO. Neo4j supports SSO authentication and authorization through identity providers implementing the OpenID Connect (OIDC) standard. @@ -23,16 +23,18 @@ SSO works in the following way: . The client (e.g., Bloom, Neo4j Browser, etc.) asks the user for credentials and contacts the identity provider. . The identity provider responds with a JSON Web Token (JWT), a JSON file containing fields (claims) relative to the user (email, audience, groups, etc.). . The client provides the server with the JWT, and the server verifies its signature with the JWKs. -[role=label--new-5.24] -. By setting the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true`, you can control which users can authenticate and authorize by creating xref:authentication-authorization/auth-providers.adoc[Auth Providers] in the database using Cypher. -In this mode, a user with a matching Auth Provider must exist in the database for the user to be able to authenticate and authorize using an SSO (or any external) provider. -This allows you to do the following in the database, using Cypher: -.. `SUSPEND` SSO users. -.. Set the `HOME DATABASE` for an SSO user. -.. Set a reader-friendly name for an SSO user (rather than relying on the external identifier). +. label:new[Introduced in 5.24] Optionally, you can control the authentication and authorization on a user level by setting xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] to `true` in the _neo4j.conf_ file and the xref:authentication-authorization/auth-providers.adoc[auth providers] for the users, which authentication and authorization you want to control, using Cypher. +The setting mandates that users representing the corresponding auth provider must exist in the database to be able to authenticate and authorize using an SSO (or any external) provider. +For information on how to modify or create users in this mode, see xref:authentication-authorization/manage-users.adoc[Manage users]. + +This mode allows you the following using Cypher: +.. Suspend SSO users. +.. Set a home database for an SSO user. +.. Set a user-friendly name for an SSO user (rather than relying on the external identifier). +.. Set a password for an SSO user. +.. Set a password change requirement for an SSO user. + +For further information and examples, see xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers]. -See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for examples. -+ [IMPORTANT] ==== JWTs must *always* contain a value for `sub` even when using a different claim for `username`. @@ -134,10 +136,12 @@ dbms.security.oidc.okta.config=token_type_principal=id_token;token_type_authenti + image::sso-configuration-tutorials/okta-sign-on-tab.svg[title="Okta's sign-on tab"] + -[role=label--new-5.24] -. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-providers.adoc[Auth Providers] to achieve this. -Set the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true` in the _neo4j.conf_ file to enable this mode. -For example to create a user `jake` who can authenticate using native or Okta, and authorize using Okta (as configured in step 3), you can use the following Cypher query: +. label:new[Introduced in 5.24] (Optional) If you want control the authentication and authorization on a user level, configure xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] to `true` in the _neo4j.conf_ file. +This setting mandates that users representing the corresponding auth provider must exist in the database before they can authenticate and authorize. +For information on how to create users in this mode, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. ++ +For example, to create the user `jake` who can authenticate using `native` or `okta`, and authorize using Okta (as configured in step 3), you can use the following Cypher query: ++ [source, cypher, role=noplay] ---- CREATE USER jake @@ -145,8 +149,8 @@ SET HOME DATABASE 'jakesHomeDb' SET AUTH 'oidc-okta' {SET ID 'jakesUniqueOktaUserId'} // `jakesUniqueOktaUserId` must match the value of the claim that you configured via dbms.security.oidc.okta.claims.username SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED} ---- - -See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for further examples. ++ +See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers] for further examples. @@ -164,7 +168,7 @@ This example shows how to configure Entra ID for authentication and authorizatio . Open the **Expose an API** tab and select **Add a Scope**. .. If you click the **Add a Scope** button for the first time, you see a new pane stating that you need to add an _Application ID URI_ before proceeding. + -You can find it on your app *Overview* page. +You can find it on your app *Overview* page. + .The GUID is used to identify specific resources or instances within Azure. You can find it on the app registration page. image::sso-configuration-tutorials/azure-id.svg[] @@ -287,7 +291,7 @@ In the next step, you must map these to user roles in the Neo4j settings. image::sso-configuration-tutorials/oidc-azure-server-groups.png[title="Entra OIDC server groups"] . Configure a mapping from Entra Group Object IDs to Neo4j roles. -For details, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the Identity Provider Groups to the Neo4j Roles]. +For details, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. + [source, properties] ---- @@ -303,14 +307,14 @@ dbms.security.oidc.azure.authorization.group_to_role_mapping= "e8b6ddfa-688d-4ac dbms.security.oidc.azure.claims.groups=groups ---- -==== Using Entra ID App Roles +==== Using Entra ID App roles . On the app's home page, navigate to *App roles* and add the Neo4j roles to the Microsoft Entra ID. + image::sso-configuration-tutorials/oidc-azure-app-roles.png[title="Entra OIDC app roles config"] -. The *Value* column in the App roles config must either correspond to Neo4j Roles or be mapped in the _neo4j.conf_ file. -For details, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the Identity Provider Groups to the Neo4j Roles]. +. The *Value* column in the App roles config must either correspond to Neo4j roles or be mapped in the _neo4j.conf_ file. +For details, see xref:authentication-authorization/sso-integration.adoc#auth-sso-map-idp-roles[Map the identity provider groups to the Neo4j roles]. + [source, properties] ---- @@ -326,24 +330,27 @@ dbms.security.oidc.azure.authorization.group_to_role_mapping= "managers" = admin dbms.security.oidc.azure.claims.groups=roles ---- -[role=label--new-5.24] -. (Optional). If you want to mandate that users exist in the database in order to authenticate and authorize, you can use xref:authentication-authorization/auth-providers.adoc[Auth Providers] to achieve this. -Set the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true` in the _neo4j.conf_ file to enable this mode. -For example to create a user `jake` who can authenticate and authorize using Azure, you can use the following Cypher query: +. label:new[Introduced in 5.24] (Optional) If you want control the authentication and authorization on a user level, configure xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] to `true` in the _neo4j.conf_ file. +This setting mandates that users representing the corresponding auth provider must exist in the database before they can authenticate and authorize. +For information on how to create users in this mode, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. ++ +For example, to create a user `jake` who can authenticate and authorize using Azure, you can use the following Cypher query: ++ [source, cypher, role=noplay] ---- CREATE USER jake SET HOME DATABASE 'jakesHomeDb' SET AUTH 'oidc-azure' {SET ID 'jakesUniqueAzureUserId'} // `jakesUniqueAzureUserId` must match the value of the claim that you configured via dbms.security.oidc.azure.claims.username ---- - -See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[SSO integration] for further examples. ++ +See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers] for further examples. == Google -This example shows how to use Google OpenID Connect for authentication using ID tokens in conjunction with native authorization. +=== ID token +This example shows how to use Google OpenID Connect for authentication using ID tokens in conjunction with native authorization. . Configure the client and the redirect URI: + @@ -357,7 +364,7 @@ SSO authorization does not work with Google, as the JWT returned by Google does Therefore, it is recommended to use native (or another flavor) authorization by creating a native version of the user in Neo4j. ==== -. Configure Neo4j to use Google authentication by configuring the following settings in the _neo4j.conf_ file: +. Configure Neo4j to use Google authentication by setting the following configurations in the _neo4j.conf_ file: + [source, properties] ---- @@ -373,103 +380,108 @@ dbms.security.oidc.google.token_params=client_secret=GOCSPX-v4cGkygPJvm3Sjjbc0hv dbms.security.oidc.google.config=token_type_principal=id_token;token_type_authentication=id_token ---- -There are then two ways to create the user in the database (which is required to give the users roles from native authorization): +. Using one of the following options, create a user in the database who can authenticate and authorize natively to be able to give the users roles from native authorization. ++ +[.tabbed-example] +===== +[.include-with-auth-providers] +====== +label:new[Introduced in 5.24] -. Using Auth Providers. -xref:authentication-authorization/auth-providers.adoc[Auth Providers] allow us to specify authentication and authorization providers at the user-level which is useful in this scenario. -This approach relies on the existence of an `admin` user who can authenticate natively, and can themselves create less privileged users who may only authenticate using `oidc-google` and who will receive the roles granted to them using `native` authorization. +This approach relies on the existence of an admin user who can authenticate natively and then create less privileged users via xref:authentication-authorization/auth-providers.adoc[auth providers], who can authenticate only using `oidc-google`, but will receive the roles granted to them using `native` authorization. [NOTE] ==== An admin user with the name `neo4j` is created by default when the database is xref:configuration/set-initial-password.adoc[first started]. ==== -.. Change the configuration to allow `native` authentication (for use only by the `admin` user): - +. In the _neo4j.conf_ file, temporarily enable native authentication for the `admin` user only and enable the user-level control of authentication and authorization: ++ [source, properties] ---- dbms.security.authentication_providers=oidc-google, native ----- - -.. Set the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true` in the _neo4j.conf_ file. -This will switch to __User Auth Providers__ mode whereby users can only authenticate and authorize if they have a corresponding Auth Provider in the database. - -[source, properties] ----- dbms.security.require_local_user=true ---- +This will switch to __user auth providers__ mode whereby users can only authenticate and authorize if they have a corresponding auth provider in the database. - -.. Create a user who can authenticate and authorize using `oidc-google` (they will not be able to authenticate using `native` (username and password) authentication, only `oidc-google`): - +. Create a user who can authenticate and authorize only using `oidc-google`: ++ [source, cypher, role=noplay] ---- CREATE USER jake SET HOME DATABASE 'jakesHomeDb' -SET AUTH 'oidc-google' {SET ID 'jakesUniqueGoogleUserId'} // `jakesUniqueGoogleUserId` must match the value of the claim that you configured via dbms.security.oidc.google.claims.username +SET AUTH 'oidc-google' {SET ID 'jakesUniqueGoogleUserId'} # <1> ---- ++ +<1> `jakesUniqueGoogleUserId` must match the value of the claim that you configured via `dbms.security.oidc.google.claims.username`. -.. Grant the user roles using native authorization. - +. Grant the user `jake` roles, for example, `reader`: ++ [source, cypher, role=noplay] ---- GRANT ROLE reader TO jake ---- ++ +The user implicitly receives `native` authorization because `native` is in the list of authorization providers and you have explicitly granted the user a role. -The user will implicitly receive `native` authorization because `native` is in the list of authorization providers and you have explicitly granted the user a role. - -Once you have set up your users in this way, you can disable native authentication for the database completely (this will prevent all users, including the admin, from logging in with a username and password): - +. Once you have set up your users in this way, you can disable native authentication for the database completely. +This will prevent all users, including the admin, from logging in with a username and password: ++ [source, properties] ---- dbms.security.authentication_providers=oidc-google ---- +====== +[.include-with-native-authentication] +====== -. Alternatively, if you don't use Auth Providers, you can temporarily enable `native` authentication to create an SSO-authenticated admin user `alice` who can then create other users who can only authenticate using SSO. - -To do this we temporarily enable native authentication: +Alternatively, if you do not use auth providers, you can temporarily enable `native` authentication to create an SSO-authenticated admin user `alice` who can then create other users who can only authenticate using SSO. +. Temporarily enable `native` authentication: ++ [source, properties] ---- dbms.security.authentication_providers=oidc-google, native ---- -Then, create an SSO-authenticated `admin` user (in this example an equivalent of `alice@neo4j-test.com` must be set up in the Google SSO provider and their credentials must be known): - +. Create an SSO-authenticated `admin` user (in this example an equivalent of `alice@neo4j-test.com` must be set up in the Google SSO provider and their credentials must be known): ++ [source] ---- CREATE USER `alice@neo4j-test.com` SET PASSWORD 'secretpassword'; GRANT ROLE admin to `alice@neo4j-test.com`; ---- -Disable native authentication for the database to prevent users logging in with username and password: - +. Disable native authentication for the database to prevent users logging in with username and password: ++ [source, properties] ---- dbms.security.authentication_providers=oidc-google ---- -. Log via Google SSO as `alice@neo4j-test.com`, the `admin` user - -. Use this admin user to create other users who can only authenticate using `oidc-google` and will receive the roles granted to them using `native` authorization. - +. Log in via Google SSO as `alice@neo4j-test.com`, the `admin` user. +. Create other users who can authenticate only using `oidc-google` and will receive the roles granted to them using `native` authorization. ++ [source, cypher, role=noplay] ---- -CREATE USER jakesUniqueGoogleUserId // `jakesUniqueGoogleUserId` must match the value of the claim that you configured via dbms.security.oidc.google.claims.username +CREATE USER jakesUniqueGoogleUserId # <1> SET HOME DATABASE 'jakesHomeDb' SET PASSWORD 'secretpassword' SET PASSWORD CHANGE NOT REQUIRED ---- +<1> `jakesUniqueGoogleUserId` must match the value of the claim that you configured via `dbms.security.oidc.google.claims.username`. -.. Grant the user roles using native authorization - +. Grant the user roles using native authorization: ++ [source, cypher, role=noplay] ---- GRANT ROLE reader TO jakesUniqueGoogleUserId ---- +====== +===== == FAQ From 4ed694a707aa90994981c703fbe7ce13896b5933 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Mon, 23 Sep 2024 09:45:06 +0100 Subject: [PATCH 40/62] Update modules/ROOT/pages/authentication-authorization/ldap-integration.adoc Co-authored-by: Therese Magnusson --- .../pages/authentication-authorization/ldap-integration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index afdd3ea83..e658c194d 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -374,7 +374,7 @@ See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-provide 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. +.Alter a user to remove one of their auth providers ====== [source,cypher,role=noplay] From 10e6ed57dd2bbfd5502383fb772e9891e2543264 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Mon, 23 Sep 2024 09:45:24 +0100 Subject: [PATCH 41/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc Co-authored-by: Therese Magnusson --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 2b3ae6263..bbbfb0a10 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -160,7 +160,7 @@ CREATE USER name [IF NOT EXISTS] ---- SET AUTH [PROVIDER] 'provider' "{" { - SET ID 'id' // a unique identifier of the user in an external system + SET ID 'id' # a unique identifier of the user in an external system \| SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' # only applicable to the 'native' provider \| SET PASSWORD CHANGE [NOT] REQUIRED # only applicable to the 'native' provider } From 2049ab83dfffa641a3c09c93d153f066644c0e34 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 10:19:29 +0100 Subject: [PATCH 42/62] Update modules/ROOT/pages/authentication-authorization/auth-providers.adoc Co-authored-by: Phil Wright <95368282+phil198@users.noreply.github.com> --- .../ROOT/pages/authentication-authorization/auth-providers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 327e33c13..586a296f4 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -7,7 +7,7 @@ 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 representing the corresponding auth provider must exist in the database before they can authenticate and authorize. +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. From ae52401cd6a88b435b33eda54a614179fe324bd1 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 10:19:50 +0100 Subject: [PATCH 43/62] Update modules/ROOT/pages/authentication-authorization/auth-providers.adoc Co-authored-by: Phil Wright <95368282+phil198@users.noreply.github.com> --- .../ROOT/pages/authentication-authorization/auth-providers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 586a296f4..5b28746d0 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -27,7 +27,7 @@ User auth providers can be used for a variety of use cases, including: == 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 provider's name of the matching auth provider. +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: From 35fafdefb219475772c2f80db033d2756d9bfc4b Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 10:20:06 +0100 Subject: [PATCH 44/62] Update modules/ROOT/pages/authentication-authorization/auth-providers.adoc Co-authored-by: Phil Wright <95368282+phil198@users.noreply.github.com> --- .../ROOT/pages/authentication-authorization/auth-providers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 5b28746d0..3eb59f7f3 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -39,7 +39,7 @@ For example: == 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 ensures that users from the authentication provider must exist in the database before they can log in and be authorized. +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 the user's authentication provider. If a matching authentication provider is found for that user, the user can log in and be authorized successfully. From d509b3e37cc3c0e185726c98a84b7de2fae706a9 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 10:20:30 +0100 Subject: [PATCH 45/62] Update modules/ROOT/pages/authentication-authorization/auth-providers.adoc Co-authored-by: Phil Wright <95368282+phil198@users.noreply.github.com> --- .../pages/authentication-authorization/auth-providers.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc index 3eb59f7f3..ca0318d8a 100644 --- a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -41,8 +41,8 @@ For example: 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 the user's authentication provider. -If a matching authentication provider is found for that user, the user can log in and be authorized successfully. +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 From 95d1d02c11eb67c3113ab28dca34cb9c37657738 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 10:21:03 +0100 Subject: [PATCH 46/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc Co-authored-by: Phil Wright <95368282+phil198@users.noreply.github.com> --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index bbbfb0a10..c9f0b1472 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -173,7 +173,7 @@ Creates a new user. [NOTE] ==== -It is mandatory to specify a `SET PASSWORD` or a `SET AUTH` clause or both because users must have at least one auth provider. +It is mandatory to specify a `SET PASSWORD` and/or at least one `SET AUTH` clause because users must have at least one auth provider. ==== For more information, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. From 6ea6053a4f371b2f52653283725279f249e44b76 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 10:21:17 +0100 Subject: [PATCH 47/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc Co-authored-by: Phil Wright <95368282+phil198@users.noreply.github.com> --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index c9f0b1472..c95484c61 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -535,7 +535,7 @@ It returns `null` in Community edition. | {check-mark} | home -| The home database configured by the user, otherwise `null`. +| The home database configured for the user, otherwise `null`. A home database is resolved if it is pointing to a database or a database alias. If this database is unavailable or no database is specified, the login will fail. From 70dfc138be54f33b3e6354ff5eb7f4e7472d75e2 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 10:21:32 +0100 Subject: [PATCH 48/62] Update modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc Co-authored-by: Phil Wright <95368282+phil198@users.noreply.github.com> --- modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index 066aeaf37..7800f3058 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -24,7 +24,7 @@ SSO works in the following way: . The identity provider responds with a JSON Web Token (JWT), a JSON file containing fields (claims) relative to the user (email, audience, groups, etc.). . The client provides the server with the JWT, and the server verifies its signature with the JWKs. . label:new[Introduced in 5.24] Optionally, you can control the authentication and authorization on a user level by setting xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] to `true` in the _neo4j.conf_ file and the xref:authentication-authorization/auth-providers.adoc[auth providers] for the users, which authentication and authorization you want to control, using Cypher. -The setting mandates that users representing the corresponding auth provider must exist in the database to be able to authenticate and authorize using an SSO (or any external) provider. +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. For information on how to modify or create users in this mode, see xref:authentication-authorization/manage-users.adoc[Manage users]. + This mode allows you the following using Cypher: .. Suspend SSO users. From 9ffa1391e444d44e70ec2ae8c97d863e466a20d1 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 10:21:42 +0100 Subject: [PATCH 49/62] Update modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc Co-authored-by: Phil Wright <95368282+phil198@users.noreply.github.com> --- modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index 7800f3058..bc450c119 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -137,7 +137,7 @@ dbms.security.oidc.okta.config=token_type_principal=id_token;token_type_authenti image::sso-configuration-tutorials/okta-sign-on-tab.svg[title="Okta's sign-on tab"] + . label:new[Introduced in 5.24] (Optional) If you want control the authentication and authorization on a user level, configure xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] to `true` in the _neo4j.conf_ file. -This setting mandates that users representing the corresponding auth provider must exist in the database before they can authenticate and authorize. +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. For information on how to create users in this mode, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. + For example, to create the user `jake` who can authenticate using `native` or `okta`, and authorize using Okta (as configured in step 3), you can use the following Cypher query: From a3fa7468113c3115b9635f88c09eb406cfb7e878 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 10:21:51 +0100 Subject: [PATCH 50/62] Update modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc Co-authored-by: Phil Wright <95368282+phil198@users.noreply.github.com> --- modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc index bc450c119..7677617c7 100644 --- a/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc +++ b/modules/ROOT/pages/tutorial/tutorial-sso-configuration.adoc @@ -331,7 +331,7 @@ dbms.security.oidc.azure.claims.groups=roles ---- . label:new[Introduced in 5.24] (Optional) If you want control the authentication and authorization on a user level, configure xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] to `true` in the _neo4j.conf_ file. -This setting mandates that users representing the corresponding auth provider must exist in the database before they can authenticate and authorize. +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. For information on how to create users in this mode, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. + For example, to create a user `jake` who can authenticate and authorize using Azure, you can use the following Cypher query: From 98b573fb53d761021360276411fd23dd475f07a6 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 10:22:05 +0100 Subject: [PATCH 51/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc Co-authored-by: Phil Wright <95368282+phil198@users.noreply.github.com> --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index c95484c61..2eb3ef3b7 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -751,7 +751,7 @@ WHERE provider = 'oidc1' You can create users using one of the following Cypher commands, depending on whether you want to create a new user or replace an existing one. In both cases, you can specify the user's password, whether they must change it at the next login, their status, home database, and auth provider settings. The `SET` clauses can be applied in any order. -It is mandatory to specify a `SET PASSWORD` or a `SET AUTH` clause or both because users must have at least one auth provider. +It is mandatory to specify a `SET PASSWORD` and/or at least one `SET AUTH` clause because users must have at least one auth provider. `SET AUTH` is available from Neo4j 5.24 onwards. .`CREATE USER` syntax From 58bd7a2edf070adde77caa56efa52aaec7662fd6 Mon Sep 17 00:00:00 2001 From: Therese Magnusson Date: Tue, 24 Sep 2024 11:56:57 +0200 Subject: [PATCH 52/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc Co-authored-by: Phil Wright <95368282+phil198@users.noreply.github.com> --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 2eb3ef3b7..173618872 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -223,7 +223,7 @@ Creates a new user, or if a user with the same name exists, replace it. [NOTE] ==== -It is mandatory to specify a `SET PASSWORD` or a `SET AUTH` clause or both because users must have at least one auth provider. +It is mandatory to specify a `SET PASSWORD` and/or at least one `SET AUTH` clause because users must have at least one auth provider. ==== For more information, see xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users]. From cd8f4897d74b09f4c54025b7807f4da0624f9aad Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 17:17:37 +0200 Subject: [PATCH 53/62] add native to the manage users --- .../pages/authentication-authorization/manage-users.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 173618872..a3705fef9 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -428,7 +428,7 @@ It produces a table with the following columns: | roles | Roles granted to the user. -Will return `null` in community edition. +It returns `null` in Community edition. | LIST OF STRING | {cross-mark} | {check-mark} @@ -537,7 +537,7 @@ It returns `null` in Community edition. | home | The home database configured for the user, otherwise `null`. A home database is resolved if it is pointing to a database or a database alias. -If this database is unavailable or no database is specified, the login will fail. +If the configured home database is unavailable and the user does not specify another database, the login will fail. It returns `null` in Community edition. | STRING @@ -801,7 +801,7 @@ If no home database is set, the DBMS default database is used as the home databa <6> label:new[Introduced in 5.24] One or more `SET AUTH` clause can be used to configure external xref:authentication-authorization/auth-providers.adoc[auth providers], such as LDAP or OIDC, which define authentication/authorization providers for that user. `SET AUTH` can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. -For examples, see xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers] for OIDC and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[Configure authentication/authorization at the user level using auth providers] for LDAP. +For examples, see xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers] for OIDC, xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users] for native authentication, and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[Configure authentication/authorization at the user level using auth providers] for LDAP. + [source, syntax, role="noheader"] ---- From 5943694ef95a6fee49f7aa414e5a9befb244a2c6 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 18:02:28 +0200 Subject: [PATCH 54/62] revert the set password change not required descriptions --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index a3705fef9..9935b404e 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -790,7 +790,7 @@ With `ENCRYPTED`, the password string is expected to be in the format of ` Specifies whether the user must change their password at the next login. -If omitted, the default is `CHANGE REQUIRED`. +If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted, the default is `CHANGE REQUIRED`. The `SET PASSWORD` prefix of the `CHANGE [NOT] REQUIRED` clause is only optional if it directly follows the `SET PASSWORD 'password'` clause and is not part of a `SET AUTH` clause. <4> The default for `SET STATUS` is `ACTIVE`. @@ -1015,7 +1015,7 @@ With `ENCRYPTED`, the password string is expected to be in the format of ` Specifies whether the user must change their password at the next login. -If omitted, the default is `CHANGE REQUIRED`. +If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted, the default is `CHANGE REQUIRED`. The `SET PASSWORD` prefix of the `CHANGE [NOT] REQUIRED` clause is only optional if it directly follows the `SET PASSWORD 'password'` clause and is not part of a `SET AUTH` clause. <6> The default for `SET STATUS` is `ACTIVE`. <7> Specifies a home database for a user. A home database is resolved if it is pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for that user. From 4f56af7bf3faf56509379e7a6c67fd57217c89d1 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 24 Sep 2024 18:10:01 +0200 Subject: [PATCH 55/62] refer to the examples in the respective sections --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 9935b404e..ed1cf65f5 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -801,7 +801,7 @@ If no home database is set, the DBMS default database is used as the home databa <6> label:new[Introduced in 5.24] One or more `SET AUTH` clause can be used to configure external xref:authentication-authorization/auth-providers.adoc[auth providers], such as LDAP or OIDC, which define authentication/authorization providers for that user. `SET AUTH` can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. -For examples, see xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers] for OIDC, xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users] for native authentication, and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[Configure authentication/authorization at the user level using auth providers] for LDAP. +For further informations, see the examples in this section, as well as xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers] for OIDC, and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[Configure authentication/authorization at the user level using auth providers] for LDAP. + [source, syntax, role="noheader"] ---- @@ -1022,7 +1022,7 @@ The `SET PASSWORD` prefix of the `CHANGE [NOT] REQUIRED` clause is only optional <8> label:new[Introduced in 5.24] One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[auth providers], which define authentication / authorization providers for that user. This might be used to configure external auth providers like LDAP or OIDC, but can also be used as an alternative way to set the native (password-based) auth settings like `SET PASSWORD` and `SET PASSWORD CHANGE REQUIRED`. -For examples, see <>, xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers], and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[Configure authentication/authorization at the user level using auth providers]. +For further informations, see the examples in this section, as well as xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers], and xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[Configure authentication/authorization at the user level using auth providers]. + [source, syntax, role="noheader"] ---- From 4f52fc58b1fb636d32c3c3ac02869f9d86c886a1 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 25 Sep 2024 08:59:05 +0100 Subject: [PATCH 56/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc Co-authored-by: Therese Magnusson --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index ed1cf65f5..d967be792 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -790,7 +790,7 @@ With `ENCRYPTED`, the password string is expected to be in the format of ` Specifies whether the user must change their password at the next login. -If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted, the default is `CHANGE REQUIRED`. +If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted but a password is given, the default is `CHANGE REQUIRED`. The `SET PASSWORD` prefix of the `CHANGE [NOT] REQUIRED` clause is only optional if it directly follows the `SET PASSWORD 'password'` clause and is not part of a `SET AUTH` clause. <4> The default for `SET STATUS` is `ACTIVE`. From 5a198184944997d76bffd26836313e937e7c2569 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 25 Sep 2024 10:38:46 +0100 Subject: [PATCH 57/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index d967be792..404c0c1a3 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -1015,7 +1015,7 @@ With `ENCRYPTED`, the password string is expected to be in the format of ` Specifies whether the user must change their password at the next login. -If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted, the default is `CHANGE REQUIRED`. +If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted when adding native auth to a user (either by first removing pre-existing native auth or if the user does not have native auth to start with), the default is `CHANGE REQUIRED`. The `SET PASSWORD` prefix of the `CHANGE [NOT] REQUIRED` clause is only optional if it directly follows the `SET PASSWORD 'password'` clause and is not part of a `SET AUTH` clause. <6> The default for `SET STATUS` is `ACTIVE`. <7> Specifies a home database for a user. A home database is resolved if it is pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for that user. From 9ddb616f53a930fa5be4cbadd1973bc9312e820d Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 25 Sep 2024 10:38:56 +0100 Subject: [PATCH 58/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 404c0c1a3..b570dd9e8 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -1017,7 +1017,8 @@ With `ENCRYPTED`, the password string is expected to be in the format of ` Specifies whether the user must change their password at the next login. If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted when adding native auth to a user (either by first removing pre-existing native auth or if the user does not have native auth to start with), the default is `CHANGE REQUIRED`. The `SET PASSWORD` prefix of the `CHANGE [NOT] REQUIRED` clause is only optional if it directly follows the `SET PASSWORD 'password'` clause and is not part of a `SET AUTH` clause. -<6> The default for `SET STATUS` is `ACTIVE`. +<6> Specifies the user's status. +The default is `ACTIVE`. <7> Specifies a home database for a user. A home database is resolved if it is pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for that user. <8> label:new[Introduced in 5.24] One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[auth providers], which define authentication / authorization providers for that user. From a3cfb43a4c5568e0e487da91556cf26094d0fd6b Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 25 Sep 2024 10:39:05 +0100 Subject: [PATCH 59/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index b570dd9e8..2c7bcf53d 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -793,7 +793,8 @@ With `ENCRYPTED`, the password string is expected to be in the format of ` The default for `SET STATUS` is `ACTIVE`. +<4> Specifies the user's status. +If not set, the default is `ACTIVE`. <5> Specifies a home database for a user. A home database is resolved if it is pointing to a database or a database alias. From 6cde04ecde9b87c0600841293b275635c4170ca9 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 25 Sep 2024 10:48:14 +0100 Subject: [PATCH 60/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 2c7bcf53d..e93fc05f9 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -985,6 +985,7 @@ You can modify users with the `ALTER USER` command. The command allows you to change the user's password, status, home database, and auth provider settings. The `SET` and `REMOVE` clauses can be applied in any order. However, all `REMOVE` clauses must come before the first `SET` clause and at least one `SET` or `REMOVE` clause is required for the command. +If any of the `SET` or `REMOVE` clauses are omitted, the corresponding settings will not be changed. [source, syntax, role="noheader"] ---- From ff5bcd36759814ef94484f5df2fcf649a4e9d9ca Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 25 Sep 2024 12:45:01 +0100 Subject: [PATCH 61/62] Update modules/ROOT/pages/authentication-authorization/manage-users.adoc Co-authored-by: Therese Magnusson --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index e93fc05f9..5546493f5 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -1020,7 +1020,6 @@ With `ENCRYPTED`, the password string is expected to be in the format of ` Specifies the user's status. -The default is `ACTIVE`. <7> Specifies a home database for a user. A home database is resolved if it is pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for that user. <8> label:new[Introduced in 5.24] One or more `SET AUTH` clauses can be used to set xref:authentication-authorization/auth-providers.adoc[auth providers], which define authentication / authorization providers for that user. From ab3e9d6c12aae29a48e19482a0242f11e2c08ca5 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 25 Sep 2024 13:52:20 +0200 Subject: [PATCH 62/62] add that changed required is `null` if the user has `native` auth disabled. --- .../ROOT/pages/authentication-authorization/manage-users.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/pages/authentication-authorization/manage-users.adoc b/modules/ROOT/pages/authentication-authorization/manage-users.adoc index 5546493f5..3d1c533df 100644 --- a/modules/ROOT/pages/authentication-authorization/manage-users.adoc +++ b/modules/ROOT/pages/authentication-authorization/manage-users.adoc @@ -435,6 +435,7 @@ It returns `null` in Community edition. | passwordChangeRequired | If `true`, the user must change their password at the next login. +This is `null` if the user has `native` auth disabled. | BOOLEAN | {check-mark} | {check-mark}