diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 4b8b5493d..a1fb005d4 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-providers.adoc[] *** xref:authentication-authorization/ldap-integration.adoc[] *** xref:authentication-authorization/sso-integration.adoc[] 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 diff --git a/modules/ROOT/pages/authentication-authorization/auth-providers.adoc b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc new file mode 100644 index 000000000..ca0318d8a --- /dev/null +++ b/modules/ROOT/pages/authentication-authorization/auth-providers.adoc @@ -0,0 +1,69 @@ +:description: This section explains how to use Cypher to manage authentication and authorization at the user level using Cypher. +:page-role: enterprise-edition new-5.24 + +[[access-control-auth-providers]] += User auth providers + +Authentication and authorization can be controlled on a user level using Cypher by setting auth providers on users. + +To use auth providers, you need to set the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true`. +This setting mandates that users with the relevant auth provider attached to them must exist in the database before they can authenticate and authorize with that auth provider. + +User auth providers allow you to link externally-defined users (e.g., in a third-party ID provider like OIDC or LDAP) to the Neo4j internal user model. +The internal model can define roles (authorization), `SUSPENDED` status, `HOME DATABASE`, and metadata such as the unique displayed name of the user. +For consistency, you can also define `native` (password-based) auth using the auth provider syntax, including native-only users (i.e., users who can only authenticate with a password). + +== Use cases + +User auth providers can be used for a variety of use cases, including: + +* Provisioning different auth providers (including native username/password auth) for different users. +* Setting an arbitrary easy username for a user while using an external unique identifier (like `sub` for OIDC auths, which itself is not a user-friendly value). +* Setting `HOME DATABASE` for externally authenticated users. +* Setting `SUSPENDED` status for an externally authenticated user. +* Using native authorization to manage roles for externally authenticated users. +* Retaining full control of which users can authenticate from within the database. + +== How it works + +When a user authenticates, their identifying attributes are checked against the relevant property of the auth providers in the database. +If there is a match, then the user is linked to the Neo4j user and authorized according to the DBMS security configuration settings that match the name of the matching auth provider. + +How the matching lookup is done depends on the type of provider. +For example: + +* For an OIDC provider, the claim configured by xref:configuration/configuration-settings.adoc#config_dbms.security.oidc.-provider-.claims.username[`dbms.security.oidc.mysso.claims.username`] (default `sub`) is taken from the token and is used to look up an auth provider whose `ID` and `provider` properties match the `sub` and provider respectively of the OIDC provider. +* For an LDAP provider, the `dn` is used to look up an auth provider with a `provider` property of `ldap` and an `ID` property that matches the supplied `dn`. +* For the `native` (username/password) provider, the supplied username itself is used to look up the auth provider. + +== Enabling user auth providers mode + +To enable user auth providers mode, set the configuration setting xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] to `true`. +This setting mandates that users with the relevant auth provider attached to them must exist in the database before they can authenticate and authorize with that auth provider. + +When the user authenticates, Neo4j searches for a user with a matching authentication provider. +If a match is found, the user can log in and be authorized successfully. + +== Migrating to auth providers mode + +If you have existing users in the database and want to migrate to auth providers mode, you can use the `ALTER USER ... SET AUTH` command to attach an auth provider to each of them. +Until you change `dbms.security.require_local_user` to `true`, this will not impact the users' ability to authenticate and authorize as they always have done. + +Once the process of adding auth providers to your users finishes, you can set `dbms.security.require_local_user` to `true` and restart the DBMS to complete the migration. +After this time, only users with a corresponding auth provider in the database will be able to authenticate and authorize. + +[NOTE] +==== +Existing users created using the original `CREATE USER ... SET PASSWORD` command implicitly have the native (username/password) auth provider, so you do not need to add it explicitly using `SET AUTH`. + +To verify which auth providers are attached to a user, use the xref:authentication-authorization/manage-users.adoc#access-control-list-users[`SHOW USERS WITH AUTH`] command. +==== + +== Examples + +For examples of how to use auth providers with different authentication providers, see the following sections: + +- xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers] +- xref:authentication-authorization/manage-users.adoc#access-control-create-users[Creating users] +- xref:authentication-authorization/ldap-integration.adoc#auth-ldap-auth-providers[Configure authentication/authorization at the user level using LDAP as an auth provider] + diff --git a/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc b/modules/ROOT/pages/authentication-authorization/dbms-administration.adoc index 1b7ef3ba9..b861c3b44 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: @@ -466,6 +466,12 @@ GRANT [IMMUTABLE] SET PASSWORD[S] TO role[, ...] | Enables the specified roles to modify users' passwords and whether those passwords must be changed upon first login. +| [source, syntax, role=noheader] +GRANT [IMMUTABLE] SET AUTH + ON DBMS + TO role[, ...] +| label:new[Introduced in 5.24] Enables the specified roles to `SET` or `REMOVE` users' xref:authentication-authorization/auth-providers.adoc[auth providers]. + | [source, syntax, role=noheader] GRANT [IMMUTABLE] SET USER HOME DATABASE ON DBMS @@ -571,7 +577,7 @@ SHOW ROLE userModifier PRIVILEGES AS COMMANDS a|Rows: 1 |=== -A user that is granted the `ALTER USER` privilege is allowed to run the `ALTER USER` administration command with one or several of the `SET PASSWORD`, `SET PASSWORD CHANGE [NOT] REQUIRED` and `SET STATUS` parts: +A user that is granted the `ALTER USER` privilege is allowed to run the `ALTER USER` administration command with one or several of the `SET PASSWORD`, `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET AUTH`, `REMOVE AUTH` and `SET STATUS` parts: [source, cypher, role=noplay] ---- @@ -609,6 +615,14 @@ A user that is granted the `SET PASSWORDS` privilege is allowed to run the `ALTE ALTER USER jake SET PASSWORD 'abcd5678' CHANGE NOT REQUIRED ---- +label:new[Introduced in 5.24] A user that is granted the `SET AUTH` privilege is allowed to run the `ALTER USER` administration command with one or both of the `SET AUTH` and `REMOVE AUTH` parts: + +[source, cypher, role=noplay] +---- +ALTER USER jake REMOVE AUTH 'native SET AUTH 'oidc-okta' { SET id 'jakesUniqueOktaUserId' } +---- + + The ability to modify the account status of users can be granted via the `SET USER STATUS` privilege. See an example: @@ -679,7 +693,7 @@ ALTER USER jake REMOVE HOME DATABASE [NOTE] ==== -Note that the combination of the `SET PASSWORDS`, `SET USER STATUS`, and the `SET USER HOME DATABASE` privilege actions is equivalent to the `ALTER USER` privilege action. +Note that the combination of the `SET PASSWORDS`, `SET AUTH`, `SET USER STATUS`, and the `SET USER HOME DATABASE` privilege actions is equivalent to the `ALTER USER` privilege action. ==== The ability to delete users can be granted via the `DROP USER` privilege. diff --git a/modules/ROOT/pages/authentication-authorization/index.adoc b/modules/ROOT/pages/authentication-authorization/index.adoc index a837f1b81..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,6 +97,15 @@ This is in contrast to a suspended user. [[term-administrator]]administrator:: This is a user who has been assigned the admin role. +[[term-auth-provider]]auth provider:: +Properties attached to a user which define which authentication and authorization config to use for that user. + +[[term-authentication]]authentication:: +The process of verifying the identity of a user, typically using credentials like a username and password or a cryptographic token like a JWT. + +[[term-authorization]]authorization:: +The process of determining a user's access rights and privileges within Neo4j, based on their verified identity. + [[term-current-user]]current user:: This is the currently logged-in user invoking the commands. diff --git a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc index a1d6e608f..e658c194d 100644 --- a/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc +++ b/modules/ROOT/pages/authentication-authorization/ldap-integration.adoc @@ -3,30 +3,6 @@ = LDAP integration :description: This page describes Neo4j support for integrating with LDAP systems. -This page describes Neo4j support for integrating with LDAP systems. -The following topics are covered: - -* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-introduction[Introduction] -* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-parameters[LDAP configuration parameters] -* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider[Set Neo4j to use LDAP] -* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-map-ldap-roles[Map the LDAP groups to the Neo4j roles] -* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider-ad[Configure Neo4j to use Active Directory] -** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider-ad-uid[Configure Neo4j to support LDAP user ID authentication] -** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider-ad-sysaccount[Configure Neo4j to support attribute authentication] -** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider-ad-nosysaccount[Configure Neo4j to support `sAMAccountName` authentication by setting `user_dn_template`] -** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-nested-groups[Configure Neo4j to perform nested group lookup] -* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-configure-provider-openldap[Configure Neo4j to use OpenLDAP] -* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-search[Verify the LDAP configuration] -* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-clear-auth-cache[The auth cache] -* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-ad-encrypted[Available methods of encryption] -** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-encrypted-starttls[Use LDAP with encryption via StartTLS] -** xref:authentication-authorization/ldap-integration.adoc#auth-ldap-encrypted-ldaps[Use LDAP with encrypted LDAPS] -* xref:authentication-authorization/ldap-integration.adoc#auth-ldap-self-signed-certificate[Use a self-signed certificate (SSL) in a test environment] - - -[[auth-ldap-introduction]] -== Introduction - Neo4j supports LDAP, which allows for integration with Active Directory (AD), OpenLDAP, or other LDAP-compatible authentication services. This means that you use the LDAP service for managing federated users, while the native Neo4j user and role administration are completely turned off. @@ -104,7 +80,7 @@ This way, the LDAP connector is used as a security provider for both authenticat If you want, you can still use the `native` provider for mixed-mode authentication and authorization. The values are comma-separated and queried in the declared order. + -.Configure Neo4j to use LDAP and the native authentication and authorization provider. +.Configure Neo4j to use LDAP and the native authentication and authorization provider ====== [source,configuration,role="noheader"] ---- @@ -358,6 +334,136 @@ dbms.security.ldap.authorization.access_permitted_group=501 . Map the groups in the LDAP system to the Neo4j built-in and custom roles. For more information, see xref:authentication-authorization/ldap-integration.adoc#auth-ldap-map-ldap-roles[Map the LDAP groups to the Neo4j roles]. +[role=label--new-5.24] +[[auth-ldap-auth-providers]] +== Configure authentication/authorization at the user level using auth providers +xref:authentication-authorization/auth-providers.adoc[User auth providers] can be used to determine which users can authenticate and authorize using the configured providers, including LDAP. + +You must change the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true` to use auth providers. +This means that a user with a matching auth provider *must* exist in order to be able to authenticate and authorize. +This applies to all providers. + +Conversely, when xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] is set to `false`, users' auth providers have no bearing on the way that they are authenticated and authorized, instead authentication and authorization is controlled centrally (for all users) by the database configuration. + +The following examples show how to configure users with auth provider `ldap` using Cypher. + +.Create a user with an auth provider who can authenticate and authorize using `LDAP` +====== +[source,cypher,role=noplay] +---- +CREATE USER alice +SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } +---- + +The command creates the user `alice` who can authenticate and authorize using LDAP provided their LDAP `dn` is `cn=alice,ou=engineering,dc=example,dc=com`. +====== + +.Create a user with two auth providers allowing the user to authenticate and authorize with either LDAP or the `mysso` provider +====== + +[source,cypher,role=noplay] +---- +CREATE USER alice +SET HOME DATABASE anotherDb +SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } +SET AUTH 'oidc-mysso' {SET ID 'alicesUniqueMySsoId'} +---- + +The command creates the user `alice` who can authenticate and authorize using `ldap` or `mysso`. +See xref:authentication-authorization/sso-integration.adoc#auth-sso-auth-providers[Configure SSO at the user level using auth providers] for more information on setting up an OIDC provider. +The example also illustrates that the user can have their home database set even when using only external auth providers. +====== + +.Alter a user to remove one of their auth providers +====== + +[source,cypher,role=noplay] +---- +ALTER USER alice +REMOVE AUTH 'ldap' +---- + +The command prevents the user `alice` from being able to authenticate and authorize using `ldap`. +====== + +.Alter a user to allow them to authenticate and authorize using username and password +====== + +[source,cypher,role=noplay] +---- +ALTER USER alice +SET AUTH 'native' {SET PASSWORD 'changeme' SET PASSWORD CHANGE REQUIRED} +---- + +The command allows the user `alice` to authenticate and authorize using the specified username and password (in addition to what they are already configured to use). +====== + + +.Configure the database to allow authentication via `ldap` and authorization via the `native` provider +====== + +. Set the following database config: ++ +[source, properties] +---- +dbms.security.authentication_providers=ldap +dbms.security.authorization_providers=native +---- + +. Create a user with an `ldap` auth provider: ++ +[source,cypher,role=noplay] +---- +CREATE USER alice +SET AUTH PROVIDER 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } +---- + +. Natively grant the `READER` role to the user: ++ +[source,cypher,role=noplay] +---- +GRANT ROLE READER TO alice +---- ++ +The command allows the user `alice` to authenticate using `ldap` and receive the `READER` role from the `native` provider. + +. You can also give the user the union of roles from `ldap` *and* `native` roles by setting `ldap` as an authorization provider too: ++ +[source, properties] +---- +dbms.security.authentication_providers=ldap +dbms.security.authorization_providers=native,ldap +---- +====== + +.Suspend a user +====== +[source,cypher,role=noplay] +---- +ALTER USER alice +SET STATUS SUSPENDED + +---- +The command completely prevents the user from being able to authenticate/authorize by any means. +====== + +.Disambiguate users with the same name in different LDAP trees +====== + +Suppose there are two users both with the name `alice`, one is part of the `engineering` tree (`cn=alice,ou=engineering,dc=example,dc=com`) and the other is part of the `sales` tree (`cn=alice,ou=sales,dc=example,dc=com`). + +To disambiguate these users, you can create two users in the database, each with a different `ID` that corresponds to the `dn` of the user in the LDAP tree. + +[source,cypher,role=noplay] +---- +CREATE USER aliceEngineering +SET AUTH 'ldap' { SET ID 'cn=alice,ou=engineering,dc=example,dc=com' } + +CREATE USER aliceSales +SET AUTH 'ldap' { SET ID 'cn=alice,ou=sales,dc=example,dc=com' } +---- +====== + [[auth-ldap-search]] == Verify the LDAP configuration 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 028734333..3d1c533df 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]] @@ -91,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]. |=== @@ -117,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| @@ -126,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]. |=== @@ -147,16 +148,34 @@ 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 }..."}"]... # 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' # only applicable to the 'native' provider + \| SET PASSWORD CHANGE [NOT] REQUIRED # only applicable to the 'native' provider + } +"}" ---- | Description a| Creates a new user. +[NOTE] +==== +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]. | Required privilege @@ -166,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]. |=== @@ -180,16 +199,33 @@ 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 }..."}"]... # 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' # only applicable to the 'native' provider + \| SET PASSWORD CHANGE [NOT] REQUIRED # only applicable to the 'native' provider + } +"}" ---- | Description a| Creates a new user, or if a user with the same name exists, replace it. +[NOTE] +==== +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]. | Required privilege @@ -199,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"] @@ -207,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]. |=== @@ -236,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]. |=== @@ -250,18 +286,33 @@ 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] - [REMOVE HOME DATABASE] + [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 + } +"}" ---- | Description 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. + +* 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]. @@ -272,7 +323,7 @@ a| GRANT SET PASSWORD ---- -[source, privilege, role="noheader" +[source, privilege, role="noheader"] ---- GRANT SET USER STATUS ---- @@ -282,7 +333,12 @@ GRANT SET USER STATUS GRANT SET USER HOME DATABASE ---- -(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) +[source, privilege, role="noheader"] +---- +GRANT SET AUTH +---- + +For more information, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]. |=== @@ -338,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,^.^,^.^"] |=== @@ -371,13 +428,14 @@ The currently logged-in user can be seen using `SHOW CURRENT USER`, which will p | 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} | 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} @@ -385,7 +443,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} @@ -394,7 +452,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} @@ -425,14 +483,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 of users 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,^.^,^.^"] |=== @@ -449,15 +508,21 @@ 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. + +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]. -Will return `null` in community edition. +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. + +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 is `null` if the user has `native` auth disabled. | BOOLEAN | {check-mark} | {check-mark} @@ -465,22 +530,30 @@ 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 for the user, otherwise `null`. +A home database is resolved if it is pointing to a database or a database alias. +If the configured home database is unavailable and the user does not specify another database, the login will fail. -Will return `null` in community edition. +It returns `null` in Community edition. | STRING | {cross-mark} | {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 you must change the password after the first login. +==== + +.Show users +====== [source, cypher, role=noplay] ---- SHOW USERS @@ -500,14 +573,16 @@ SHOW USERS |false |false | - -5+a|Rows: 1 +|"jake" +|["PUBLIC"] +|false +|false +| +5+a|Rows: 2 |=== +====== -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. - -.Show user +.Show user with column reorder and filtering ====== This example shows how to: @@ -519,9 +594,26 @@ This example shows how to: 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 +.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`. @@ -532,63 +624,201 @@ 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 +|=== ====== -[NOTE] -==== -The `SHOW USER name PRIVILEGES` command is described in xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. -==== +[role=label--new-5.24] +[[access-control-list-user-auth-providers]] +== Listing user auth providers + +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="1a,4,1m,^.^,^.^"] +|=== +| 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. +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} +| {check-mark} +|=== + +.Show users with auth +====== +[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: 3 +|=== +====== + +.Show user with auth using filtering +====== +Show all users with the `oidc` auth provider. +[source,cypher,role=noplay] +---- +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 +|=== +====== [[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` 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 [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] +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 # <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 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> 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. +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 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"] ---- -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 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` part is only optional if it directly follows the `SET PASSWORD` 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. -* The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, and `SET HOME DATABASE` 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. @@ -608,10 +838,20 @@ 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] +---- +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: @@ -622,11 +862,26 @@ SET ENCRYPTED PASSWORD '1,6d57a5e0b3317055454e455f96c98c750c77fb371f3f0634a1b8ff SET STATUS ACTIVE ---- +[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 +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` 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. @@ -641,6 +896,14 @@ CREATE USER jake IF NOT EXISTS 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: + +[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 +919,14 @@ 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: + +[source,cypher,role=noplay] +---- +CREATE OR REPLACE USER jake +SET AUTH 'native' {SET PLAINTEXT PASSWORD 'abcd1234'} +---- ====== [NOTE] @@ -674,6 +945,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 @@ -709,77 +982,164 @@ 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. +If any of the `SET` or `REMOVE` clauses are omitted, the corresponding settings will not be changed. [source, syntax, role="noheader"] ---- -ALTER USER name [IF EXISTS] - [SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password'] - [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE | SUSPENDED}] - [SET HOME DATABASE name] - [REMOVE HOME DATABASE name] ----- - -* At least one `SET` or `REMOVE` clause is required for the command. -* `SET` and `REMOVE` clauses cannot be combined in the same command. -* The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, and `SET HOME DATABASE` clauses can be applied in any order. -The `SET PASSWORD` clause must come first, if used. -* 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]. + +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`. -* If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted, the default is `CHANGE REQUIRED`. -The `SET PASSWORD` part is only optional if it directly follows the `SET PASSWORD` clause. -* For `SET PASSWORD CHANGE [NOT] REQUIRED`, the `SET PASSWORD` is only optional if it directly follows the `SET PASSWORD` 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. -* `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. - -For example, you can modify the user `bob` with a new password and active status, and remove the requirement to change his password: +** `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 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> Specifies the user's status. +<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 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"] +---- +SET AUTH [PROVIDER] '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 + } +"}" +---- -[source, cypher, role=noplay] + +.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 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-providers.adoc[auth providers] 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 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 +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: + +---- +ALTER USER bob +SET AUTH 'native' {SET PASSWORD CHANGE REQUIRED} +---- +====== + +[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 +REMOVE AUTH 'native' +SET AUTH 'oidc-mysso1' {SET ID 'bobsUniqueMySso1Id'} +---- +====== + +[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 +REMOVE ALL AUTH +SET AUTH 'oidc-mysso1' {SET ID 'bobsUniqueMySso1Id'} +SET AUTH 'oidc-mysso2' {SET ID 'bobsUniqueMySso2Id'} +---- +====== + +.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 SET HOME DATABASE anotherDbOrAlias ---- +====== -Or remove the home database from the user `bob`: +.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] +[source,cypher,role=noplay] ---- ALTER USER bob REMOVE HOME DATABASE +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`, 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`, 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`: @@ -850,9 +1210,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 eafd92cb1..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,10 +251,11 @@ 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 Provider +=== 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. @@ -267,8 +268,118 @@ In this configuration, Neo4j receives a token from the identity provider and use 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]] +=== 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. + +You must change the xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] configuration setting to `true` to use auth providers. +This means that a user with a matching auth provider *must* exist in order to be able to authenticate and authorize. +This applies to all providers. + +Conversely, when xref:configuration/configuration-settings.adoc#config_dbms.security.require_local_user[`dbms.security.require_local_user`] is set to `false`, users' auth providers have no bearing on the way that they are authenticated and authorized, instead authentication and authorization is controlled centrally (for all users) by the database configuration. + +The following examples show how to configure users with auth provider using Cypher. + +.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 +---- + +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 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 +---- +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 +====== +[source,cypher,role=noplay] +---- +ALTER USER jake +REMOVE AUTH 'oidc-mysso2' +---- +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} +---- +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 +====== + +. Set the following database config: ++ +[source, properties] +---- +dbms.security.authentication_providers=oidc-mysso +dbms.security.authorization_providers=native +---- + +. 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 +---- + +. 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. + +. 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 + +---- +The command completely prevents the user from being able to authenticate/authorize by any means. +====== + [[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 dd35db08f..4632700ac 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -4614,6 +4614,21 @@ 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` + +.dbms.security.require_local_user +[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. +|Valid values +a|A boolean. +|Default value +m|+++false+++ +|=== + [[config_dbms.netty.ssl.provider]] === `dbms.netty.ssl.provider` 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 97be538ce..7677617c7 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,7 +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. -+ +. 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. +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. +.. 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]. + [IMPORTANT] ==== JWTs must *always* contain a value for `sub` even when using a different claim for `username`. @@ -124,6 +135,23 @@ 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"] ++ +. 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 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: ++ +[source, cypher, role=noplay] +---- +CREATE USER jake +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[Configure SSO at the user level using auth providers] for further examples. + == Microsoft Entra ID (formerly Azure Active Directory) @@ -140,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[] @@ -263,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] ---- @@ -279,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] ---- @@ -302,10 +330,27 @@ dbms.security.oidc.azure.authorization.group_to_role_mapping= "managers" = admin 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 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: ++ +[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[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: + @@ -319,15 +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. ==== -. 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: +. Configure Neo4j to use Google authentication by setting the following configurations in the _neo4j.conf_ file: + [source, properties] ---- @@ -343,15 +380,109 @@ 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"] +. 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] + +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] ==== -The native authentication is disabled to prevent someone from logging in to _alice@neo4j-test.com_ with the set password. +An admin user with the name `neo4j` is created by default when the database is xref:configuration/set-initial-password.adoc[first started]. ==== +. 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 +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 only using `oidc-google`: ++ +[source, cypher, role=noplay] +---- +CREATE USER jake +SET HOME DATABASE 'jakesHomeDb' +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 `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. + +. 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 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 +---- + +. 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 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 # <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: ++ +[source, cypher, role=noplay] +---- +GRANT ROLE reader TO jakesUniqueGoogleUserId +---- +====== +===== + == FAQ === When should `pkce` be used as auth flow?