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/_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 + +
diff --git a/v20.1/alter-role.md b/v20.1/alter-role.md new file mode 100644 index 00000000000..623de328883 --- /dev/null +++ b/v20.1/alter-role.md @@ -0,0 +1,183 @@ +--- +title: ALTER ROLE +summary: The ALTER ROLE statement can be used to add or change a role's password. +toc: true +--- + +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}} +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 + +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 + +
{% 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 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 + +### 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"; +~~~ + +### 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) +~~~ + +### 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) +- [`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..0c5f9fb6333 100644 --- a/v20.1/alter-user.md +++ b/v20.1/alter-user.md @@ -4,19 +4,19 @@ 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 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`. +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 -The user must have the `INSERT` and `UPDATE` [privileges](authorization.html#assign-privileges) on the `system.users` table. +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 @@ -33,7 +33,10 @@ 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 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. +`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 @@ -72,6 +75,68 @@ To preserve case in a password specified using identifier syntax, use double quo > ALTER USER 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 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: + +{% include copy-clipboard.html %} +~~~ sql +> ALTER USER carl WITH PASSWORD NULL; +~~~ + +### Change login privileges for a user + +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; +~~~ + +{% 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/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..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,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-role.md b/v20.1/create-role.md index d2b21ef004d..fd90a9e6e5d 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. @@ -27,7 +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. +New in v20.1: To create other roles, the role must have the [`CREATEROLE`](#allow-the-role-to-create-other-roles) parameter set. ## Synopsis @@ -37,7 +37,11 @@ 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. +`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 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. ## Examples @@ -51,6 +55,58 @@ 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; +~~~ + +### 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 337ae538d53..f8f0404d1eb 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. @@ -23,7 +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. +New in v20.1: To create other users, the user must have the [`CREATEROLE`](#allow-the-user-to-create-other-users) parameter set. ## Synopsis @@ -40,29 +40,34 @@ 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](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. ## 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. -- [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. 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 -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 -> CREATE USER jpointsman; +> CREATE USER carl; ~~~ After creating users, you must: @@ -70,18 +75,70 @@ 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). -### Create a user with a password +### 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 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 jpointsman WITH PASSWORD 'Q7gc8rEdS'; +> CREATE USER carl WITH PASSWORD NULL; ~~~ -Password creation is supported only in secure clusters for non-`root` users. The `root` user must authenticate with a client certificate and key. +### 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. +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 @@ -99,7 +156,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 @@ -110,7 +167,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 ~~~ @@ -119,11 +176,55 @@ $ cockroach sql --user=jpointsman {% include copy-clipboard.html %} ~~~ shell -$ cockroach sql --insecure --user=jpointsman +$ 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): + +{% 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/drop-role.md b/v20.1/drop-role.md index 1a00233c9af..d5f1e3af382 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. +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
{% 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..539274ba970 100644 --- a/v20.1/drop-user.md +++ b/v20.1/drop-user.md @@ -12,7 +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. +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/grant.md b/v20.1/grant.md index ca7bdc6c9c9..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 @@ -42,6 +40,7 @@ Privilege | Levels `INSERT` | Table `DELETE` | Table `UPDATE` | Table +New in v20.1 `ZONECONFIG` | Database, Table ## Parameters @@ -148,6 +147,14 @@ Parameter | Description (3 rows) ~~~ +### Grant the privilege to manage the replication zones for 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 +164,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) diff --git a/v20.1/gssapi_authentication.md b/v20.1/gssapi_authentication.md index f6692ccb8d6..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) 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) 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/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. diff --git a/v20.1/show-roles.md b/v20.1/show-roles.md index c47f7fae25e..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 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.users` and `system.role_members` tables. ## 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..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 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 @@ -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 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.