diff --git a/modules/ROOT/pages/access-control/manage-users.adoc b/modules/ROOT/pages/access-control/manage-users.adoc index cc314eee6..6faf44a28 100644 --- a/modules/ROOT/pages/access-control/manage-users.adoc +++ b/modules/ROOT/pages/access-control/manage-users.adoc @@ -23,7 +23,7 @@ m| SHOW CURRENT USER | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- SHOW CURRENT USER [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] @@ -35,7 +35,7 @@ SHOW CURRENT USER a| Lists the current user. -When using the `RETURN` clause, the `YIELD` clause is mandatory and may not be omitted. +When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. For more information, see xref::access-control/manage-users.adoc#access-control-current-users[Listing current user]. @@ -53,7 +53,7 @@ m| SHOW USERS | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- SHOW USERS [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] @@ -63,15 +63,15 @@ SHOW USERS | Description a| -List all users. +Lists all users. -When using the `RETURN` clause, the `YIELD` clause is mandatory and may not be omitted. +When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. For more information, see xref::access-control/manage-users.adoc#access-control-list-users[Listing users]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT SHOW USER ---- @@ -88,7 +88,7 @@ m| SHOW USER PRIVILEGES | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- SHOW USER[S] [name[, ...]] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] @@ -98,28 +98,29 @@ SHOW USER[S] [name[, ...]] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] | Description a| -List the privileges granted to the specified users or the current user if no user is specified. +Lists the privileges granted to the specified users or the current user if no user is specified. -When using the `RETURN` clause, the `YIELD` clause is mandatory and may not be omitted. +When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. For more information, see xref::access-control/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT SHOW PRIVILEGE ---- -[source, privilege, role="noheader", indent=0] +(see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[DBMS PRIVILEGE MANAGEMENT privileges]) + +|=== + +[source, privilege, role="noheader"] ---- GRANT SHOW USER ---- -(see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[DBMS PRIVILEGE MANAGEMENT privileges]) - (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) - |=== [cols="<15s,<85"] @@ -129,7 +130,7 @@ m| CREATE USER | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- CREATE USER name [IF NOT EXISTS] SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' @@ -140,13 +141,13 @@ CREATE USER name [IF NOT EXISTS] | Description a| -Create a new user. +Creates a new user. For more information, see xref::access-control/manage-users.adoc#access-control-create-users[Creating users]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT CREATE USER ---- @@ -162,7 +163,7 @@ m| CREATE OR REPLACE USER | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- CREATE OR REPLACE USER name SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' @@ -173,18 +174,22 @@ CREATE OR REPLACE USER name | Description a| -Create a new user, or if a user with the same name exists, replace it. +Creates a new user, or if a user with the same name exists, replace it. For more information, see xref::access-control/manage-users.adoc#access-control-create-users[Creating users]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT CREATE USER ---- -[source, privilege, role="noheader", indent=0] +(see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) + +|=== + +[source, privilege, role="noheader"] ---- GRANT DROP USER ---- @@ -200,20 +205,20 @@ m| RENAME USER | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- RENAME USER name [IF EXISTS] TO otherName ---- | Description a| -Change the name of a user. +Changes the name of a user. For more information, see xref::access-control/manage-users.adoc#access-control-rename-users[Renaming users]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT RENAME USER ---- @@ -229,7 +234,7 @@ m| ALTER USER | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- ALTER USER name [IF EXISTS] [SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'] @@ -241,23 +246,25 @@ ALTER USER name [IF EXISTS] | Description a| -Modify 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. +Modifies the settings for an existing user. +At least one `SET` or `REMOVE` clause is required. +`SET` and `REMOVE` clauses cannot be combined in the same command. For more information, see xref::access-control/manage-users.adoc#access-control-alter-users[Modifying users]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT SET PASSWORD ---- -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader" ---- GRANT SET USER STATUS ---- -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT SET USER HOME DATABASE ---- @@ -275,14 +282,14 @@ m| ALTER CURRENT USER SET PASSWORD | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- ALTER CURRENT USER SET PASSWORD FROM 'oldPassword' TO 'newPassword' ---- | Description a| -Change the current user's password. +Changes the current user's password. For more information, see xref::access-control/manage-users.adoc#access-control-alter-password[Changing the current user's password]. @@ -300,20 +307,20 @@ m| DROP USER | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- DROP USER name [IF EXISTS] ---- | Description a| -Remove an existing user. +Removes an existing user. For more information, see xref::access-control/manage-users.adoc#access-control-drop-users[Delete users]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT DROP USER ---- @@ -332,7 +339,7 @@ The `SHOW USER[S] PRIVILEGES` command is only available in Neo4j Enterprise Edit [[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: +The currently logged-in user can be seen using `SHOW CURRENT USER`, which will produce a table with the following columns: [options="header", width="100%", cols="2a,4,^.^,^.^"] |=== @@ -362,13 +369,13 @@ The currently logged-in user can be seen using `SHOW CURRENT USER` which will pr | {check-mark} | home -| The home database configured for 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. +| 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. | {cross-mark} | {check-mark} |=== -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW CURRENT USER ---- @@ -400,7 +407,7 @@ This command is only supported for a logged-in user and will return an empty res [[access-control-list-users]] == Listing users -Available users can be seen using `SHOW USERS` which will produce a table of users with the following columns: +Available users can be seen using `SHOW USERS`, which will produce a table of users with the following columns: [options="header", width="100%", cols="2a,4,^.^,^.^"] |=== @@ -430,14 +437,14 @@ Available users can be seen using `SHOW USERS` which will produce a table of use | {check-mark} | home -| The home database configured for the user, or `null` if no home database has been configured. +| 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. +If this database is unavailable and the user does not specify a database to use, they will not be able to log in. | {cross-mark} | {check-mark} |=== -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW USERS ---- @@ -465,12 +472,12 @@ It is possible to set the initial password using xref:4.4@operations-manual:ROOT .Show user ====== -This example show how: +This example shows how to: * Reorder the columns using a `YIELD` clause. * Filter the results using a `WHERE` clause. -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW USERS YIELD user, suspended, passwordChangeRequired, roles, home WHERE user = 'jake' @@ -482,7 +489,7 @@ WHERE user = 'jake' It is possible to add a `RETURN` clause to further manipulate the results after filtering. In this example, the `RETURN` clause is used to filter out the `roles` column and rename the `user` column to `adminUser`. -[source,cypher,role=noplay, indent=0] +[source,cypher,role=noplay] ---- SHOW USERS YIELD roles, user WHERE 'admin' IN roles @@ -501,7 +508,7 @@ The `SHOW USER name PRIVILEGES` command is described in xref::access-control/man Users can be created using `CREATE USER`. -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- CREATE USER name [IF NOT EXISTS] SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password' @@ -512,7 +519,7 @@ CREATE USER name [IF NOT EXISTS] Users can be created or replaced using `CREATE OR REPLACE USER`. -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- CREATE OR REPLACE USER name SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password' @@ -524,13 +531,13 @@ CREATE OR REPLACE USER name * 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. -Therefore, it is never possible to get the plaintext of a password back out of the 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:4.4@operations-manual:ROOT:backup-restore/restore-backup/index.adoc#restore-backup-example[Operations Manual -> Restore a database backup -> Example]. + -With `ENCRYPTED`, the password string is expected to be in the format of `,,`, where, for example: +With `ENCRYPTED`, the password string is expected to be in the format of ``, `` or ``, 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`. @@ -553,10 +560,9 @@ The created user will appear on the list provided by `SHOW USERS`. .Create user ====== +For example, you can create the user `jake` in a suspended state, with the home database `anotherDb`, and the requirement to change the password by using the command: -For example, you can create the user `jake` in a suspended state, with the home database `anotherDb`, and the requirement to change the password, using the command: - -[source, cypher, role=noplay, indent=0] +[source,cypher,role=noplay] ---- CREATE USER jake SET PASSWORD 'abc' CHANGE REQUIRED @@ -569,10 +575,9 @@ SET HOME DATABASE anotherDb .Create user ====== +Or you can recreate 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: -Or, you can recreate 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 not to change the password, by running: - -[source, cypher, role=noplay, indent=0] +[source,cypher,role=noplay] ---- CREATE USER jake SET ENCRYPTED PASSWORD '1,6d57a5e0b3317055454e455f96c98c750c77fb371f3f0634a1b8ff2a55c5b825,190ae47c661e0668a0c8be8a21ff78a4a34cdf918cae3c407e907b73932bd16c' CHANGE NOT REQUIRED @@ -592,8 +597,7 @@ Appending `IF NOT EXISTS` to the `CREATE USER` command will ensure that no excep .Create user if not exists ====== - -[source, cypher, role=noplay, indent=0] +[source,cypher,role=noplay] ---- CREATE USER jake IF NOT EXISTS SET PLAINTEXT PASSWORD 'xyz' @@ -606,8 +610,7 @@ The `CREATE OR REPLACE USER` command will result in any existing user being dele .Create or replace user ====== - -[source, cypher, role=noplay, indent=0] +[source,cypher,role=noplay] ---- CREATE OR REPLACE USER jake SET PLAINTEXT PASSWORD 'xyz' @@ -619,21 +622,21 @@ This is equivalent to running `DROP USER jake IF EXISTS` followed by `CREATE USE [NOTE] ==== -The `CREATE OR REPLACE USER` command does not allow you to use the `IF NOT EXISTS`. +The `CREATE OR REPLACE USER` command does not allow the use of `IF NOT EXISTS`. ==== [[access-control-rename-users]] == Renaming users -Users can be renamed using the `RENAME USER` command. +Users can be renamed with the `RENAME USER` command. -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- RENAME USER jake TO bob ---- -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW USERS ---- @@ -668,9 +671,9 @@ The `RENAME USER` command is only available when using native authentication and [[access-control-alter-users]] == Modifying users -Users can be modified using `ALTER USER`. +Users can be modified with `ALTER USER`. -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- ALTER USER name [IF EXISTS] [SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password'] @@ -683,17 +686,17 @@ ALTER USER name [IF EXISTS] * 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. +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. -Therefore, it is never possible to get the plaintext of a password back out of the 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:4.4@operations-manual:ROOT:backup-restore/restore-backup/index.adoc#restore-backup-example[Operations Manual -> Restore a database backup -> Example]. + -With `ENCRYPTED`, the password string is expected to be in the format of `,,`, where, for example: +With `ENCRYPTED`, the password string is expected to be in the format of ``,`` or ``, 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`. @@ -707,24 +710,24 @@ This results in the DBMS default database being used as the home database for th For example, you can modify the user `bob` with a new password and active status, and remove the requirement to change his password: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- ALTER USER bob SET PASSWORD 'abc123' CHANGE NOT REQUIRED SET STATUS ACTIVE ---- -Or, you may decide to assign the user `bob` a different home database: +Or you may decide to assign the user `bob` a different home database: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- ALTER USER bob SET HOME DATABASE anotherDbOrAlias ---- -Or, remove the home database from the user `bob`: +Or remove the home database from the user `bob`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- ALTER USER bob REMOVE HOME DATABASE @@ -732,7 +735,7 @@ REMOVE HOME DATABASE [NOTE] ==== -When altering a user it is only necessary to specify the changes required. +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. ==== @@ -743,7 +746,7 @@ The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE`, and `REMOVE HOME DAT The changes to the user will appear on the list provided by `SHOW USERS`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW USERS ---- @@ -770,9 +773,10 @@ SHOW USERS |=== The default behavior of this command is to throw an exception if the user does not exist. -Appending an optional parameter `IF EXISTS` to the command makes it idempotent and ensures that no exception is thrown and nothing happens should the user not exist. +Adding an optional parameter `IF EXISTS` to the command makes it idempotent and ensures that no exception is thrown. +Nothing happens should the user not exist. -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- ALTER USER nonExistingUser IF EXISTS SET PASSWORD 'abc123' ---- @@ -785,7 +789,7 @@ Users can change their password using `ALTER CURRENT USER SET PASSWORD`. The old password is required in addition to the new one, and either or both can be a string value or a string parameter. When a user executes this command it will change their password as well as set the `CHANGE NOT REQUIRED` flag. -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- ALTER CURRENT USER SET PASSWORD FROM 'abc123' TO '123xyz' @@ -800,18 +804,18 @@ This command works only for a logged-in user and cannot be run with auth disable [[access-control-drop-users]] == Delete users -Users can be deleted using `DROP USER`. +Users can be deleted with `DROP USER`. -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- DROP USER bob ---- Deleting a user will not automatically terminate associated connections, sessions, transactions, or queries. -When a user has been deleted, it will no longer appear on the list provided by `SHOW USERS`: +However, when a user has been deleted, it will no longer appear on the list provided by `SHOW USERS`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW USERS ---- @@ -830,4 +834,3 @@ SHOW USERS 5+a|Rows: 1 |=== -