From 1100792c2dbf4b1486e56163e5591e06ec4b47e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A1bio=20Botelho?= Date: Wed, 4 Sep 2024 11:10:19 +0100 Subject: [PATCH 01/11] Add seed docs for Azure (#1743) Co-authored-by: Reneta Popova --- .../ROOT/pages/backup-restore/aggregate.adoc | 16 +++++++++- .../pages/backup-restore/offline-backup.adoc | 15 +++++++++- .../pages/backup-restore/online-backup.adoc | 16 ++++++++-- .../pages/backup-restore/restore-backup.adoc | 14 +++++++++ .../pages/backup-restore/restore-dump.adoc | 13 +++++++++ .../neo4j-admin/consistency-checker.adoc | 16 +++++++++- .../tools/neo4j-admin/neo4j-admin-import.adoc | 15 +++++++++- modules/ROOT/partials/azb-credentials.adoc | 29 +++++++++++++++++++ 8 files changed, 128 insertions(+), 6 deletions(-) create mode 100644 modules/ROOT/partials/azb-credentials.adoc diff --git a/modules/ROOT/pages/backup-restore/aggregate.adoc b/modules/ROOT/pages/backup-restore/aggregate.adoc index 1fb818c8f..a1eb65de1 100644 --- a/modules/ROOT/pages/backup-restore/aggregate.adoc +++ b/modules/ROOT/pages/backup-restore/aggregate.adoc @@ -162,4 +162,18 @@ The example assumes that you have a backup chain located in the `myBucket/myDire bin/neo4j-admin database aggregate-backup --from-path=gs://myBucket/myDirectory/myBackup.backup mydatabase ---- ====== -===== \ No newline at end of file + +[.include-with-Azure-cloud-storage] +====== + +include::partial$/azb-credentials.adoc[] + +. Then, use the following command to aggregate the backup chain located in a given folder in your Azure blob storage container. +The example assumes that you have a backup chain located with a `myStorageAccount/myContainer/myDirectory` folder identifiable by the file `myBackup.backup`: ++ +[source,shell] +---- +bin/neo4j-admin database aggregate-backup --from-path=azb://myStorageAccount/myContainer/myDirectory/myBackup.backup mydatabase +---- +====== +===== diff --git a/modules/ROOT/pages/backup-restore/offline-backup.adoc b/modules/ROOT/pages/backup-restore/offline-backup.adoc index 09d5c1996..e663d535e 100644 --- a/modules/ROOT/pages/backup-restore/offline-backup.adoc +++ b/modules/ROOT/pages/backup-restore/offline-backup.adoc @@ -156,4 +156,17 @@ include::partial$/gcs-credentials.adoc[] bin/neo4j-admin database dump mydatabase --to-path=gs://myBucket/myDirectory/ ---- ====== -===== \ No newline at end of file + +[.include-with-Azure-cloud-storage] +====== + +include::partial$/azb-credentials.adoc[] + +. Run `neo4j-admin database dump` command to dump your database into your Azure container: ++ +[source,shell] +---- +bin/neo4j-admin database dump mydatabase --to-path=azb://myStorageAccount/myContainer/myDirectory/ +---- +====== +===== diff --git a/modules/ROOT/pages/backup-restore/online-backup.adoc b/modules/ROOT/pages/backup-restore/online-backup.adoc index a04fda974..c26388a1a 100644 --- a/modules/ROOT/pages/backup-restore/online-backup.adoc +++ b/modules/ROOT/pages/backup-restore/online-backup.adoc @@ -227,7 +227,7 @@ While the server is checkpointing, the backup job receives no data, which may le To extend the backup timeout, modify the xref:configuration/configuration-settings.adoc#config_dbms.cluster.catchup.client_inactivity_timeout[`dbms.cluster.catchup.client_inactivity_timeout`] setting, which restricts the network inactivity. It controls the timeout duration of the catchup protocol, which is the underlying protocol of multiple catchup processes, including backups. -You can also tune up xref:configuration/configuration-settings.adoc#_checkpoint_settings[the Checkpoint settings] or check that your disks are performant enough to handle the load. +You can also tune up xref:configuration/configuration-settings.adoc#_checkpoint_settings[the Checkpoint settings] or check that your disks are performant enough to handle the load. For more information, see xref:performance/disks-ram-and-other-tips.adoc#performance-checkpoint-iops-limit[Checkpoint IOPS limit]. To read more about checkpointing, see xref:database-internals/checkpointing.adoc[Database internals -> Checkpointing and log pruning]. @@ -429,4 +429,16 @@ include::partial$/gcs-credentials.adoc[] bin/neo4j-admin database backup --to-path=gs://myBucket/myDirectory/ mydatabase ---- ====== -===== \ No newline at end of file +[.include-with-Azure-cloud-storage] +====== + +include::partial$/azb-credentials.adoc[] + +. Run `neo4j-admin database backup` command to back up your database to your Azure container: ++ +[source,shell] +---- +bin/neo4j-admin database backup --to-path=azb://myStorageAccount/myContainer/myDirectory/ mydatabase +---- +====== +===== diff --git a/modules/ROOT/pages/backup-restore/restore-backup.adoc b/modules/ROOT/pages/backup-restore/restore-backup.adoc index b505238bf..0cbd725da 100644 --- a/modules/ROOT/pages/backup-restore/restore-backup.adoc +++ b/modules/ROOT/pages/backup-restore/restore-backup.adoc @@ -253,6 +253,20 @@ The example assumes that you have backup artifacts located in the `myBucket/myDi bin/neo4j-admin database restore --to-path=gs://myBucket/myDirectory/myBackup.backup mydatabase ---- ====== + +[.include-with-Azure-cloud-storage] +====== + +include::partial$/azb-credentials.adoc[] + +. Run the `neo4j-admin database restore` command to restore the database located in a given folder in your Azure blob storage container. +The example assumes that you have backup artifacts located in the `myStorageAccount/myContainer/myDirectory` folder. ++ +[source,shell] +---- +bin/neo4j-admin database restore --to-path=azb://myStorageAccount/myContainer/myDirectory/myBackup.backup mydatabase +---- +====== ===== === Restore a database backup in a cluster diff --git a/modules/ROOT/pages/backup-restore/restore-dump.adoc b/modules/ROOT/pages/backup-restore/restore-dump.adoc index 09d33f8c4..f4e675f22 100644 --- a/modules/ROOT/pages/backup-restore/restore-dump.adoc +++ b/modules/ROOT/pages/backup-restore/restore-dump.adoc @@ -195,5 +195,18 @@ The example assumes that you have dump artifacts located in the `myBucket/myDire bin/neo4j-admin database load mydatabase --from-path=gs://myBucket/myDirectory/ --overwrite-destination=true ---- ====== +[.include-with-Azure-cloud-storage] +====== + +include::partial$/azb-credentials.adoc[] + +. Run the `neo4j-admin database load` command to load a dump from your Azure blob storage container. +The example assumes that you have dump artifacts located in the `myStorageAccount/myContainer/myDirectory` folder in your Azure account. ++ +[source,shell] +---- +bin/neo4j-admin database load mydatabase --from-path=azb://myStorageAccount/myContainer/myDirectory --overwrite-destination=true +---- +====== ===== diff --git a/modules/ROOT/pages/tools/neo4j-admin/consistency-checker.adoc b/modules/ROOT/pages/tools/neo4j-admin/consistency-checker.adoc index 95ea753ed..1f446eb4e 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/consistency-checker.adoc +++ b/modules/ROOT/pages/tools/neo4j-admin/consistency-checker.adoc @@ -242,4 +242,18 @@ The example assumes that you have backup or dump artifacts located in the `myBuc bin/neo4j-admin database check mydatabase --from-path=gs://myBucket/myDirectory/ ---- ====== -===== \ No newline at end of file + +[.include-with-Azure-cloud-storage] +====== + +include::partial$/azb-credentials.adoc[] + +. Run the `bin/neo4j-admin database check` command to check the consistency of your database located in your Azure blob storage container. +The example assumes that you have backup or dump artifacts located in the `myStorageAccount/myContainer/myDirectory` folder in Azure. ++ +[source,shell] +---- +bin/neo4j-admin database check mydatabase --from-path=azb://myStorageAccount/myContainer/myDirectory/ +---- +====== +===== diff --git a/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-import.adoc b/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-import.adoc index 87bfdfb24..bcc9da218 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-import.adoc +++ b/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-import.adoc @@ -478,8 +478,21 @@ The example assumes that you have data stored in the `myBucket/data` folder in y bin/neo4j-admin database import full --nodes gs://myBucket/data/nodes.csv --relationships gs://myBucket/data/relationships.csv newdb ---- ====== -===== +[.include-with-Azure-cloud-storage] +====== + +include::partial$/azb-credentials.adoc[] + +. Run the `neo4j-admin database import` command to import your data from your Azure blob storage container. +The example assumes that you have data stored in the `myStorageAccount/myContainer/data` folder in your container. ++ +[source,shell] +---- +bin/neo4j-admin database import full --nodes azb://myStorageAccount/myContainer/data/nodes.csv --relationships azb://myStorageAccount/myContainer/data/relationships.csv newdb +---- +====== +===== [role=label--enterprise-edition] [[import-tool-incremental]] diff --git a/modules/ROOT/partials/azb-credentials.adoc b/modules/ROOT/partials/azb-credentials.adoc new file mode 100644 index 000000000..86e097efb --- /dev/null +++ b/modules/ROOT/partials/azb-credentials.adoc @@ -0,0 +1,29 @@ +. Ensure you have an Azure account, an Azure storage account, and a blob container. +.. You can create a storage account using the Azure portal. + +For more information, see the Azure official documentation on link:https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal[Create a storage account]. +.. Create a blob container in the Azure portal. + +For more information, see the Azure official documentation on link:https://learn.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal[Quickstart: Upload, download, and list blobs with the Azure portal]. +. Install the Azure CLI by following the instructions in the Azure official documentation -- link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli[Azure official documentation]. +. Authenticate the neo4j or neo4j-admin process against Azure using the default Azure credentials. + +See the Azure official documentation on link:https://learn.microsoft.com/en-us/java/api/com.azure.identity.defaultazurecredential?view=azure-java-stable[default Azure credentials] for more information. + ++ +[source,shell] +---- +az login +---- ++ +Then you should be ready to use Azure URLs in either neo4j or neo4j-admin. + +. To validate that you have access to the container with your login credentials, run the following commands: ++ +[source,shell] +---- +# Upload a file: +az storage blob upload --file someLocalFile --account-name accountName - --container someContainer --name remoteFileName --auth-mode login + +# Download the file +az storage blob download --account-name accountName --container someContainer --name remoteFileName --file downloadedFile --auth-mode login + +# List container files +az storage blob list --account-name someContainer --container someContainer --auth-mode login +---- From ea7f533d64f81a67812671b1ab9db945854945d0 Mon Sep 17 00:00:00 2001 From: Phil Wright <95368282+phil198@users.noreply.github.com> Date: Wed, 25 Sep 2024 13:14:17 +0100 Subject: [PATCH 02/11] User Auth Providers (#1745) This PR is for the examples and general description of the User Auth Providers feature. Its currently applicable to native auth, LDAP and OIDC. --------- Co-authored-by: Therese Magnusson Co-authored-by: Reneta Popova --- modules/ROOT/content-nav.adoc | 1 + ..._grant_and_deny_syntax_dbms_privileges.svg | 10 +- .../ROOT/images/privileges_hierarchy_dbms.svg | 11 +- .../auth-providers.adoc | 69 ++ .../dbms-administration.adoc | 22 +- .../authentication-authorization/index.adoc | 13 + .../ldap-integration.adoc | 156 ++++- .../manage-roles.adoc | 2 +- .../manage-users.adoc | 600 ++++++++++++++---- .../sso-integration.adoc | 127 +++- .../configuration/configuration-settings.adoc | 15 + modules/ROOT/pages/tutorial/index.adoc | 2 +- .../tutorial/tutorial-sso-configuration.adoc | 173 ++++- 13 files changed, 1002 insertions(+), 199 deletions(-) create mode 100644 modules/ROOT/pages/authentication-authorization/auth-providers.adoc diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index a4e5a8f8e..ace1804e8 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -184,6 +184,7 @@ *** xref:authentication-authorization/manage-execute-permissions.adoc[] ** xref:authentication-authorization/built-in-roles.adoc[] ** Integration with auth systems +*** xref:authentication-authorization/auth-providers.adoc[] *** xref:authentication-authorization/ldap-integration.adoc[] *** xref:authentication-authorization/sso-integration.adoc[] 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 73ec58327..b6e964ea7 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -4620,6 +4620,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? From dc278bf5f58d62235376e0e2904fda551335f76b Mon Sep 17 00:00:00 2001 From: Frannie-Ludmilla Date: Mon, 26 Aug 2024 10:29:27 +0200 Subject: [PATCH 03/11] Add docs related to public --temp-path option in backup related commands (#1768) This PR is related to adding a new `--temp-path` option that was merged in https://github.com/neo-technology/neo4j/pull/26359 --------- Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/backup-restore/aggregate.adoc | 8 ++++++-- modules/ROOT/pages/backup-restore/online-backup.adoc | 11 +++++++---- modules/ROOT/pages/backup-restore/restore-backup.adoc | 8 ++++++-- 3 files changed, 19 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/aggregate.adoc b/modules/ROOT/pages/backup-restore/aggregate.adoc index a1eb65de1..295e1c721 100644 --- a/modules/ROOT/pages/backup-restore/aggregate.adoc +++ b/modules/ROOT/pages/backup-restore/aggregate.adoc @@ -27,8 +27,8 @@ This operation is called _recovery_ and can be costly. neo4j-admin database aggregate-backup [-h] [--expand-commands] [--verbose] [--keep-old-backup[=true|false]] [--parallel-recovery[=true|false]] - [--additional-config=] - --from-path= [] + [--additional-config=] --from-path= + [--temp-path=] [] ---- === Description @@ -89,6 +89,10 @@ Note: this is an EXPERIMENTAL option. Consult Neo4j support before use. |false +|--temp-path= +|Provide a path to a temporary empty directory for storing backup files until the command is completed. The files will be deleted once the command is finished. +| + |--verbose |Enable verbose output. | diff --git a/modules/ROOT/pages/backup-restore/online-backup.adoc b/modules/ROOT/pages/backup-restore/online-backup.adoc index c26388a1a..dd78dd39d 100644 --- a/modules/ROOT/pages/backup-restore/online-backup.adoc +++ b/modules/ROOT/pages/backup-restore/online-backup.adoc @@ -76,10 +76,9 @@ neo4j-admin database backup [-h] [--expand-commands] [--verbose] [--parallel-recovery[=true|false]] [--additional-config=] [--include-metadata=none|all|users|roles] - [--inspect-path=] [--pagecache=] - [--to-path=] [--type=] - [--from=[,...]]... - [...] + [--inspect-path=] [--pagecache=] [--temp-path=] + [--to-path=] [--type=] [--from=[,...]]... [...] ---- === Description @@ -171,6 +170,10 @@ It is recommended to use `SHOW USERS`, `SHOW ROLES`, and `SHOW ROLE $role PRIVIL Note: this is an EXPERIMENTAL option. Consult Neo4j support before use. |false +|--temp-path= +|Provide a path to a temporary empty directory for storing backup files until the command is completed. The files will be deleted once the command is finished. +| + |--to-path= |Directory to place backup in (required unless `--inspect-path` is used). | diff --git a/modules/ROOT/pages/backup-restore/restore-backup.adoc b/modules/ROOT/pages/backup-restore/restore-backup.adoc index 0cbd725da..9481018e7 100644 --- a/modules/ROOT/pages/backup-restore/restore-backup.adoc +++ b/modules/ROOT/pages/backup-restore/restore-backup.adoc @@ -40,9 +40,9 @@ neo4j-admin database restore [-h] [--expand-commands] [--verbose] [--overwrite-destination[=true|false]] [--additional-config=] --from-path=[,...] - [--restore-until=] + [--restore-until=] [--temp-path=] [--to-path-data=] [--to-path-txn=] - [] + [] ---- === Parameters @@ -113,6 +113,10 @@ Usage of this option is only allowed if the `--from-path` parameter points to ex Usage of this option is only allowed if the `--from-path` parameter points to exactly one directory. | +|--temp-path= +|Provide a path to a temporary empty directory for storing backup files until the command is completed. The files will be deleted once the command is finished. +| + |--verbose |Enable verbose output. | From f66fd0923daf932d9b01ae4f53ccda2ecdafb706 Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Thu, 22 Aug 2024 15:55:19 +0200 Subject: [PATCH 04/11] Update the version to 5.24 (#1789) --- antora.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/antora.yml b/antora.yml index 6452fa2d7..b1a06a020 100644 --- a/antora.yml +++ b/antora.yml @@ -7,7 +7,7 @@ nav: asciidoc: attributes: neo4j-version: '5' - neo4j-version-minor: '5.23' - neo4j-version-exact: '5.23.0' - neo4j-buildnumber: '5.23' + neo4j-version-minor: '5.24' + neo4j-version-exact: '5.24.0' + neo4j-buildnumber: '5.24' neo4j-debian-package-version: '1:5.22.0@' From 2d1be99b09fed1fabd2e90099546c574f2851b24 Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 27 Aug 2024 10:51:44 +0200 Subject: [PATCH 05/11] Change the signature for the `dbms.cluster.checkConnectivity` procedure (#1791) related to the [PR#26817](https://github.com/neo-technology/neo4j/pull/26817) --- modules/ROOT/pages/reference/procedures.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/reference/procedures.adoc b/modules/ROOT/pages/reference/procedures.adoc index 62d26a511..c7664cc7d 100644 --- a/modules/ROOT/pages/reference/procedures.adoc +++ b/modules/ROOT/pages/reference/procedures.adoc @@ -1676,7 +1676,7 @@ Check the connectivity of this instance to other cluster members. Not all ports are relevant to all members. Valid values for 'port-name' are: [CLUSTER, RAFT]. | Signature -m|dbms.cluster.checkConnectivity(port-name = null :: STRING, server = null :: STRING) :: (serverId :: STRING, mode-constraint :: STRING, port-name :: STRING, port-address :: STRING, result :: STRING) +m|dbms.cluster.checkConnectivity(port-name = null :: STRING, server = null :: STRING) :: (serverId :: STRING, name :: STRING, address :: STRING, mode-constraint :: STRING, port-name :: STRING, port-address :: STRING, result :: STRING) | Mode m|DBMS |=== From d2d157b3017c9bce3a10a8d8921dc291f2b705d3 Mon Sep 17 00:00:00 2001 From: Stefanos Giagkiozis Date: Fri, 6 Sep 2024 11:57:37 +0100 Subject: [PATCH 06/11] Add docker compose documentation (#1804) https://trello.com/c/MgmtbjRJ/1470-support-docker-secrets * Adds documentation for general docker compose usage * Adds documentation for using secrets with neo4j --------- Co-authored-by: Reneta Popova --- modules/ROOT/content-nav.adoc | 1 + .../docker/docker-compose-standalone.adoc | 106 ++++++++++++++++++ modules/ROOT/pages/docker/index.adoc | 2 + 3 files changed, 109 insertions(+) create mode 100644 modules/ROOT/pages/docker/docker-compose-standalone.adoc diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index ace1804e8..a1fb005d4 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -21,6 +21,7 @@ ** xref:docker/mounting-volumes.adoc[] ** xref:docker/configuration.adoc[] ** xref:docker/plugins.adoc[] +** xref:docker/docker-compose-standalone.adoc[] ** xref:docker/clustering.adoc[] ** xref:docker/operations.adoc[] ** xref:docker/dump-load.adoc[] diff --git a/modules/ROOT/pages/docker/docker-compose-standalone.adoc b/modules/ROOT/pages/docker/docker-compose-standalone.adoc new file mode 100644 index 000000000..8f52cdf08 --- /dev/null +++ b/modules/ROOT/pages/docker/docker-compose-standalone.adoc @@ -0,0 +1,106 @@ +:description: Running Neo4j in a Docker container using Docker Compose +[[docker-compose-neo4j-standalone]] += Deploy a Neo4j standalone server using Docker Compose + +You can deploy a Neo4j standalone server using Docker Compose by defining the container configuration in a _docker-compose.yml_ file and authenticating with basic authentication or Docker secrets. + +[[docker-compose-basic-authentication]] +== Deploy a Neo4j server using basic authentication mechanism + +Before you start, verify that you have installed Docker Compose. +For more information, see the https://docs.docker.com/compose/install/[Install Docker Compose official documentation]. + +. Create a project folder where you will store your _docker-compose.yml_ file and run your Neo4j server. +. Prepare your _docker-compose.yml_ file using the following example. +For more information, see the Docker Compose official documentation on https://docs.docker.com/compose/compose-file/#service-configuration-reference[Docker Compose specification]. ++ +.Example of a _docker-compose.yml_ file +[source,yaml,subs="attributes+,+macros"] +---- +services: + neo4j: + image: neo4j:latest + volumes: # <1> + - /$HOME/neo4j/logs:/logs + - /$HOME/neo4j/config:/config + - /$HOME/neo4j/data:/data + - /$HOME/neo4j/plugins:/plugins + environment: + - NEO4J_AUTH=neo4j/your_password # <2> + ports: + - "7474:7474" + - "7687:7687" + restart: always +---- +<1> Mount the _/$HOME/neo4j/<..>:_ directories to local directories on your host machine to store logs, configuration, data, and plugins. +For more information about mounting volumes, see xref:docker/mounting-volumes.adoc[]. +<2> Set the `neo4j` username and password. + +. Deploy your Neo4j server by running `docker-compose up` from your project folder. ++ +[source,shell,subs="attributes+,+macros"] +---- +docker-compose up -d +---- ++ +The `-d` flag starts the container in detached mode. + +[role=label--recommended] +[[docker-compose-secrets]] +== Deploy a Neo4j server with Docker secrets + +It is advisable not to store sensitive information, such as the database username and password, in the _docker-compose.yml_ file. +You can instead store your credentials in files and use them in your _docker-compose.yml_ file without exposing their values. + +. Create a file, for example, _neo4j_auth.txt_, containing the username and password for the Neo4j server to be used as a Docker secret. ++ +[source,text,subs="attributes"] +---- +neo4j:your_password +---- +. Prepare your _docker-compose.yml_ file using the following example. +For more information, see the Docker Compose official documentation on https://docs.docker.com/compose/compose-file/#service-configuration-reference[Docker Compose specification]. ++ +.Example of a _docker-compose.yml_ file +[source,yaml,subs="attributes+,+macros"] +---- +services: + neo4j: + image: neo4j:latest + volumes: # <1> + - /$HOME/neo4j/logs:/logs + - /$HOME/neo4j/config:/config + - /$HOME/neo4j/data:/data + - /$HOME/neo4j/plugin:/plugins + environment: + - NEO4J_AUTH_FILE=/run/secrets/neo4j_auth_file # <2> + ports: + - "7474:7474" + - "7687:7687" + restart: always + secrets: + - neo4j_auth_file #<3> +secrets: + neo4j_auth_file: # <4> + file: ./neo4j_auth.txt # <5> +---- +<1> Mount the _/$HOME/neo4j/<..>:_ directories to local directories on your host machine to store logs, configuration, data, and plugins. +<2> Path to the file where the value for the `NEO4J_AUTH` environment variable can be found. +<3> The name of the secret, for example `neo4j_auth_file`. +<4> Path to the _neo4j_auth.txt_ file. +<5> The name of the secret in the `neo4j` service. ++ +[WARNING] +==== +The secret value overrides the equivalent environment variable if they are both defined. +So, for example, if you also define an environment variable `NEO4J_AUTH=neo4j/your_other_password` in the `environment` section of the `neo4j` service, the value of `NEO4J_AUTH_FILE` will be the one used. +==== + +. Deploy your Neo4j server by running `docker-compose up` from your project folder. ++ +[source,shell,subs="attributes+,+macros"] +---- +docker-compose up -d +---- ++ +The `-d` flag starts the container in detached mode. \ No newline at end of file diff --git a/modules/ROOT/pages/docker/index.adoc b/modules/ROOT/pages/docker/index.adoc index f73a641a8..40e68f252 100644 --- a/modules/ROOT/pages/docker/index.adoc +++ b/modules/ROOT/pages/docker/index.adoc @@ -10,6 +10,7 @@ This chapter describes the following: * xref:docker/mounting-volumes.adoc[Persisting data with Docker volumes] -- How and where to mount persistent storage to the Docker container. * xref:docker/configuration.adoc[Modify the default configuration] -- How to configure Neo4j to run in a Docker container. * xref:docker/plugins.adoc[Plugins] -- How to load plugins when using Neo4j in Docker. +* xref:docker/docker-compose-standalone.adoc[Deploy a Neo4j server with Docker Compose] -- How to set up a Neo4j server with Docker Compose using a basic authentication mechanism or Docker secrets. * xref:docker/clustering.adoc[Deploy a Neo4j cluster on Docker] -- How to set up and deploy a Neo4j cluster on Docker. * xref:docker/operations.adoc[Docker specific operations] -- Descriptions of various `neo4j-admin` and `cypher-shell` operations that are specific to using Docker. * xref:docker/dump-load.adoc[Offline dump and load] -- How to perform dump and load of a containerized Neo4j database. @@ -17,6 +18,7 @@ This chapter describes the following: * xref:docker/security.adoc[Security] -- Information about using encryption with a Neo4j Docker image. * xref:docker/ref-settings.adoc[Docker specific configuration settings] -- A conversion table for the Neo4j configuration settings to Docker format. + [NOTE] ==== Docker does not run natively on macOS or Windows. From 697f452a1665036cbe3808779826e0c22b6b1bca Mon Sep 17 00:00:00 2001 From: Therese Magnusson Date: Tue, 24 Sep 2024 17:46:12 +0200 Subject: [PATCH 07/11] Add `DROP DATABASE name CASCADE ALIASES` (#1805) to drop any aliases blocking the deletion of the database Documenting https://github.com/neo-technology/neo4j/pull/26465, ~~needs to wait until that has been merged.~~ --------- Co-authored-by: Mark Dixon <1756429+mnd999@users.noreply.github.com> Co-authored-by: Reneta Popova --- .../manage-aliases-composite-databases.adoc | 1 + .../delete-composite-databases.adoc | 55 +++++++++++++++++- .../standard-databases/delete-databases.adoc | 56 ++++++++++++++++++- .../pages/database-administration/syntax.adoc | 2 +- 4 files changed, 108 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc b/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc index e1ca3e7f3..b8901f7e1 100644 --- a/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc +++ b/modules/ROOT/pages/database-administration/aliases/manage-aliases-composite-databases.adoc @@ -160,6 +160,7 @@ SHOW ALIASES FOR DATABASE YIELD * +-----------------------------------------------------------------------------------------------------------------------------------+ ---- +[[delete-composite-database-alias]] == Delete database aliases in composite databases To delete an alias in a composite database, use the `DROP ALIAS FOR DATABASE` command. diff --git a/modules/ROOT/pages/database-administration/composite-databases/delete-composite-databases.adoc b/modules/ROOT/pages/database-administration/composite-databases/delete-composite-databases.adoc index d1710a640..60b50b553 100644 --- a/modules/ROOT/pages/database-administration/composite-databases/delete-composite-databases.adoc +++ b/modules/ROOT/pages/database-administration/composite-databases/delete-composite-databases.adoc @@ -3,8 +3,17 @@ [[composite-databases-delete]] = Delete composite databases -You can delete composite databases using either the command `DROP COMPOSITE DATABASE name` or the more general one `DROP DATABASE name`. -However, keep in mind that the first command will fail if the target database is not composite, while the second one will not fail because it targets any database. +There are two ways of deleting a composite database with constituent database aliases (local or remote) by either dropping the constituent database aliases first and then deleting the composite database, or deleting the composite database while also dropping the constituent database aliases. + +[[composite-databases-delete-without-aliases]] +== Delete a composite database + +Before deleting a composite database, you must ensure that it is not in use by any database aliases. +If the composite database is in use, you must first drop the aliases that reference it. +For more information, see xref:database-administration/aliases/manage-aliases-composite-databases.adoc#delete-composite-database-alias[Delete database aliases in composite databases]. + +You can delete composite databases using either the command `DROP COMPOSITE DATABASE name` or the more general one `DROP DATABASE name`. +However, keep in mind that the first command targets only composite databases, while the second one targets any database. .Query [source, cypher] @@ -12,3 +21,45 @@ However, keep in mind that the first command will fail if the target database is DROP COMPOSITE DATABASE inventory ---- +[role=label--new-5.24] +[[composite-databases-delete-with-aliases]] +== Delete a composite database while dropping its constituents + +You can use the `CASCADE ALIASES` option of the `DROP COMPOSITE DATABASE` Cypher command to drop the constituent database aliases while deleting the composite database. + +[NOTE] +==== +This operation does not deletes the actual target databases of the constituent database aliases. +==== + +The `CASCADE ALIASES` option is useful when you want to delete a composite database and its constituent database aliases in one step. +Using `CASCADE ALIASES` requires the `DROP ALIAS` privilege. +For more information about this privilege, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[ALIAS MANAGEMENT privileges]. + +.Drop a composite database and its consitutent alias +==== +This example shows how to create a composite database `movies` and a database alias `movies.sweden` for the database `swedish-movies` and then delete the alias `sweden` and the composite database `movies`. + +.Create a composite database `movies` and a database alias `movies.sweden` for the database `swedish-movies` +[source, cypher] +---- +CREATE COMPOSITE DATABASE movies +CREATE ALIAS movies.sweden FOR DATABASE `swedish-movies` +---- + +.Delete the composite database `movies` while also dropping the alias `movies.sweden` +[source, cypher] +---- +DROP COMPOSITE DATABASE movies CASCADE ALIASES +---- +==== + +This behavior is the same for the more general command `DROP DATABASE name` when using it to drop a composite database. + +//The option `RESTRICT` explicitly requests the default behavior of the command. + +[NOTE] +==== +For composite databases, the aliases that are dropped when using the `CASCADE ALIASES` option can be found in the `constituents` column of `SHOW DATABASE`. +==== + diff --git a/modules/ROOT/pages/database-administration/standard-databases/delete-databases.adoc b/modules/ROOT/pages/database-administration/standard-databases/delete-databases.adoc index 47667ff2f..71cbe26b5 100644 --- a/modules/ROOT/pages/database-administration/standard-databases/delete-databases.adoc +++ b/modules/ROOT/pages/database-administration/standard-databases/delete-databases.adoc @@ -17,7 +17,7 @@ Note that all database aliases must be dropped before dropping a database. | [source, syntax, role="noheader"] ---- -DROP [COMPOSITE] DATABASE name [IF EXISTS] [{DUMP\|DESTROY} [DATA]] [WAIT [n [SEC[OND[S]]]]\|NOWAIT] +DROP [COMPOSITE] DATABASE name [IF EXISTS] [RESTRICT \| CASCADE ALIAS[ES]] [{DUMP\|DESTROY} [DATA]] [WAIT [n [SEC[OND[S]]]]\|NOWAIT] ---- |=== @@ -92,9 +92,9 @@ In Neo4j, dumps can be stored in the directory specified by the xref:configurati The option `DESTROY DATA` explicitly requests the default behavior of the command. [[delete-existing-db-with-dump]] -=== Delete a database with `IF{nbsp}EXISTS` and `DUMP DATA`/ `DESTROY DATA` +=== Delete a database with `IF{nbsp}EXISTS` and `DUMP DATA`/`DESTROY DATA` -The options `IF EXISTS` and `DUMP DATA`/ `DESTROY DATA` can also be combined. +The options `IF EXISTS` and `DUMP DATA`/`DESTROY DATA` can also be combined. An example could look like this: @@ -103,4 +103,54 @@ An example could look like this: DROP DATABASE customers IF EXISTS DUMP DATA ---- +[[delete-databases-with-aliases]] +=== Delete a database with local database aliases targeting it + +There are two ways of dropping a database that is the target of local database aliases: + +* Drop the local database aliases first, then use `DROP DATABASE name` to drop the database. +Remote database aliases targeting the database do not affect the deletion of the database and therefore dos not need to be dropped beforehand. +* Use `DROP DATABASE name CASCADE ALIASES` to also drop the local database aliases targeting it while dropping the database. +If any of the dropped database aliases are constituents of composite databases, those composite databases will not be dropped. +This command does not affect the remote database aliases targeting the database being dropped. +They will simply no longer resolve their targets as if they were created targeting a non-existing database. + +Using `CASCADE ALIASES` requires the `DROP ALIAS` privilege. +For more information about the privilege, see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-alias-management[ALIAS MANAGEMENT privileges]. + +.Drop a database and the local database alias targeting it +==== +The following example creates a database `movies` and a local database alias `films` targeting it: + +[source, cypher] +---- +CREATE DATABASE movies +CREATE ALIAS films FOR DATABASE movies +---- + +Then, the database `movies` and the local database alias `films` can be dropped using the following command: + +[source, cypher] +---- +DROP DATABASE movies CASCADE ALIASES +---- +==== + +The option `RESTRICT` explicitly requests the default behavior of the command. + +[NOTE] +==== +For standard databases, the aliases that are dropped when using the `CASCADE ALIASES` option can be found in the `aliases` column of `SHOW DATABASE`. +==== + +[[delete-existing-databases-with-aliases]] +=== Delete a database with `RESTRICT`/`CASCADE ALIASES` and other command parts + +The options `RESTRICT`/`CASCADE ALIASES` can also be combined with `IF EXISTS` and `DUMP DATA`/`DESTROY DATA`. +For example: + +[source, cypher] +---- +DROP DATABASE movies IF EXISTS CASCADE ALIASES DUMP DATA +---- diff --git a/modules/ROOT/pages/database-administration/syntax.adoc b/modules/ROOT/pages/database-administration/syntax.adoc index e6c3ac7e9..ad6054aa0 100644 --- a/modules/ROOT/pages/database-administration/syntax.adoc +++ b/modules/ROOT/pages/database-administration/syntax.adoc @@ -176,7 +176,7 @@ START DATABASE name [WAIT [n [SEC[OND[S]]]]\|NOWAIT] | [source, syntax, role="noheader"] ---- -DROP [COMPOSITE] DATABASE name [IF EXISTS] [{DUMP\|DESTROY} [DATA]] [WAIT [n [SEC[OND[S]]]]\|NOWAIT] +DROP [COMPOSITE] DATABASE name [IF EXISTS] [RESTRICT \| CASCADE ALIAS[ES]] [{DUMP\|DESTROY} [DATA]] [WAIT [n [SEC[OND[S]]]]\|NOWAIT] ---- |=== From fc67e60fdee42fab52cd71ef5c4155093a83308d Mon Sep 17 00:00:00 2001 From: Tony Butterfield <1846725+tonbut@users.noreply.github.com> Date: Fri, 20 Sep 2024 21:06:32 +0100 Subject: [PATCH 08/11] Added detail on backup compression flag (#1808) This support case shows how a customer is misled by absolute description of backup being faster when compression is disabled. https://trello.com/c/xsCLZrwy/7747-s3dbs-risk-management5181-backup-is-taking-more-time-with-compressfalse --------- Co-authored-by: Reneta Popova --- modules/ROOT/pages/backup-restore/online-backup.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/online-backup.adoc b/modules/ROOT/pages/backup-restore/online-backup.adoc index dd78dd39d..595f2c285 100644 --- a/modules/ROOT/pages/backup-restore/online-backup.adoc +++ b/modules/ROOT/pages/backup-restore/online-backup.adoc @@ -121,8 +121,7 @@ If is "*", `neo4j-admin` will attempt to back up all databases of the | |--compress[=true\|false] -|Request backup artifact to be compressed. If disabled, backup artifact creation is faster but -the size of the produced artifact will be approximately equal to the size of backed-up database. +|Request backup artifact to be compressed. Compression can yield a backup artefact many times smaller, but the exact reduction depends upon many factors, including the database format and the kind of data stored. If disabled, the size of the produced artifact will be approximately equal to the size of the backed-up database. The speed of the backup operation is affected by compression, but which is faster depends upon the relative performance of CPU and storage. If backup speed is important, consider evaluating both options - with compression enabled and disabled. |true | --expand-commands From 2dbaa7ffb61a43388c56b736894de8f2f27d7509 Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Thu, 19 Sep 2024 12:44:14 +0200 Subject: [PATCH 09/11] Add new procedures `dbms.cluster.recreateDatabase`, `dbms.cluster.statusCheck` (#1816) --- modules/ROOT/pages/reference/procedures.adoc | 38 +++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/reference/procedures.adoc b/modules/ROOT/pages/reference/procedures.adoc index c7664cc7d..7dd7a2f0a 100644 --- a/modules/ROOT/pages/reference/procedures.adoc +++ b/modules/ROOT/pages/reference/procedures.adoc @@ -318,6 +318,16 @@ In 4.2, signature changed to `db.listLocks() :: (mode :: STRING, resourceType :: | label:yes[] | label:new[Introduced in 5.23] label:server-management[`SERVER MANAGEMENT` privilege only] +| xref:reference/procedures.adoc#procedure_dbms_cluster_recreateDatabase[`dbms.cluster.recreateDatabase()`] +| label:no[] +| label:yes[] +| label:new[Introduced in 5.24] + +| xref:reference/procedures.adoc#procedure_dbms_cluster_statusCheck[`dbms.cluster.statusCheck()`] +| label:no[] +| label:yes[] +| label:new[Introduced in 5.24] label:admin-only[] + | xref:reference/procedures.adoc#procedure_dbms_components[`dbms.components()`] | label:yes[] | label:yes[] @@ -1974,6 +1984,33 @@ m|WRITE This procedure requires the `SERVER MANAGEMENT` privilege. +[[procedure_dbms_cluster_recreateDatabase]] +[role=label--enterprise-edition label--new-5.24] +.dbms.cluster.recreateDatabase() +[cols="<15s,<85"] +|=== +| Description +a|Recreates a database while keeping all RBAC settings. +The procedure initiates a process, which when complete, will have synchronized and started all database instances within the cluster. +| Signature +m|dbms.cluster.recreateDatabase(database :: STRING, options = {} :: MAP) +| Mode +a|WRITE +|=== + +[[procedure_dbms_cluster_statusCheck]] +[role=label--enterprise-edition label--new-5.24 label--admin-only] +.dbms.cluster.statusCheck() +[cols="<15s,<85"] +|=== +| Description +a|Performs a rafted status check. +| Signature +m|dbms.cluster.statusCheck(databases :: LIST, timeoutMilliseconds = null :: INTEGER) :: (database :: STRING, serverId :: STRING, serverName :: STRING, address :: STRING, replicationSuccessful :: BOOLEAN, memberStatus :: STRING, recognisedLeader :: STRING, recognisedLeaderTerm :: INTEGER, requester :: BOOLEAN, error :: STRING) +| Mode +a|DBMS +|=== + [[procedure_dbms_components]] .dbms.components() [cols="<15s,<85"] @@ -2232,7 +2269,6 @@ a|WRITE |=== - [[procedure_dbms_scheduler_failedjobs]] [role=label--enterprise-edition label--admin-only] .dbms.scheduler.failedJobs() From 425a27333a8a1514f98367b78b301c1a565db533 Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 24 Sep 2024 14:48:09 +0200 Subject: [PATCH 10/11] Add docs on the recreate procedure (#1819) Co-authored-by: Balazs Lendvai <56266523+gfx54b@users.noreply.github.com> Co-authored-by: Anna Sjerling <102957391+AnnaSjerling@users.noreply.github.com> --- modules/ROOT/pages/clustering/databases.adoc | 123 +++++++++++++++++++ modules/ROOT/pages/clustering/index.adoc | 2 +- 2 files changed, 124 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/databases.adoc b/modules/ROOT/pages/clustering/databases.adoc index 87ed8f282..fb0ddc566 100644 --- a/modules/ROOT/pages/clustering/databases.adoc +++ b/modules/ROOT/pages/clustering/databases.adoc @@ -225,6 +225,129 @@ neo4j@neo4j> DRYRUN REALLOCATE DATABASES; +----------------------------------------------------------------------------------------------------------------------------------------+ ---- +[role=label--new-5.24] +[[recreate-databases]] +== Recreate a database + +Neo4j 5.24 introduces the xref:reference/procedures.adoc#procedure_dbms_cluster_recreateDatabase[`dbms.cluster.recreateDatabase()`] procedure, which allows you: + +* To change the database store to a specified backup, while keeping all the associated privileges for the database. + +* To make your database write-available again after it has been lost (for example, due to a disaster). +// See xref:clustering/disaster-recovery.adoc[] for more information. + +[CAUTION] +==== +The recreate procedure works only for real user databases and not for composite databases, or the `system` database. + +Remember that the recreate procedure results in downtime while the stores get updated. +The time is unbounded and may depend on different factors -- for example, the size of the store, network speed, etc. +==== + +The database in question can be in an `online` or `offline` state when it is recreated, but a successful operation starts the database regardless of its previous state. + +If your database has Change Data Capture (CDC) enabled, the CDC chain will stop when the database is recreated, even though CDC remains enabled in the recreated database. +To restore CDC functionality, follow the guide on how link:https://neo4j.com/docs/cdc/current/existing-databases/[to initialize CDC applications from an existing database]. + +Before recreating a database, any eventual quarantined states need to be addressed. +For more information, see xref:database-administration/standard-databases/errors.adoc#quarantine[Standard databases -> Error handling]. + +You need xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[the `CREATE DATABASE` and `DROP DATABASE` privileges] to run the recreate procedure. + +To check if the recreation is successful, use the `SHOW DATABASES` command and verify that all allocations have been started. + +Additionally, you have the option to modify <> during the recreation process. +However, note that the store format, access, and enrichment cannot be altered during recreation. + +[[recreate-seeding-options]] +=== Seeding options + +The store to be used during the recreation of a database can be defined in different ways. +One method uses a backup, while others use available allocations in the cluster. + +You can use either <> or <> to specify the source from which the database should be recreated. + +* If you define neither, an error is thrown. + +* If you define both of them, then `seedingServers` must be an empty list. +See <> for more details. + +* If `seedingServers` is not empty and `seedURI` is also defined, an error will occur. + +[[uri-seed]] +==== Use backup as a seed + +If you provide a URI to a backup or a dump, the stores on all allocations will be replaced by the backup or the dump at the given URI. +The new allocations can be put on any `ENABLED` server in the cluster. +See <> for more details. + + +[source, shell] +---- +CALL dbms.cluster.recreateDatabase("neo4j", {seedURI: "s3:/myBucket/myBackup.backup"}); +---- + +[[seed-servers]] +==== Use available servers as a seed + +After the recreation is complete, the database will have the latest data store from the seeding servers. + +[CAUTION] +==== +Recreation is based on remaining stores or a store defined by the user. +This means that stores which were lost or not defined are not used for the recreation. +If not used stores were more up to date than the used ones, this results in data loss. +==== + +[[specified-servers]] +===== Specified servers + +You can specify a set of available servers. +The stores on all allocations will be synchronized to the most up-to-date store from the defined servers. +The number of defined servers cannot exceed the number of total allocations in the desired topology. + +[source, shell] +---- +CALL dbms.cluster.recreateDatabase("neo4j", {seedingServers: ["serverId1", "serverId2", "serverId3"]}); +---- + +[[undefined-servers]] +===== Undefined servers + +If you provide an empty list of seeding servers and do not specify a `seedURI`, Neo4j automatically selects all available allocations of the database as seeders. +The store will be replaced by the most up-to-date seeder available in the cluster. + +[source, shell] +---- +CALL dbms.cluster.recreateDatabase("neo4j", {seedingServers: []}); +---- + +[[undefined-servers-backup]] +===== Undefined servers with fallback backup + +If both an empty list of seeding servers and a `seedURI` are provided, Neo4j finds all available allocations of the database and use those as seeders. +However, if no available servers can be found, the database is recreated based on the backup or the dump defined by the URI. +This means the store is replaced by the most up-to-date seeder if available; otherwise, the backup is used. + +[source, shell] +---- +CALL dbms.cluster.recreateDatabase("neo4j", {seedingServers: [], seedURI: "s3:/myBucket/myBackup.backup"}); +---- + +[[alter-topology-recreate]] +=== Change the topology + +There is an option to define a new topology when recreating a database. +This can be beneficial during a disaster, if enough servers are not available to recreate the database with the original topology. +When altering the total number of allocations down during a recreation, it is important to remember that the number of seeding servers cannot exceed the number of total allocations of the database. +This also holds true when using recreate with an empty list of seeders. +If there are more available servers in the cluster hosting the database than the number of new allocations, the recreation will fail. + +[source, shell] +---- +CALL dbms.cluster.recreateDatabase("neo4j", {seedingServers: [], primaries: 3, secondaries: 0}); +---- + [[cluster-seed]] == Seed a cluster diff --git a/modules/ROOT/pages/clustering/index.adoc b/modules/ROOT/pages/clustering/index.adoc index 5e181cdf4..2d56ef214 100644 --- a/modules/ROOT/pages/clustering/index.adoc +++ b/modules/ROOT/pages/clustering/index.adoc @@ -9,7 +9,7 @@ This chapter describes the following: * Setting up a cluster -- The basics of configuring and deploying a new cluster. ** xref:clustering/setup/deploy.adoc[Deploy a basic cluster] -- How to set up a basic cluster. ** xref:clustering/setup/analytics-cluster.adoc[Deploy an analytics cluster] -- How to deploy a special case Neo4j cluster for analytic queries. -** xref:clustering/setup/single-to-cluster.adoc[Move from single server to cluster] -- This section describes how to move from a single Neo4j server to Neo4j cluster. +** xref:clustering/setup/single-to-cluster.adoc[Move from a standalone deployment to a cluster] -- This section describes how to move from a single Neo4j server to Neo4j cluster. ** xref:clustering/setup/discovery.adoc[Cluster server discovery] -- How servers in a cluster discover each other and form a cluster. ** xref:clustering/setup/routing.adoc[Leadership, routing and load balancing] -- Election of leaders, routing and load balancing. ** xref:clustering/setup/encryption.adoc[Intra-cluster encryption] -- How to secure the cluster communication. From 22b84e6dd43a67d74d2776a07cbdc45c35b07830 Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Thu, 26 Sep 2024 11:05:11 +0200 Subject: [PATCH 11/11] Add `--schema` to the neo4j-admin import tool (#1822) --- .../tools/neo4j-admin/neo4j-admin-import.adoc | 48 +++++++++++++++++-- 1 file changed, 45 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-import.adoc b/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-import.adoc index bcc9da218..32ecc2d3e 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-import.adoc +++ b/modules/ROOT/pages/tools/neo4j-admin/neo4j-admin-import.adoc @@ -64,6 +64,10 @@ These are some things you need to keep in mind when creating your input files: ==== Indexes and constraints are not created during the import. Instead, you have to add these afterward (see link:{neo4j-docs-base-uri}/cypher-manual/{page-version}/indexes-for-full-text-search[Cypher Manual -> Indexes]). + +Starting from Neo4j 5.24, you can use the `--schema` option to create indexes and contraints during the import process. +The option is available in the Enterprise Edition and works only for the block format. +See <> for more information. ==== [[import-tool-full]] @@ -85,9 +89,9 @@ neo4j-admin database import full [-h] [--expand-commands] [--verbose] [--auto-sk [--bad-tolerance=] [--delimiter=] [--format=] [--high-parallel-io=on|off|auto] [--id-type=string|integer|actual] [--input-encoding=] [--max-off-heap-memory=] [--quote=] - [--read-buffer-size=] [--report-file=] [--threads=] --nodes=[