From 8efdbfaa6956a498f92799bc057a4abe11aa54fe Mon Sep 17 00:00:00 2001 From: Amruta Date: Tue, 31 Mar 2020 16:11:39 -0400 Subject: [PATCH 01/14] Alter role sql diagram --- _includes/v20.1/sql/diagrams/alter_role.html | 29 ++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 _includes/v20.1/sql/diagrams/alter_role.html diff --git a/_includes/v20.1/sql/diagrams/alter_role.html b/_includes/v20.1/sql/diagrams/alter_role.html new file mode 100644 index 00000000000..6291ec7cca0 --- /dev/null +++ b/_includes/v20.1/sql/diagrams/alter_role.html @@ -0,0 +1,29 @@ +
+ + + + +ALTER + + +ROLE + + +USER + + +IF + + +EXISTS + + +name + + +opt_with + + +role_options + +
From cc74ffc1098f1b5fb8dae2b62defad820bb8e454 Mon Sep 17 00:00:00 2001 From: Amruta Date: Thu, 2 Apr 2020 14:23:36 -0400 Subject: [PATCH 02/14] Added alter role doc + root password updates + misc updates --- v20.1/alter-role.md | 82 +++++++++++++++++++++++++++++++++++++ v20.1/alter-user.md | 4 +- v20.1/authentication.md | 2 +- v20.1/authorization.md | 5 ++- v20.1/create-user.md | 6 +-- v20.1/information-schema.md | 3 -- 6 files changed, 90 insertions(+), 12 deletions(-) create mode 100644 v20.1/alter-role.md diff --git a/v20.1/alter-role.md b/v20.1/alter-role.md new file mode 100644 index 00000000000..a7bc8d635e2 --- /dev/null +++ b/v20.1/alter-role.md @@ -0,0 +1,82 @@ +--- +title: ALTER ROLE +summary: The ALTER ROLE statement can be used to add or change a role's password. +toc: true +--- + +The `ALTER ROLE` [statement](sql-statements.html) can be used to add or change a [role's](create-role.html) password. + +{{site.data.alerts.callout_info}} +New in v20.1: Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL statements for enhanced Postgres compatibility, `ALTER ROLE` is now an alias for [`ALTER USER`](alter-user.html). +{{site.data.alerts.end}} + +## Considerations + +- Password creation and alteration is supported only in secure clusters. + +## Required privileges + +The user must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. + +## Synopsis + +
{% include {{ page.version.version }}/sql/diagrams/alter_role.html %}
+ +## Parameters + + + +Parameter | Description +----------|------------- +`name` | The name of the role whose password you want to create or add. +`password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged. + +## Examples + +### Change password using a string literal + +{% include copy-clipboard.html %} +~~~ sql +> ALTER ROLE carl WITH PASSWORD 'ilov3beefjerky'; +~~~ +~~~ +ALTER ROLE 1 +~~~ + +### Change password using an identifier + +The following statement changes the password to `ilov3beefjerky`, as above: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER ROLE carl WITH PASSWORD ilov3beefjerky; +~~~ + +This is equivalent to the example in the previous section because the password contains only lowercase characters. + +In contrast, the following statement changes the password to `thereisnotomorrow`, even though the password in the syntax contains capitals, because identifiers are normalized automatically: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER ROLE carl WITH PASSWORD ThereIsNoTomorrow; +~~~ + +To preserve case in a password specified using identifier syntax, use double quotes: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER ROLE carl WITH PASSWORD "ThereIsNoTomorrow"; +~~~ + +## See also + +- [`DROP ROLE`](drop-role.html) +- [`SHOW ROLES`](show-roles.html) +- [`GRANT `](grant.html) +- [`SHOW GRANTS`](show-grants.html) +- [Create Security Certificates](cockroach-cert.html) +- [Other SQL Statements](sql-statements.html) diff --git a/v20.1/alter-user.md b/v20.1/alter-user.md index 681461e963d..15813b275f9 100644 --- a/v20.1/alter-user.md +++ b/v20.1/alter-user.md @@ -7,12 +7,12 @@ toc: true The `ALTER USER` [statement](sql-statements.html) can be used to add or change a [user's](create-user.html) password. {{site.data.alerts.callout_info}} -New in v20.1: Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL statements for enhanced Postgres compatibility, `ALTER USER` is now an alias for `ALTER ROLE`. +New in v20.1: Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL statements for enhanced Postgres compatibility, `ALTER USER` is now an alias for [`ALTER ROLE`](alter-role.html). {{site.data.alerts.end}} ## Considerations -- Password creation and alteration is supported only in secure clusters for non-`root` users. +- Password creation and alteration is supported only in secure clusters. ## Required privileges diff --git a/v20.1/authentication.md b/v20.1/authentication.md index e118ae8a7c0..ef8ad7448b7 100644 --- a/v20.1/authentication.md +++ b/v20.1/authentication.md @@ -50,7 +50,7 @@ CockroachDB offers three methods for client authentication: $ cockroach sql --certs-dir=certs --user=jpointsman ~~~ -- **Password authentication**, which is available to non-`root` users who you've created passwords for. Password creation is supported only in secure clusters. +- **Password authentication**, which is available to users and roles who you've created passwords for. Password creation is supported only in secure clusters. Example: {% include copy-clipboard.html %} diff --git a/v20.1/authorization.md b/v20.1/authorization.md index 656c5fde7b2..e0912ce5369 100644 --- a/v20.1/authorization.md +++ b/v20.1/authorization.md @@ -28,6 +28,8 @@ By default, a new user belongs to the `public` role and has no privileges other ### `root` user The `root` user is created by default for each cluster. The `root` user is assigned to the [`admin` role](#admin-role) and has all privileges across the cluster. +For secure clusters, in addition to [generating the client certificate](authentication.html#client-authentication) for the `root` user, you can assign or change the password for the `root` user using the [`ALTER USER`](alter-user.html) statement. + ## Roles {{site.data.alerts.callout_info}} @@ -121,8 +123,7 @@ You can manage the following privileges for databases and tables: We recommend the following best practices to set up access control for your clusters: -- Use the `root` user only for database administration tasks such as creating and managing other users, creating and managing roles, and creating and managing databases. Do not use the `root` user for applications; instead, create users with specific privileges based on your application’s access requirements. -- Create roles with specific privileges, create users, and then add the users to the relevant roles. +- Use the `root` user only for database administration tasks such as creating and managing other users, creating and managing roles, and creating and managing databases. Do not use the `root` user for applications; instead, create users or roles with specific privileges based on your application’s access requirements. - Use the ["least privilege model"](https://en.wikipedia.org/wiki/Principle_of_least_privilege) to grant privileges to users and roles. ## Example diff --git a/v20.1/create-user.md b/v20.1/create-user.md index 337ae538d53..2328355b395 100644 --- a/v20.1/create-user.md +++ b/v20.1/create-user.md @@ -40,7 +40,7 @@ table td:first-child { Parameter | Description -----------|------------- `user_name` | The name of the user you want to create.

Usernames are case-insensitive; must start with a letter, number, or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters. -`password` | Let the user [authenticate their access to a secure cluster](#user-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters for non-`root` users. The `root` user must authenticate with a client certificate and key. +`password` | Let the user [authenticate their access to a secure cluster](#user-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. ## User authentication @@ -48,7 +48,7 @@ Secure clusters require users to authenticate their access to databases and tabl - [Client certificate and key authentication](#secure-clusters-with-client-certificates), which is available to all users. To ensure the highest level of security, we recommend only using client certificate and key authentication. -- [Password authentication](#secure-clusters-with-passwords), which is available to non-`root` users who you've created passwords for. To create a user with a password, use the `WITH PASSWORD` clause of `CREATE USER`. To add a password to an existing user, use the [`ALTER USER`](alter-user.html) statement. +- [Password authentication](#secure-clusters-with-passwords), which is available to users and roles who you've created passwords for. To create a user with a password, use the `WITH PASSWORD` clause of `CREATE USER`. To add a password to an existing user, use the [`ALTER USER`](alter-user.html) statement. Users can use passwords to authenticate without supplying client certificates and keys; however, we recommend using certificate-based authentication whenever possible. @@ -77,8 +77,6 @@ After creating users, you must: > CREATE USER jpointsman WITH PASSWORD 'Q7gc8rEdS'; ~~~ -Password creation is supported only in secure clusters for non-`root` users. The `root` user must authenticate with a client certificate and key. - ### Manage users After creating a user, you can use the [`ALTER USER`](alter-user.html) statement to add or change the user's password and the [`DROP USER`](drop-user.html) statement to the remove users. diff --git a/v20.1/information-schema.md b/v20.1/information-schema.md index db2fc49cd88..6a253c236ee 100644 --- a/v20.1/information-schema.md +++ b/v20.1/information-schema.md @@ -304,9 +304,6 @@ Column | Description `user_privileges` identifies global [privileges](authorization.html#assign-privileges). -{{site.data.alerts.callout_info}}Currently, CockroachDB does not support global privileges for non-root users. Therefore, this view contains global privileges only for root. -{{site.data.alerts.end}} - Column | Description -------|----------- `grantee` | Username of user with grant. From bbebc024fedf2597ae5469cfb12e5f37b8590e39 Mon Sep 17 00:00:00 2001 From: Amruta Date: Thu, 2 Apr 2020 17:42:04 -0400 Subject: [PATCH 03/14] password null + misc updates --- v20.1/alter-user.md | 15 ++++++++++++--- v20.1/create-user.md | 2 +- v20.1/gssapi_authentication.md | 4 ++-- 3 files changed, 15 insertions(+), 6 deletions(-) diff --git a/v20.1/alter-user.md b/v20.1/alter-user.md index 15813b275f9..6fe811b7146 100644 --- a/v20.1/alter-user.md +++ b/v20.1/alter-user.md @@ -4,7 +4,7 @@ summary: The ALTER USER statement can be used to add or change a user's password toc: true --- -The `ALTER USER` [statement](sql-statements.html) can be used to add or change a [user's](create-user.html) password. +The `ALTER USER` [statement](sql-statements.html) can be used to add, change, or remove a [user's](create-user.html) password. {{site.data.alerts.callout_info}} New in v20.1: Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL statements for enhanced Postgres compatibility, `ALTER USER` is now an alias for [`ALTER ROLE`](alter-role.html). @@ -16,7 +16,7 @@ The `ALTER USER` [statement](sql-statements.html) can be used to add or change a ## Required privileges -The user must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. +The user must have the `INSERT`, `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. ## Synopsis @@ -33,7 +33,7 @@ table td:first-child { Parameter | Description ----------|------------- `name` | The name of the user whose password you want to create or add. -`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged. +`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged.

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-user-from-using-password-authentication). ## Examples @@ -72,6 +72,15 @@ To preserve case in a password specified using identifier syntax, use double quo > ALTER USER carl WITH PASSWORD "ThereIsNoTomorrow"; ~~~ +### Prevent user from using password authentication + +The following statement prevents the user from using password authentication and mandates certificate-based client authentication: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER USER carl WITH PASSWORD NULL; +~~~ + ## See also - [`DROP USER`](drop-user.html) diff --git a/v20.1/create-user.md b/v20.1/create-user.md index 2328355b395..0c17edccfad 100644 --- a/v20.1/create-user.md +++ b/v20.1/create-user.md @@ -40,7 +40,7 @@ table td:first-child { Parameter | Description -----------|------------- `user_name` | The name of the user you want to create.

Usernames are case-insensitive; must start with a letter, number, or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters. -`password` | Let the user [authenticate their access to a secure cluster](#user-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. +`password` | Let the user [authenticate their access to a secure cluster](#user-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. ## User authentication diff --git a/v20.1/gssapi_authentication.md b/v20.1/gssapi_authentication.md index f6692ccb8d6..d32af957d30 100644 --- a/v20.1/gssapi_authentication.md +++ b/v20.1/gssapi_authentication.md @@ -142,8 +142,8 @@ Copy the resulting keytab to the database nodes. If clients are connecting to mu > SET cluster setting server.host_based_authentication.configuration = 'host all all all gss include_realm=0'; ~~~ - Setting the `server.host_based_authentication.configuration` [cluster setting](cluster-settings.html) makes it mandatory for all users (except `root`) to authenticate using GSSAPI. The `root` user is still required to authenticate using its client certificate. - + Setting the `server.host_based_authentication.configuration` [cluster setting](cluster-settings.html) cluster setting to this particular value makes it mandatory for all non-`root` users to authenticate using GSSAPI. The `root` user is always an exception and remains able to authenticate using a valid client cert or a user password. + The `include_realm=0` option is required to tell CockroachDB to remove the `@DOMAIN.COM` realm information from the username. We don't support any advanced mapping of GSSAPI usernames to CockroachDB usernames right now. If you want to limit which realms' users can connect, you can also add one or more `krb_realm` parameters to the end of the line as a whitelist, as follows: `host all all all gss include_realm=0 krb_realm=domain.com krb_realm=corp.domain.com` The syntax is based on the `pg_hba.conf` standard for PostgreSQL which is documented [here](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html). It can be used to exclude other users from Kerberos authentication. From 3066a32324f6c3fd8c238e320e97b5ea46601e33 Mon Sep 17 00:00:00 2001 From: Amruta Date: Thu, 2 Apr 2020 18:15:16 -0400 Subject: [PATCH 04/14] WIP changes --- v20.1/alter-user.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/v20.1/alter-user.md b/v20.1/alter-user.md index 6fe811b7146..c8bc4672b3c 100644 --- a/v20.1/alter-user.md +++ b/v20.1/alter-user.md @@ -4,7 +4,7 @@ summary: The ALTER USER statement can be used to add or change a user's password toc: true --- -The `ALTER USER` [statement](sql-statements.html) can be used to add, change, or remove a [user's](create-user.html) password. +The `ALTER USER` [statement](sql-statements.html) can be used to add, change, or remove a [user's](create-user.html) password and to change the login privileges for a user or role. {{site.data.alerts.callout_info}} New in v20.1: Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL statements for enhanced Postgres compatibility, `ALTER USER` is now an alias for [`ALTER ROLE`](alter-role.html). @@ -16,7 +16,7 @@ The `ALTER USER` [statement](sql-statements.html) can be used to add, change, or ## Required privileges -The user must have the `INSERT`, `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. +The user must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. ## Synopsis @@ -34,6 +34,7 @@ Parameter | Description ----------|------------- `name` | The name of the user whose password you want to create or add. `password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged.

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-user-from-using-password-authentication). +`login`/`nologin` | The `login` parameter allows a user to login using either password or certificate-based client authentication. Setting the parameter to `nologin` prevents the user from logging in using any authentication method. ## Examples @@ -81,6 +82,22 @@ The following statement prevents the user from using password authentication and > ALTER USER carl WITH PASSWORD NULL; ~~~ +### Change login privileges for a user + +The following statement prevents the user from logging in using the password authentication and certificate-based client authentication: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER USER carl NOLOGIN; +~~~ + +The following statement allows the user to log in using either password authentication or certificate-based client authentication: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER USER carl LOGIN; +~~~ + ## See also - [`DROP USER`](drop-user.html) From 0d33bbc44fd8309fbbefda7a79f8e8c7ae2dad25 Mon Sep 17 00:00:00 2001 From: Amruta Date: Thu, 2 Apr 2020 19:16:45 -0400 Subject: [PATCH 05/14] nologin and password validity --- v20.1/alter-role.md | 70 ++++++++++++++++++++++++++++++++++++++++++-- v20.1/alter-user.md | 50 +++++++++++++++++++++++++++---- v20.1/create-role.md | 3 ++ v20.1/create-user.md | 61 ++++++++++++++++++++++++++++++++++++-- v20.1/show-roles.md | 15 +++++----- v20.1/show-users.md | 26 ++++++++-------- 6 files changed, 195 insertions(+), 30 deletions(-) diff --git a/v20.1/alter-role.md b/v20.1/alter-role.md index a7bc8d635e2..5e09a3e7a98 100644 --- a/v20.1/alter-role.md +++ b/v20.1/alter-role.md @@ -4,7 +4,7 @@ summary: The ALTER ROLE statement can be used to add or change a role's password toc: true --- -The `ALTER ROLE` [statement](sql-statements.html) can be used to add or change a [role's](create-role.html) password. +The `ALTER ROLE` [statement](sql-statements.html) can be used to add, change, or remove a [role's](create-role.html) password and to change the login privileges for a role. {{site.data.alerts.callout_info}} New in v20.1: Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL statements for enhanced Postgres compatibility, `ALTER ROLE` is now an alias for [`ALTER USER`](alter-user.html). @@ -16,7 +16,7 @@ The `ALTER ROLE` [statement](sql-statements.html) can be used to add or change a ## Required privileges -The user must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. +The role must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. ## Synopsis @@ -33,7 +33,9 @@ table td:first-child { Parameter | Description ----------|------------- `name` | The name of the role whose password you want to create or add. -`password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged. +`password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged.

To prevent a role from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-role-from-using-password-authentication). +`valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. +`login`/`nologin` | The `login` parameter allows a role to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `nologin`](#change-login-privileges-for-a-role) prevents the role from logging in using any authentication method. ## Examples @@ -72,6 +74,68 @@ To preserve case in a password specified using identifier syntax, use double quo > ALTER ROLE carl WITH PASSWORD "ThereIsNoTomorrow"; ~~~ +### Set password validity + +The following statement sets the date and time after which the password is not valid: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER ROLE carl VALID UNTIL '2021-01-01'; +~~~ + +### Prevent a role from using password authentication + +The following statement prevents the role from using password authentication and mandates certificate-based client authentication: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER ROLE carl WITH PASSWORD NULL; +~~~ + +### Change login privileges for a role + +The following statement prevents the role from logging in with any [client authentication method](authentication.html#client-authentication): + +{% include copy-clipboard.html %} +~~~ sql +> ALTER ROLE carl NOLOGIN; +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SHOW ROLES; +~~~ + +~~~ + username | options | member_of +-----------+------------+------------ + admin | CREATEROLE | {} + carl | NOLOGIN | {} + root | CREATEROLE | {admin} +(3 rows) +~~~ + +The following statement allows the role to log in with one of the client authentication methods: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER ROLE carl LOGIN; +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SHOW ROLES; +~~~ + +~~~ + username | options | member_of +-----------+------------+------------ + admin | CREATEROLE | {} + carl | | {} + root | CREATEROLE | {admin} +(3 rows) +~~~ + ## See also - [`DROP ROLE`](drop-role.html) diff --git a/v20.1/alter-user.md b/v20.1/alter-user.md index c8bc4672b3c..de7ff2198d2 100644 --- a/v20.1/alter-user.md +++ b/v20.1/alter-user.md @@ -4,7 +4,7 @@ summary: The ALTER USER statement can be used to add or change a user's password toc: true --- -The `ALTER USER` [statement](sql-statements.html) can be used to add, change, or remove a [user's](create-user.html) password and to change the login privileges for a user or role. +The `ALTER USER` [statement](sql-statements.html) can be used to add, change, or remove a [user's](create-user.html) password and to change the login privileges for a user. {{site.data.alerts.callout_info}} New in v20.1: Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL statements for enhanced Postgres compatibility, `ALTER USER` is now an alias for [`ALTER ROLE`](alter-role.html). @@ -33,8 +33,9 @@ table td:first-child { Parameter | Description ----------|------------- `name` | The name of the user whose password you want to create or add. -`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged.

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-user-from-using-password-authentication). -`login`/`nologin` | The `login` parameter allows a user to login using either password or certificate-based client authentication. Setting the parameter to `nologin` prevents the user from logging in using any authentication method. +`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged.

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication). +`valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. +`login`/`nologin` | The `login` parameter allows a user to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `nologin`](#change-login-privileges-for-a-user) prevents the user from logging in using any authentication method. ## Examples @@ -73,7 +74,16 @@ To preserve case in a password specified using identifier syntax, use double quo > ALTER USER carl WITH PASSWORD "ThereIsNoTomorrow"; ~~~ -### Prevent user from using password authentication +### Set password validity + +The following statement sets the date and time after which the password is not valid: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER USER carl VALID UNTIL '2021-01-01'; +~~~ + +### Prevent a user from using password authentication The following statement prevents the user from using password authentication and mandates certificate-based client authentication: @@ -84,20 +94,48 @@ The following statement prevents the user from using password authentication and ### Change login privileges for a user -The following statement prevents the user from logging in using the password authentication and certificate-based client authentication: +The following statement prevents the user from logging in with any [client authentication method](authentication.html#client-authentication): {% include copy-clipboard.html %} ~~~ sql > ALTER USER carl NOLOGIN; ~~~ -The following statement allows the user to log in using either password authentication or certificate-based client authentication: +{% include copy-clipboard.html %} +~~~ sql +> SHOW USERS; +~~~ + +~~~ + username | options | member_of +-----------+------------+------------ + admin | CREATEROLE | {} + carl | NOLOGIN | {} + root | CREATEROLE | {admin} +(3 rows) +~~~ + +The following statement allows the user to log in with one of the client authentication methods: {% include copy-clipboard.html %} ~~~ sql > ALTER USER carl LOGIN; ~~~ +{% include copy-clipboard.html %} +~~~ sql +> SHOW USERS; +~~~ + +~~~ + username | options | member_of +-----------+------------+------------ + admin | CREATEROLE | {} + carl | | {} + root | CREATEROLE | {admin} +(3 rows) +~~~ + ## See also - [`DROP USER`](drop-user.html) diff --git a/v20.1/create-role.md b/v20.1/create-role.md index d2b21ef004d..ccc56b7c13f 100644 --- a/v20.1/create-role.md +++ b/v20.1/create-role.md @@ -38,6 +38,9 @@ Roles can only be created by superusers, i.e., members of the `admin` role. The | Parameter | Description | ------------|-------------- `name` | The name of the role you want to create. Role names are case-insensitive; must start with either a letter or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters.

Note that roles and [users](create-user.html) share the same namespace and must be unique. +`password` | Let the role [authenticate their access to a secure cluster](#client-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. +`valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. +`login`/`nologin` | The `login` parameter allows a role to login with one of the [client authentication methods](authentication.html#client-authentication).

By default, the parameter is set to `nologin` for the `CREATE ROLE` statement. ## Examples diff --git a/v20.1/create-user.md b/v20.1/create-user.md index 0c17edccfad..b5206eab966 100644 --- a/v20.1/create-user.md +++ b/v20.1/create-user.md @@ -40,11 +40,13 @@ table td:first-child { Parameter | Description -----------|------------- `user_name` | The name of the user you want to create.

Usernames are case-insensitive; must start with a letter, number, or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters. -`password` | Let the user [authenticate their access to a secure cluster](#user-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. +`password` | Let the user [authenticate their access to a secure cluster](#user-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. +`valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. +`login`/`nologin` | The `login` parameter allows a user to login with one of the [user authentication methods](#user-authentication). [Setting the parameter to `nologin`](#set-login-privileges-for-a-user) prevents the user from logging in using any authentication method.

By default, the parameter is set to `login` for the `CREATE USER` statement. ## User authentication -Secure clusters require users to authenticate their access to databases and tables. CockroachDB offers two methods for this: +Secure clusters require users to authenticate their access to databases and tables. CockroachDB offers three methods for this: - [Client certificate and key authentication](#secure-clusters-with-client-certificates), which is available to all users. To ensure the highest level of security, we recommend only using client certificate and key authentication. @@ -54,6 +56,8 @@ Secure clusters require users to authenticate their access to databases and tabl Password creation is supported only in secure clusters. +- [**GSSAPI authentication**](gssapi_authentication.html), which is available to [Enterprise users](enterprise-licensing.html). + ## Examples ### Create a user @@ -77,6 +81,15 @@ After creating users, you must: > CREATE USER jpointsman WITH PASSWORD 'Q7gc8rEdS'; ~~~ +### Set password validity + +The following statement sets the date and time after which the password is not valid: + +{% include copy-clipboard.html %} +~~~ sql +> CREATE USER carl VALID UNTIL '2021-01-01'; +~~~ + ### Manage users After creating a user, you can use the [`ALTER USER`](alter-user.html) statement to add or change the user's password and the [`DROP USER`](drop-user.html) statement to the remove users. @@ -122,6 +135,50 @@ $ cockroach sql --insecure --user=jpointsman +### Set login privileges for a user + +The following statement prevents the user from logging in using any [user authentication method](user-authentication): + +{% include copy-clipboard.html %} +~~~ sql +> CREATE USER carl NOLOGIN; +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SHOW USERS; +~~~ + +~~~ + username | options | member_of +-----------+------------+------------ + admin | CREATEROLE | {} + carl | NOLOGIN | {} + root | CREATEROLE | {admin} +(3 rows) +~~~ + +To allow the user to log in using one of the user authentication methods, use the `ALTER USER` statement: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER USER carl LOGIN; +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SHOW USERS; +~~~ + +~~~ + username | options | member_of +-----------+------------+------------ + admin | CREATEROLE | {} + carl | | {} + root | CREATEROLE | {admin} +(3 rows) +~~~ + ## See also - [Authorization](authorization.html) diff --git a/v20.1/show-roles.md b/v20.1/show-roles.md index c47f7fae25e..ea796e161d3 100644 --- a/v20.1/show-roles.md +++ b/v20.1/show-roles.md @@ -18,7 +18,7 @@ The `SHOW ROLES` [statement](sql-statements.html) lists the roles for all databa ## Required privileges -The user must have the [`SELECT`](select-clause.html) [privilege](authorization.html#assign-privileges) on the system table. +The role must have the [`SELECT`](select-clause.html) [privilege](authorization.html#assign-privileges) on the system table. ## Example @@ -28,12 +28,13 @@ The user must have the [`SELECT`](select-clause.html) [privilege](authorization. ~~~ ~~~ -+-----------+ -| role_name | -+-----------+ -| admin | -| dev_ops | -+-----------+ + username | options | member_of +-----------+------------+------------ + admin | CREATEROLE | {} + carl | NOLOGIN | {} + petee | | {} + root | CREATEROLE | {admin} +(4 rows) ~~~ ## See also diff --git a/v20.1/show-users.md b/v20.1/show-users.md index f94f87444e7..9b4d2a279c8 100644 --- a/v20.1/show-users.md +++ b/v20.1/show-users.md @@ -28,12 +28,13 @@ The user must have the [`SELECT`](select-clause.html) [privilege](authorization. ~~~ ~~~ - user_name -+------------+ - jpointsman - maxroach - root -(3 rows) + username | options | member_of +-----------+------------+------------ + admin | CREATEROLE | {} + carl | NOLOGIN | {} + petee | | {} + root | CREATEROLE | {admin} +(4 rows) ~~~ Alternatively, within the built-in SQL shell, you can use the `\du` [shell command](cockroach-sql.html#commands): @@ -44,12 +45,13 @@ Alternatively, within the built-in SQL shell, you can use the `\du` [shell comma ~~~ ~~~ - user_name -+------------+ - jpointsman - maxroach - root -(3 rows) + username | options | member_of +-----------+------------+------------ + admin | CREATEROLE | {} + carl | NOLOGIN | {} + petee | | {} + root | CREATEROLE | {admin} +(4 rows) ~~~ ## See also From 976a4f395e60244b582dec6b6602bcdc2ccb4de8 Mon Sep 17 00:00:00 2001 From: Amruta Date: Fri, 3 Apr 2020 10:52:36 -0400 Subject: [PATCH 06/14] added content for createrole --- v20.1/alter-role.md | 38 ++++++++++++++++++++++++++++++++++++++ v20.1/alter-user.md | 2 ++ v20.1/create-role.md | 12 +++++++++++- v20.1/create-user.md | 20 +++++++++++++++----- v20.1/drop-role.md | 2 ++ v20.1/drop-user.md | 2 ++ 6 files changed, 70 insertions(+), 6 deletions(-) diff --git a/v20.1/alter-role.md b/v20.1/alter-role.md index 5e09a3e7a98..9efac7d2b38 100644 --- a/v20.1/alter-role.md +++ b/v20.1/alter-role.md @@ -18,6 +18,8 @@ The `ALTER ROLE` [statement](sql-statements.html) can be used to add, change, or The role must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. +To alter other roles, the role must have the [`createrole`](create-role.html##allow-the-role-to-create-other-roles) parameter set. + ## Synopsis
{% include {{ page.version.version }}/sql/diagrams/alter_role.html %}
@@ -136,6 +138,42 @@ The following statement allows the role to log in with one of the client authent (3 rows) ~~~ +### Allow the role to create other roles + +{% include copy-clipboard.html %} +~~~ sql +> SHOW ROLES; +~~~ + +~~~ + username | options | member_of +-----------+------------+------------ + admin | CREATEROLE | {} + carl | | {} + root | CREATEROLE | {admin} +(3 rows) +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> ALTER ROLE carl with CREATEROLE; +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SHOW ROLES; +~~~ + +~~~ + username | options | member_of +-----------+------------+------------ + admin | CREATEROLE | {} + carl | CREATEROLE | {} + root | CREATEROLE | {admin} +(3 rows) +~~~ + + ## See also - [`DROP ROLE`](drop-role.html) diff --git a/v20.1/alter-user.md b/v20.1/alter-user.md index de7ff2198d2..4f13f6d6494 100644 --- a/v20.1/alter-user.md +++ b/v20.1/alter-user.md @@ -18,6 +18,8 @@ The `ALTER USER` [statement](sql-statements.html) can be used to add, change, or The user must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. +To alter other users, the user must have the [`createrole`](create-user.html#allow-the-user-to-create-other-users) parameter set. + ## Synopsis
{% include {{ page.version.version }}/sql/diagrams/alter_user_password.html %}
diff --git a/v20.1/create-role.md b/v20.1/create-role.md index ccc56b7c13f..d0a30e107ba 100644 --- a/v20.1/create-role.md +++ b/v20.1/create-role.md @@ -29,6 +29,8 @@ The `CREATE ROLE` [statement](sql-statements.html) creates SQL [roles](authoriza Roles can only be created by superusers, i.e., members of the `admin` role. The `admin` role exists by default with `root` as the member. +To create other roles, the role must have the [`createrole`](#allow-the-role-to-create-other-roles) parameter set. + ## Synopsis
{% include {{ page.version.version }}/sql/diagrams/create_role.html %}
@@ -40,7 +42,8 @@ Roles can only be created by superusers, i.e., members of the `admin` role. The `name` | The name of the role you want to create. Role names are case-insensitive; must start with either a letter or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters.

Note that roles and [users](create-user.html) share the same namespace and must be unique. `password` | Let the role [authenticate their access to a secure cluster](#client-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. `valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. -`login`/`nologin` | The `login` parameter allows a role to login with one of the [client authentication methods](authentication.html#client-authentication).

By default, the parameter is set to `nologin` for the `CREATE ROLE` statement. +`login`/`nologin` | Allow or disallow a role to login with one of the [client authentication methods](authentication.html#client-authentication).

By default, the parameter is set to `nologin` for the `CREATE ROLE` statement. +`createrole`/`nocreaterole` | Allow or disallow the new role to create, alter, and drop other roles.

By default, the parameter is set to `nocreaterole` for all non-admin and non-root users. ## Examples @@ -54,6 +57,13 @@ CREATE ROLE 1 After creating roles, you can [add users to the role](grant-roles.html) and [grant the role privileges](grant.html). +### Allow the role to create other roles + +{% include copy-clipboard.html %} +~~~ sql +> CREATE ROLE dev with CREATEROLE; +~~~ + ## See also - [Authorization](authorization.html) diff --git a/v20.1/create-user.md b/v20.1/create-user.md index b5206eab966..f4c5e9a44f5 100644 --- a/v20.1/create-user.md +++ b/v20.1/create-user.md @@ -25,6 +25,8 @@ The `CREATE USER` [statement](sql-statements.html) creates SQL users, which let The user must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. +To create other users, the user must have the [`createrole`](#allow-the-user-to-create-other-users) parameter set. + ## Synopsis
{% include {{ page.version.version }}/sql/diagrams/create_user.html %}
@@ -43,6 +45,7 @@ table td:first-child { `password` | Let the user [authenticate their access to a secure cluster](#user-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. `valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. `login`/`nologin` | The `login` parameter allows a user to login with one of the [user authentication methods](#user-authentication). [Setting the parameter to `nologin`](#set-login-privileges-for-a-user) prevents the user from logging in using any authentication method.

By default, the parameter is set to `login` for the `CREATE USER` statement. +`createrole`/`nocreaterole` | Allow or disallow the new user to create, alter, and drop other users.

By default, the parameter is set to `nocreaterole` for all non-admin and non-root users. ## User authentication @@ -66,7 +69,7 @@ Usernames are case-insensitive; must start with a letter, number, or underscore; {% include copy-clipboard.html %} ~~~ sql -> CREATE USER jpointsman; +> CREATE USER carl; ~~~ After creating users, you must: @@ -74,11 +77,18 @@ After creating users, you must: - [Grant them privileges to databases](grant.html). - For secure clusters, you must also [create their client certificates](cockroach-cert.html#create-the-certificate-and-key-pair-for-a-client). +### Allow the user to create other users + +{% include copy-clipboard.html %} +~~~ sql +> CREATE USER carl with CREATEROLE; +~~~ + ### Create a user with a password {% include copy-clipboard.html %} ~~~ sql -> CREATE USER jpointsman WITH PASSWORD 'Q7gc8rEdS'; +> CREATE USER carl WITH PASSWORD 'Q7gc8rEdS'; ~~~ ### Set password validity @@ -110,7 +120,7 @@ All users can authenticate their access to a secure cluster using [a client cert {% include copy-clipboard.html %} ~~~ shell -$ cockroach sql --user=jpointsman +$ cockroach sql --user=carl ~~~ #### Secure clusters with passwords @@ -121,7 +131,7 @@ If we cannot find client certificate and key files matching the user, we fall ba {% include copy-clipboard.html %} ~~~ shell -$ cockroach sql --user=jpointsman +$ cockroach sql --user=carl ~~~ @@ -130,7 +140,7 @@ $ cockroach sql --user=jpointsman {% include copy-clipboard.html %} ~~~ shell -$ cockroach sql --insecure --user=jpointsman +$ cockroach sql --insecure --user=carl ~~~ diff --git a/v20.1/drop-role.md b/v20.1/drop-role.md index 1a00233c9af..be957c3872d 100644 --- a/v20.1/drop-role.md +++ b/v20.1/drop-role.md @@ -19,6 +19,8 @@ The `DROP ROLE` [statement](sql-statements.html) removes one or more SQL roles. Roles can only be dropped by super users, i.e., members of the `admin` role. +To drop other non-admin roles, the role must have the [`createrole`](create-role.html#allow-the-user-to-create-other-roles) parameter set. + ## Synopsis
{% include {{ page.version.version }}/sql/diagrams/drop_role.html %}
diff --git a/v20.1/drop-user.md b/v20.1/drop-user.md index 231cb49034e..23f52986be0 100644 --- a/v20.1/drop-user.md +++ b/v20.1/drop-user.md @@ -14,6 +14,8 @@ The `DROP USER` [statement](sql-statements.html) removes one or more SQL users. The user must have the `DELETE` [privilege](authorization.html#assign-privileges) on the `system.users` table. +To drop other non-admin users, the user must have the [`createrole`](create-user.html#allow-the-user-to-create-other-users) parameter set. + ## Synopsis
{% include {{ page.version.version }}/sql/diagrams/drop_user.html %}
From 57ec534fd4f12ffdcd519afefe80645272dbcdb5 Mon Sep 17 00:00:00 2001 From: Amruta Date: Fri, 3 Apr 2020 10:58:34 -0400 Subject: [PATCH 07/14] added content for grant zoneconfig --- v20.1/grant.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/v20.1/grant.md b/v20.1/grant.md index ca7bdc6c9c9..4fbc4e7f2f2 100644 --- a/v20.1/grant.md +++ b/v20.1/grant.md @@ -42,6 +42,7 @@ Privilege | Levels `INSERT` | Table `DELETE` | Table `UPDATE` | Table +New in v20.1 `ZONECONFIG` | Database, Table ## Parameters @@ -148,6 +149,14 @@ Parameter | Description (3 rows) ~~~ +### Grant `ZONECONFIG` privilege on a database or table + +{% include copy-clipboard.html %} +~~~ sql +> GRANT ZONECONFIG ON TABLE mytable TO myuser; +~~~ + +The user `myuser` can then use the [`CONFIGURE ZONE`](configure-zone.html) statement to to add, modify, reset, or remove replication zones for the table `mytable`. ## See also @@ -157,4 +166,5 @@ Parameter | Description - [`REVOKE `](revoke.html) - [`SHOW GRANTS`](show-grants.html) - [`SHOW ROLES`](show-roles.html) +- [`CONFIGURE ZONE`](configure-zone.html) - [Manage Users](authorization.html#create-and-manage-users) From 67f772da33cae34434474f7bf90ed8c22032dd5f Mon Sep 17 00:00:00 2001 From: Amruta Date: Fri, 3 Apr 2020 11:07:32 -0400 Subject: [PATCH 08/14] Fixed broken links --- v20.1/alter-role.md | 2 +- v20.1/create-role.md | 2 +- v20.1/create-user.md | 2 +- v20.1/drop-role.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/v20.1/alter-role.md b/v20.1/alter-role.md index 9efac7d2b38..86780339cbd 100644 --- a/v20.1/alter-role.md +++ b/v20.1/alter-role.md @@ -18,7 +18,7 @@ The `ALTER ROLE` [statement](sql-statements.html) can be used to add, change, or The role must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. -To alter other roles, the role must have the [`createrole`](create-role.html##allow-the-role-to-create-other-roles) parameter set. +To alter other roles, the role must have the [`createrole`](create-role.html#allow-the-role-to-create-other-roles) parameter set. ## Synopsis diff --git a/v20.1/create-role.md b/v20.1/create-role.md index d0a30e107ba..13ce62cc99f 100644 --- a/v20.1/create-role.md +++ b/v20.1/create-role.md @@ -40,7 +40,7 @@ To create other roles, the role must have the [`createrole`](#allow-the-role-to- | Parameter | Description | ------------|-------------- `name` | The name of the role you want to create. Role names are case-insensitive; must start with either a letter or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters.

Note that roles and [users](create-user.html) share the same namespace and must be unique. -`password` | Let the role [authenticate their access to a secure cluster](#client-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. +`password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. `valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. `login`/`nologin` | Allow or disallow a role to login with one of the [client authentication methods](authentication.html#client-authentication).

By default, the parameter is set to `nologin` for the `CREATE ROLE` statement. `createrole`/`nocreaterole` | Allow or disallow the new role to create, alter, and drop other roles.

By default, the parameter is set to `nocreaterole` for all non-admin and non-root users. diff --git a/v20.1/create-user.md b/v20.1/create-user.md index f4c5e9a44f5..0ff785e9e01 100644 --- a/v20.1/create-user.md +++ b/v20.1/create-user.md @@ -147,7 +147,7 @@ $ cockroach sql --insecure --user=carl ### Set login privileges for a user -The following statement prevents the user from logging in using any [user authentication method](user-authentication): +The following statement prevents the user from logging in using any [user authentication method](#user-authentication): {% include copy-clipboard.html %} ~~~ sql diff --git a/v20.1/drop-role.md b/v20.1/drop-role.md index be957c3872d..b354287050f 100644 --- a/v20.1/drop-role.md +++ b/v20.1/drop-role.md @@ -19,7 +19,7 @@ The `DROP ROLE` [statement](sql-statements.html) removes one or more SQL roles. Roles can only be dropped by super users, i.e., members of the `admin` role. -To drop other non-admin roles, the role must have the [`createrole`](create-role.html#allow-the-user-to-create-other-roles) parameter set. +To drop other non-admin roles, the role must have the [`createrole`](create-role.html#allow-the-role-to-create-other-roles) parameter set. ## Synopsis From 9106450242a2162f24cf976bf1bd88c70f263b9c Mon Sep 17 00:00:00 2001 From: Amruta Date: Fri, 3 Apr 2020 19:08:39 -0400 Subject: [PATCH 09/14] Worked on Richard's comments --- v20.1/alter-role.md | 1 + v20.1/alter-user.md | 1 + 2 files changed, 2 insertions(+) diff --git a/v20.1/alter-role.md b/v20.1/alter-role.md index 86780339cbd..c8cf4bc0abe 100644 --- a/v20.1/alter-role.md +++ b/v20.1/alter-role.md @@ -38,6 +38,7 @@ Parameter | Description `password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged.

To prevent a role from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-role-from-using-password-authentication). `valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. `login`/`nologin` | The `login` parameter allows a role to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `nologin`](#change-login-privileges-for-a-role) prevents the role from logging in using any authentication method. +`createrole`/`nocreaterole` | Allow or disallow the role to create, alter, and drop other roles.

By default, the parameter is set to `nocreaterole` for all non-admin and non-root roles. ## Examples diff --git a/v20.1/alter-user.md b/v20.1/alter-user.md index 4f13f6d6494..349eed8670c 100644 --- a/v20.1/alter-user.md +++ b/v20.1/alter-user.md @@ -38,6 +38,7 @@ Parameter | Description `password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged.

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication). `valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. `login`/`nologin` | The `login` parameter allows a user to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `nologin`](#change-login-privileges-for-a-user) prevents the user from logging in using any authentication method. +`createrole`/`nocreaterole` | Allow or disallow the user to create, alter, and drop other users.

By default, the parameter is set to `nocreaterole` for all non-admin and non-root users. ## Examples From 7a0468d83ef80651a13102bf3c925425da7703cf Mon Sep 17 00:00:00 2001 From: Amruta Date: Thu, 9 Apr 2020 13:55:14 -0400 Subject: [PATCH 10/14] Working on review comments --- v20.1/alter-role.md | 10 ++++------ v20.1/alter-user.md | 10 ++++------ v20.1/authorization.md | 4 ++-- v20.1/create-role.md | 10 ++++------ v20.1/create-user.md | 12 +++++------- v20.1/drop-role.md | 2 +- v20.1/drop-user.md | 4 +--- v20.1/gssapi_authentication.md | 2 +- v20.1/show-roles.md | 2 +- v20.1/show-users.md | 2 +- 10 files changed, 24 insertions(+), 34 deletions(-) diff --git a/v20.1/alter-role.md b/v20.1/alter-role.md index c8cf4bc0abe..fe86b45e4c7 100644 --- a/v20.1/alter-role.md +++ b/v20.1/alter-role.md @@ -16,9 +16,7 @@ The `ALTER ROLE` [statement](sql-statements.html) can be used to add, change, or ## Required privileges -The role must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. - -To alter other roles, the role must have the [`createrole`](create-role.html#allow-the-role-to-create-other-roles) parameter set. +New in v20.1: To alter other roles, the role must have the [`CREATEROLE`](create-role.html#allow-the-role-to-create-other-roles) parameter set. ## Synopsis @@ -36,9 +34,9 @@ Parameter | Description ----------|------------- `name` | The name of the role whose password you want to create or add. `password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged.

To prevent a role from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-role-from-using-password-authentication). -`valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. -`login`/`nologin` | The `login` parameter allows a role to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `nologin`](#change-login-privileges-for-a-role) prevents the role from logging in using any authentication method. -`createrole`/`nocreaterole` | Allow or disallow the role to create, alter, and drop other roles.

By default, the parameter is set to `nocreaterole` for all non-admin and non-root roles. +`VALID UNTIL` | New in v20.1: The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. +`LOGIN`/`NOLOGIN` | New in v20.1: The `LOGIN` parameter allows a role to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `nologin`](#change-login-privileges-for-a-role) prevents the role from logging in using any authentication method. +`CREATEROLE`/`NOCREATEROLE` | New in v20.1: Allow or disallow the role to create, alter, and drop other roles.

By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root roles. ## Examples diff --git a/v20.1/alter-user.md b/v20.1/alter-user.md index 349eed8670c..ae12a132b8a 100644 --- a/v20.1/alter-user.md +++ b/v20.1/alter-user.md @@ -16,9 +16,7 @@ The `ALTER USER` [statement](sql-statements.html) can be used to add, change, or ## Required privileges -The user must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. - -To alter other users, the user must have the [`createrole`](create-user.html#allow-the-user-to-create-other-users) parameter set. +New in v20.1: To alter other users, the user must have the [`CREATEROLE`](create-user.html#allow-the-user-to-create-other-users) parameter set. ## Synopsis @@ -36,9 +34,9 @@ Parameter | Description ----------|------------- `name` | The name of the user whose password you want to create or add. `password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged.

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication). -`valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. -`login`/`nologin` | The `login` parameter allows a user to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `nologin`](#change-login-privileges-for-a-user) prevents the user from logging in using any authentication method. -`createrole`/`nocreaterole` | Allow or disallow the user to create, alter, and drop other users.

By default, the parameter is set to `nocreaterole` for all non-admin and non-root users. +`VALID UNTIL` | New in v20.1: The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. +`LOGIN`/`NOLOGIN` | New in v20.1: The `LOGIN` parameter allows a user to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `nologin`](#change-login-privileges-for-a-user) prevents the user from logging in using any authentication method. +`CREATEROLE`/`NOCREATEROLE` | New in v20.1: Allow or disallow the user to create, alter, and drop other users.

By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root users. ## Examples diff --git a/v20.1/authorization.md b/v20.1/authorization.md index e0912ce5369..a33792ed222 100644 --- a/v20.1/authorization.md +++ b/v20.1/authorization.md @@ -17,7 +17,7 @@ A SQL user can interact with a CockroachDB database using the [built-in SQL shel ### Create and manage users -Use the [`CREATE USER`](create-user.html) and [`DROP USER`](drop-user.html) statements to create and remove users, the [`ALTER USER`](alter-user.html) statement to add or change a user's password, the [`GRANT `](grant.html) and [`REVOKE `](revoke.html) statements to manage the user’s privileges, and the [`SHOW USERS`](show-users.html) statement to list users. +Use the [`CREATE USER`](create-user.html) and [`DROP USER`](drop-user.html) statements to create and remove users, the [`ALTER USER`](alter-user.html) statement to add or change a user's password and role options, the [`GRANT `](grant.html) and [`REVOKE `](revoke.html) statements to manage the user’s privileges, and the [`SHOW USERS`](show-users.html) statement to list users. A new user must be granted the required privileges for each database and table that the user needs to access. @@ -28,7 +28,7 @@ By default, a new user belongs to the `public` role and has no privileges other ### `root` user The `root` user is created by default for each cluster. The `root` user is assigned to the [`admin` role](#admin-role) and has all privileges across the cluster. -For secure clusters, in addition to [generating the client certificate](authentication.html#client-authentication) for the `root` user, you can assign or change the password for the `root` user using the [`ALTER USER`](alter-user.html) statement. +For secure clusters, in addition to [generating the client certificate](authentication.html#client-authentication) for the `root` user, you can assign or change the password for the `root` user using the [`ALTER USER`](alter-user.html) statement. ## Roles diff --git a/v20.1/create-role.md b/v20.1/create-role.md index 13ce62cc99f..a7b088d4594 100644 --- a/v20.1/create-role.md +++ b/v20.1/create-role.md @@ -27,9 +27,7 @@ The `CREATE ROLE` [statement](sql-statements.html) creates SQL [roles](authoriza ## Required privileges -Roles can only be created by superusers, i.e., members of the `admin` role. The `admin` role exists by default with `root` as the member. - -To create other roles, the role must have the [`createrole`](#allow-the-role-to-create-other-roles) parameter set. +New in v20.1: To create other roles, the role must have the [`CREATEROLE`](#allow-the-role-to-create-other-roles) parameter set. ## Synopsis @@ -41,9 +39,9 @@ To create other roles, the role must have the [`createrole`](#allow-the-role-to- ------------|-------------- `name` | The name of the role you want to create. Role names are case-insensitive; must start with either a letter or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters.

Note that roles and [users](create-user.html) share the same namespace and must be unique. `password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. -`valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. -`login`/`nologin` | Allow or disallow a role to login with one of the [client authentication methods](authentication.html#client-authentication).

By default, the parameter is set to `nologin` for the `CREATE ROLE` statement. -`createrole`/`nocreaterole` | Allow or disallow the new role to create, alter, and drop other roles.

By default, the parameter is set to `nocreaterole` for all non-admin and non-root users. +`VALID UNTIL` | New in v20.1: The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. +`LOGIN`/`NOLOGIN` | New in v20.1: Allow or disallow a role to login with one of the [client authentication methods](authentication.html#client-authentication).

By default, the parameter is set to `nologin` for the `CREATE ROLE` statement. +`CREATEROLE`/`NOCREATEROLE` | New in v20.1: Allow or disallow the new role to create, alter, and drop other roles.

By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root users. ## Examples diff --git a/v20.1/create-user.md b/v20.1/create-user.md index 0ff785e9e01..436cfce2d5b 100644 --- a/v20.1/create-user.md +++ b/v20.1/create-user.md @@ -23,9 +23,7 @@ The `CREATE USER` [statement](sql-statements.html) creates SQL users, which let ## Required privileges -The user must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. - -To create other users, the user must have the [`createrole`](#allow-the-user-to-create-other-users) parameter set. +New in v20.1: To create other users, the user must have the [`CREATEROLE`](#allow-the-user-to-create-other-users) parameter set. ## Synopsis @@ -43,9 +41,9 @@ table td:first-child { -----------|------------- `user_name` | The name of the user you want to create.

Usernames are case-insensitive; must start with a letter, number, or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters. `password` | Let the user [authenticate their access to a secure cluster](#user-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. -`valid until` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. -`login`/`nologin` | The `login` parameter allows a user to login with one of the [user authentication methods](#user-authentication). [Setting the parameter to `nologin`](#set-login-privileges-for-a-user) prevents the user from logging in using any authentication method.

By default, the parameter is set to `login` for the `CREATE USER` statement. -`createrole`/`nocreaterole` | Allow or disallow the new user to create, alter, and drop other users.

By default, the parameter is set to `nocreaterole` for all non-admin and non-root users. +`VALID UNTIL` | New in v20.1: The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. +`LOGIN`/`NOLOGIN` | New in v20.1: The `LOGIN` parameter allows a user to login with one of the [user authentication methods](#user-authentication). [Setting the parameter to `NOLOGIN`](#set-login-privileges-for-a-user) prevents the user from logging in using any authentication method.

By default, the parameter is set to `LOGIN` for the `CREATE USER` statement. +`CREATEROLE`/`NOCREATEROLE` | New in v20.1: Allow or disallow the new user to create, alter, and drop other users.

By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root users. ## User authentication @@ -102,7 +100,7 @@ The following statement sets the date and time after which the password is not v ### Manage users -After creating a user, you can use the [`ALTER USER`](alter-user.html) statement to add or change the user's password and the [`DROP USER`](drop-user.html) statement to the remove users. +After creating a user, you can use the [`ALTER USER`](alter-user.html) statement to add or change the user's password, update role options, and the [`DROP USER`](drop-user.html) statement to the remove users. ### Authenticate as a specific user diff --git a/v20.1/drop-role.md b/v20.1/drop-role.md index b354287050f..d5f1e3af382 100644 --- a/v20.1/drop-role.md +++ b/v20.1/drop-role.md @@ -19,7 +19,7 @@ The `DROP ROLE` [statement](sql-statements.html) removes one or more SQL roles. Roles can only be dropped by super users, i.e., members of the `admin` role. -To drop other non-admin roles, the role must have the [`createrole`](create-role.html#allow-the-role-to-create-other-roles) parameter set. +New in v20.1: To drop other non-admin roles, the role must have the [`CREATEROLE`](create-role.html#allow-the-role-to-create-other-roles) parameter set. ## Synopsis diff --git a/v20.1/drop-user.md b/v20.1/drop-user.md index 23f52986be0..539274ba970 100644 --- a/v20.1/drop-user.md +++ b/v20.1/drop-user.md @@ -12,9 +12,7 @@ The `DROP USER` [statement](sql-statements.html) removes one or more SQL users. ## Required privileges -The user must have the `DELETE` [privilege](authorization.html#assign-privileges) on the `system.users` table. - -To drop other non-admin users, the user must have the [`createrole`](create-user.html#allow-the-user-to-create-other-users) parameter set. +New in v20.1: To drop other non-admin users, the user must have the [`CREATEROLE`](create-user.html#allow-the-user-to-create-other-users) parameter set. ## Synopsis diff --git a/v20.1/gssapi_authentication.md b/v20.1/gssapi_authentication.md index d32af957d30..9da60172ff7 100644 --- a/v20.1/gssapi_authentication.md +++ b/v20.1/gssapi_authentication.md @@ -143,7 +143,7 @@ Copy the resulting keytab to the database nodes. If clients are connecting to mu ~~~ Setting the `server.host_based_authentication.configuration` [cluster setting](cluster-settings.html) cluster setting to this particular value makes it mandatory for all non-`root` users to authenticate using GSSAPI. The `root` user is always an exception and remains able to authenticate using a valid client cert or a user password. - + The `include_realm=0` option is required to tell CockroachDB to remove the `@DOMAIN.COM` realm information from the username. We don't support any advanced mapping of GSSAPI usernames to CockroachDB usernames right now. If you want to limit which realms' users can connect, you can also add one or more `krb_realm` parameters to the end of the line as a whitelist, as follows: `host all all all gss include_realm=0 krb_realm=domain.com krb_realm=corp.domain.com` The syntax is based on the `pg_hba.conf` standard for PostgreSQL which is documented [here](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html). It can be used to exclude other users from Kerberos authentication. diff --git a/v20.1/show-roles.md b/v20.1/show-roles.md index ea796e161d3..0c57128a127 100644 --- a/v20.1/show-roles.md +++ b/v20.1/show-roles.md @@ -18,7 +18,7 @@ The `SHOW ROLES` [statement](sql-statements.html) lists the roles for all databa ## Required privileges -The role must have the [`SELECT`](select-clause.html) [privilege](authorization.html#assign-privileges) on the system table. +The role must have the [`SELECT`](select-clause.html) [privilege](authorization.html#assign-privileges) on the `system.users` table. ## Example diff --git a/v20.1/show-users.md b/v20.1/show-users.md index 9b4d2a279c8..34b77caf119 100644 --- a/v20.1/show-users.md +++ b/v20.1/show-users.md @@ -18,7 +18,7 @@ The `SHOW USERS` [statement](sql-statements.html) lists the users for all databa ## Required privileges -The user must have the [`SELECT`](select-clause.html) [privilege](authorization.html#assign-privileges) on the system table. +The user must have the [`SELECT`](select-clause.html) [privilege](authorization.html#assign-privileges) on the `system.users` table. ## Example From b1ae68711c47fe9765dbaa54b3954f4c47463da6 Mon Sep 17 00:00:00 2001 From: Amruta Date: Thu, 9 Apr 2020 14:27:28 -0400 Subject: [PATCH 11/14] Username updates --- v20.1/create-role.md | 4 ++-- v20.1/create-user.md | 4 ++-- v20.1/show-roles.md | 2 +- v20.1/show-users.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/v20.1/create-role.md b/v20.1/create-role.md index a7b088d4594..1d4d493b646 100644 --- a/v20.1/create-role.md +++ b/v20.1/create-role.md @@ -15,7 +15,7 @@ The `CREATE ROLE` [statement](sql-statements.html) creates SQL [roles](authoriza - Role names: - Are case-insensitive - Must start with either a letter or underscore - - Must contain only letters, numbers, or underscores + - Must contain only letters, numbers, periods, or underscores - Must be between 1 and 63 characters. - After creating roles, you must [grant them privileges to databases and tables](grant.html). - Roles and users can be members of roles. @@ -37,7 +37,7 @@ The `CREATE ROLE` [statement](sql-statements.html) creates SQL [roles](authoriza | Parameter | Description | ------------|-------------- -`name` | The name of the role you want to create. Role names are case-insensitive; must start with either a letter or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters.

Note that roles and [users](create-user.html) share the same namespace and must be unique. +`name` | The name of the role you want to create. Role names are case-insensitive; must start with either a letter or underscore; must contain only letters, numbers, periods, or underscores; and must be between 1 and 63 characters.

Note that roles and [users](create-user.html) share the same namespace and must be unique. `password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. `VALID UNTIL` | New in v20.1: The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. `LOGIN`/`NOLOGIN` | New in v20.1: Allow or disallow a role to login with one of the [client authentication methods](authentication.html#client-authentication).

By default, the parameter is set to `nologin` for the `CREATE ROLE` statement. diff --git a/v20.1/create-user.md b/v20.1/create-user.md index 436cfce2d5b..cd08bece444 100644 --- a/v20.1/create-user.md +++ b/v20.1/create-user.md @@ -15,7 +15,7 @@ The `CREATE USER` [statement](sql-statements.html) creates SQL users, which let - Usernames: - Are case-insensitive - Must start with a letter, number, or underscore - - Must contain only letters, numbers, or underscores + - Must contain only letters, numbers, periods, or underscores - Must be between 1 and 63 characters. - After creating users, you must [grant them privileges to databases and tables](grant.html). - All users belong to the `public` role, to which you can [grant](grant.html) and [revoke](revoke.html) privileges. @@ -63,7 +63,7 @@ Secure clusters require users to authenticate their access to databases and tabl ### Create a user -Usernames are case-insensitive; must start with a letter, number, or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters. +Usernames are case-insensitive; must start with a letter, number, or underscore; must contain only letters, numbers, periods, or underscores; and must be between 1 and 63 characters. {% include copy-clipboard.html %} ~~~ sql diff --git a/v20.1/show-roles.md b/v20.1/show-roles.md index 0c57128a127..c6cd656c9ab 100644 --- a/v20.1/show-roles.md +++ b/v20.1/show-roles.md @@ -18,7 +18,7 @@ The `SHOW ROLES` [statement](sql-statements.html) lists the roles for all databa ## Required privileges -The role must have the [`SELECT`](select-clause.html) [privilege](authorization.html#assign-privileges) on the `system.users` table. +The role must have the [`SELECT`](select-clause.html) [privilege](authorization.html#assign-privileges) on the `system.users` and `system.role_members` tables. ## Example diff --git a/v20.1/show-users.md b/v20.1/show-users.md index 34b77caf119..58e1adcfb07 100644 --- a/v20.1/show-users.md +++ b/v20.1/show-users.md @@ -18,7 +18,7 @@ The `SHOW USERS` [statement](sql-statements.html) lists the users for all databa ## Required privileges -The user must have the [`SELECT`](select-clause.html) [privilege](authorization.html#assign-privileges) on the `system.users` table. +The user must have the [`SELECT`](select-clause.html) [privilege](authorization.html#assign-privileges) on the `system.users` and `system.role_members` tables. ## Example From a3ef60231cb73bbe52c08745dc0725d119dbbb2d Mon Sep 17 00:00:00 2001 From: Amruta Date: Wed, 22 Apr 2020 14:29:28 -0400 Subject: [PATCH 12/14] Worked on Jesse's comments --- _includes/sidebar-data-v20.1.json | 6 ++++++ v20.1/alter-role.md | 12 ++++++------ v20.1/alter-user.md | 4 ++-- v20.1/create-role.md | 4 ++-- v20.1/create-user.md | 4 ++-- v20.1/grant.md | 6 ++---- v20.1/gssapi_authentication.md | 2 +- v20.1/sql-statements.md | 3 ++- 8 files changed, 23 insertions(+), 18 deletions(-) diff --git a/_includes/sidebar-data-v20.1.json b/_includes/sidebar-data-v20.1.json index 5c90039aa16..f8f260341f6 100644 --- a/_includes/sidebar-data-v20.1.json +++ b/_includes/sidebar-data-v20.1.json @@ -840,6 +840,12 @@ "/${VERSION}/alter-range.html" ] }, + { + "title": "ALTER ROLE", + "urls": [ + "/${VERSION}/alter-role.html" + ] + }, { "title": "ALTER SEQUENCE", "urls": [ diff --git a/v20.1/alter-role.md b/v20.1/alter-role.md index fe86b45e4c7..623de328883 100644 --- a/v20.1/alter-role.md +++ b/v20.1/alter-role.md @@ -4,10 +4,10 @@ summary: The ALTER ROLE statement can be used to add or change a role's password toc: true --- -The `ALTER ROLE` [statement](sql-statements.html) can be used to add, change, or remove a [role's](create-role.html) password and to change the login privileges for a role. +New in v20.1: The `ALTER ROLE` [statement](sql-statements.html) can be used to add, change, or remove a [role's](create-role.html) password and to change the login privileges for a role. {{site.data.alerts.callout_info}} -New in v20.1: Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL statements for enhanced Postgres compatibility, `ALTER ROLE` is now an alias for [`ALTER USER`](alter-user.html). +Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL statements for enhanced Postgres compatibility, `ALTER ROLE` is now an alias for [`ALTER USER`](alter-user.html). {{site.data.alerts.end}} ## Considerations @@ -33,10 +33,10 @@ table td:first-child { Parameter | Description ----------|------------- `name` | The name of the role whose password you want to create or add. -`password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged.

To prevent a role from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-role-from-using-password-authentication). -`VALID UNTIL` | New in v20.1: The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. -`LOGIN`/`NOLOGIN` | New in v20.1: The `LOGIN` parameter allows a role to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `nologin`](#change-login-privileges-for-a-role) prevents the role from logging in using any authentication method. -`CREATEROLE`/`NOCREATEROLE` | New in v20.1: Allow or disallow the role to create, alter, and drop other roles.

By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root roles. +`password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier).

To prevent a role from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-role-from-using-password-authentication). +`VALID UNTIL` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. +`LOGIN`/`NOLOGIN` | The `LOGIN` parameter allows a role to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `NOLOGIN`](#change-login-privileges-for-a-role) prevents the role from logging in using any authentication method. +`CREATEROLE`/`NOCREATEROLE` | Allow or disallow the role to create, alter, and drop other roles.

By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root roles. ## Examples diff --git a/v20.1/alter-user.md b/v20.1/alter-user.md index ae12a132b8a..0c5f9fb6333 100644 --- a/v20.1/alter-user.md +++ b/v20.1/alter-user.md @@ -33,9 +33,9 @@ table td:first-child { Parameter | Description ----------|------------- `name` | The name of the user whose password you want to create or add. -`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier), although this is discouraged.

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication). +`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier).

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication). `VALID UNTIL` | New in v20.1: The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. -`LOGIN`/`NOLOGIN` | New in v20.1: The `LOGIN` parameter allows a user to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `nologin`](#change-login-privileges-for-a-user) prevents the user from logging in using any authentication method. +`LOGIN`/`NOLOGIN` | New in v20.1: The `LOGIN` parameter allows a user to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `NOLOGIN`](#change-login-privileges-for-a-user) prevents the user from logging in using any authentication method. `CREATEROLE`/`NOCREATEROLE` | New in v20.1: Allow or disallow the user to create, alter, and drop other users.

By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root users. ## Examples diff --git a/v20.1/create-role.md b/v20.1/create-role.md index 1d4d493b646..32b7474ade2 100644 --- a/v20.1/create-role.md +++ b/v20.1/create-role.md @@ -38,9 +38,9 @@ The `CREATE ROLE` [statement](sql-statements.html) creates SQL [roles](authoriza | Parameter | Description | ------------|-------------- `name` | The name of the role you want to create. Role names are case-insensitive; must start with either a letter or underscore; must contain only letters, numbers, periods, or underscores; and must be between 1 and 63 characters.

Note that roles and [users](create-user.html) share the same namespace and must be unique. -`password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. +`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier).

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication). `VALID UNTIL` | New in v20.1: The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. -`LOGIN`/`NOLOGIN` | New in v20.1: Allow or disallow a role to login with one of the [client authentication methods](authentication.html#client-authentication).

By default, the parameter is set to `nologin` for the `CREATE ROLE` statement. +`LOGIN`/`NOLOGIN` | New in v20.1: Allow or disallow a role to login with one of the [client authentication methods](authentication.html#client-authentication).

By default, the parameter is set to `NOLOGIN` for the `CREATE ROLE` statement. `CREATEROLE`/`NOCREATEROLE` | New in v20.1: Allow or disallow the new role to create, alter, and drop other roles.

By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root users. ## Examples diff --git a/v20.1/create-user.md b/v20.1/create-user.md index cd08bece444..666a29df51b 100644 --- a/v20.1/create-user.md +++ b/v20.1/create-user.md @@ -40,7 +40,7 @@ table td:first-child { Parameter | Description -----------|------------- `user_name` | The name of the user you want to create.

Usernames are case-insensitive; must start with a letter, number, or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters. -`password` | Let the user [authenticate their access to a secure cluster](#user-authentication) using this password. Passwords must be entered as [string](string.html) values surrounded by single quotes (`'`).

Password creation is supported only in secure clusters. +`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier).

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication). `VALID UNTIL` | New in v20.1: The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. `LOGIN`/`NOLOGIN` | New in v20.1: The `LOGIN` parameter allows a user to login with one of the [user authentication methods](#user-authentication). [Setting the parameter to `NOLOGIN`](#set-login-privileges-for-a-user) prevents the user from logging in using any authentication method.

By default, the parameter is set to `LOGIN` for the `CREATE USER` statement. `CREATEROLE`/`NOCREATEROLE` | New in v20.1: Allow or disallow the new user to create, alter, and drop other users.

By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root users. @@ -57,7 +57,7 @@ Secure clusters require users to authenticate their access to databases and tabl Password creation is supported only in secure clusters. -- [**GSSAPI authentication**](gssapi_authentication.html), which is available to [Enterprise users](enterprise-licensing.html). +- [GSSAPI authentication](gssapi_authentication.html), which is available to [Enterprise users](enterprise-licensing.html). ## Examples diff --git a/v20.1/grant.md b/v20.1/grant.md index 4fbc4e7f2f2..5b78499900f 100644 --- a/v20.1/grant.md +++ b/v20.1/grant.md @@ -14,9 +14,7 @@ For privileges required by specific statements, see the documentation for the re ## Required privileges -The user granting privileges must have the `GRANT` privilege on the target databases or tables. - -New in v20.1 In addition to the `GRANT` privilege, the user granting privileges must have the privilege being granted on the target database or tables. For example, a user granting the `SELECT` privilege on a table to another user must have the `GRANT` and `SELECT` privileges on that table. +New in v20.1 The user granting privileges must also have the privilege being granted on the target database or tables. For example, a user granting the `SELECT` privilege on a table to another user must have the `GRANT` and `SELECT` privileges on that table. ## Supported privileges @@ -149,7 +147,7 @@ Parameter | Description (3 rows) ~~~ -### Grant `ZONECONFIG` privilege on a database or table +### Grant the privilege to manage the replication zones for a database or table {% include copy-clipboard.html %} ~~~ sql diff --git a/v20.1/gssapi_authentication.md b/v20.1/gssapi_authentication.md index 9da60172ff7..eba079ffdbe 100644 --- a/v20.1/gssapi_authentication.md +++ b/v20.1/gssapi_authentication.md @@ -142,7 +142,7 @@ Copy the resulting keytab to the database nodes. If clients are connecting to mu > SET cluster setting server.host_based_authentication.configuration = 'host all all all gss include_realm=0'; ~~~ - Setting the `server.host_based_authentication.configuration` [cluster setting](cluster-settings.html) cluster setting to this particular value makes it mandatory for all non-`root` users to authenticate using GSSAPI. The `root` user is always an exception and remains able to authenticate using a valid client cert or a user password. + Setting the `server.host_based_authentication.configuration` [cluster setting](cluster-settings.html) to this particular value makes it mandatory for all non-`root` users to authenticate using GSSAPI. The `root` user is always an exception and remains able to authenticate using a valid client cert or a user password. The `include_realm=0` option is required to tell CockroachDB to remove the `@DOMAIN.COM` realm information from the username. We don't support any advanced mapping of GSSAPI usernames to CockroachDB usernames right now. If you want to limit which realms' users can connect, you can also add one or more `krb_realm` parameters to the end of the line as a whitelist, as follows: `host all all all gss include_realm=0 krb_realm=domain.com krb_realm=corp.domain.com` diff --git a/v20.1/sql-statements.md b/v20.1/sql-statements.md index 76401b177e4..a7969d31aad 100644 --- a/v20.1/sql-statements.md +++ b/v20.1/sql-statements.md @@ -43,7 +43,8 @@ Statement | Usage [`ALTER SEQUENCE`](alter-sequence.html) | Apply a schema change to a sequence. [`ALTER TABLE`](alter-table.html) | Apply a schema change to a table. [`ALTER TYPE`](alter-type.html) | Change a column's [data type](data-types.html). -[`ALTER USER`](alter-user.html) | Add or change a user's password. +[`ALTER USER`](alter-user.html) | add, change, or remove a user's password and to change the login privileges for a role. +[`ALTER ROLE`](alter-role.html) | Add, change, or remove a [role's](create-role.html) password and to change the login privileges for a role. [`ALTER VIEW`](alter-view.html) | Rename a view. [`COMMENT ON`](comment-on.html) | Associate a comment to a database, table, or column. [`CONFIGURE ZONE`](configure-zone.html) | Add, modify, reset, or remove a [replication zone](configure-replication-zones.html) for a database, table, index, partition, or system range. From fc2ccc6a984be4b363132ebe0eb849a1b4c36952 Mon Sep 17 00:00:00 2001 From: Amruta Date: Wed, 22 Apr 2020 15:04:35 -0400 Subject: [PATCH 13/14] Fixed broken links + minor updates --- v20.1/create-role.md | 47 +++++++++++++++++++++++++++++++++++++++++++- v20.1/create-user.md | 44 ++++++++++++++++++++++++++++++++++++++--- 2 files changed, 87 insertions(+), 4 deletions(-) diff --git a/v20.1/create-role.md b/v20.1/create-role.md index 32b7474ade2..fd90a9e6e5d 100644 --- a/v20.1/create-role.md +++ b/v20.1/create-role.md @@ -38,7 +38,7 @@ The `CREATE ROLE` [statement](sql-statements.html) creates SQL [roles](authoriza | Parameter | Description | ------------|-------------- `name` | The name of the role you want to create. Role names are case-insensitive; must start with either a letter or underscore; must contain only letters, numbers, periods, or underscores; and must be between 1 and 63 characters.

Note that roles and [users](create-user.html) share the same namespace and must be unique. -`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier).

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication). +`password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#create-a-role-with-a-password-using-an-identifier).

To prevent a role from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-role-from-using-password-authentication). `VALID UNTIL` | New in v20.1: The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. `LOGIN`/`NOLOGIN` | New in v20.1: Allow or disallow a role to login with one of the [client authentication methods](authentication.html#client-authentication).

By default, the parameter is set to `NOLOGIN` for the `CREATE ROLE` statement. `CREATEROLE`/`NOCREATEROLE` | New in v20.1: Allow or disallow the new role to create, alter, and drop other roles.

By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root users. @@ -62,6 +62,51 @@ After creating roles, you can [add users to the role](grant-roles.html) and [gra > CREATE ROLE dev with CREATEROLE; ~~~ +### Create a role with a password using a string literal + +{% include copy-clipboard.html %} +~~~ sql +> CREATE ROLE carl WITH PASSWORD 'ilov3beefjerky'; +~~~ + +~~~ +CREATE ROLE 1 +~~~ + +### Create a role with a password using an identifier + +The following statement sets the password to `ilov3beefjerky`, as above: + +{% include copy-clipboard.html %} +~~~ sql +> CREATE ROLE carl WITH PASSWORD ilov3beefjerky; +~~~ + +This is equivalent to the example in the previous section because the password contains only lowercase characters. + +In contrast, the following statement sets the password to `thereisnotomorrow`, even though the password in the syntax contains capitals, because identifiers are normalized automatically: + +{% include copy-clipboard.html %} +~~~ sql +> CREATE ROLE carl WITH PASSWORD ThereIsNoTomorrow; +~~~ + +To preserve case in a password specified using identifier syntax, use double quotes: + +{% include copy-clipboard.html %} +~~~ sql +> CREATE ROLE carl WITH PASSWORD "ThereIsNoTomorrow"; +~~~ + +### Prevent a role from using password authentication + +The following statement prevents the role from using password authentication and mandates certificate-based client authentication: + +{% include copy-clipboard.html %} +~~~ sql +> CREATE ROLE carl WITH PASSWORD NULL; +~~~ + ## See also - [Authorization](authorization.html) diff --git a/v20.1/create-user.md b/v20.1/create-user.md index 666a29df51b..a87dd1b0b80 100644 --- a/v20.1/create-user.md +++ b/v20.1/create-user.md @@ -40,7 +40,7 @@ table td:first-child { Parameter | Description -----------|------------- `user_name` | The name of the user you want to create.

Usernames are case-insensitive; must start with a letter, number, or underscore; must contain only letters, numbers, or underscores; and must be between 1 and 63 characters. -`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier).

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication). +`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#create-a-user-with-a-password-using-an-identifier).

To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication). `VALID UNTIL` | New in v20.1: The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid. `LOGIN`/`NOLOGIN` | New in v20.1: The `LOGIN` parameter allows a user to login with one of the [user authentication methods](#user-authentication). [Setting the parameter to `NOLOGIN`](#set-login-privileges-for-a-user) prevents the user from logging in using any authentication method.

By default, the parameter is set to `LOGIN` for the `CREATE USER` statement. `CREATEROLE`/`NOCREATEROLE` | New in v20.1: Allow or disallow the new user to create, alter, and drop other users.

By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root users. @@ -82,11 +82,49 @@ After creating users, you must: > CREATE USER carl with CREATEROLE; ~~~ -### Create a user with a password +### Create a user with a password using a string literal {% include copy-clipboard.html %} ~~~ sql -> CREATE USER carl WITH PASSWORD 'Q7gc8rEdS'; +> CREATE USER carl WITH PASSWORD 'ilov3beefjerky'; +~~~ + +~~~ +CREATE USER 1 +~~~ + +### Create a user with a password using an identifier + +The following statement changes the password to `ilov3beefjerky`, as above: + +{% include copy-clipboard.html %} +~~~ sql +> CREATE USER carl WITH PASSWORD ilov3beefjerky; +~~~ + +This is equivalent to the example in the previous section because the password contains only lowercase characters. + +In contrast, the following statement changes the password to `thereisnotomorrow`, even though the password in the syntax contains capitals, because identifiers are normalized automatically: + +{% include copy-clipboard.html %} +~~~ sql +> CREATE USER carl WITH PASSWORD ThereIsNoTomorrow; +~~~ + +To preserve case in a password specified using identifier syntax, use double quotes: + +{% include copy-clipboard.html %} +~~~ sql +> CREATE USER carl WITH PASSWORD "ThereIsNoTomorrow"; +~~~ + +### Prevent a user from using password authentication + +The following statement prevents the user from using password authentication and mandates certificate-based client authentication: + +{% include copy-clipboard.html %} +~~~ sql +> CREATE USER carl WITH PASSWORD NULL; ~~~ ### Set password validity From 6fd39179529a7f7396b80ca3b5e7399beeb8b135 Mon Sep 17 00:00:00 2001 From: Amruta Date: Wed, 22 Apr 2020 15:34:22 -0400 Subject: [PATCH 14/14] broken links --- v20.1/create-user.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/v20.1/create-user.md b/v20.1/create-user.md index a87dd1b0b80..f8f0404d1eb 100644 --- a/v20.1/create-user.md +++ b/v20.1/create-user.md @@ -82,7 +82,7 @@ After creating users, you must: > CREATE USER carl with CREATEROLE; ~~~ -### Create a user with a password using a string literal +### Create a user with a password {% include copy-clipboard.html %} ~~~ sql