IAM doc updates

_includes/sidebar-data-v20.1.json

@@ -840,6 +840,12 @@
                   "/${VERSION}/alter-range.html"
                 ]
               },
+              {
+                "title": "<code>ALTER ROLE</code>",
+                "urls": [
+                  "/${VERSION}/alter-role.html"
+                ]
+              },
               {
                 "title": "<code>ALTER SEQUENCE</code>",
                 "urls": [

_includes/v20.1/sql/diagrams/alter_role.html

@@ -0,0 +1,29 @@
+<div><svg width="751" height="81">
+<polygon points="9 17 1 13 1 21"></polygon>
+<polygon points="17 17 9 13 9 21"></polygon>
+<rect x="31" y="3" width="62" height="32" rx="10"></rect>
+<rect x="29" y="1" width="62" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="39" y="21">ALTER</text>
+<rect x="133" y="3" width="56" height="32" rx="10"></rect>
+<rect x="131" y="1" width="56" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="141" y="21">ROLE</text>
+<rect x="133" y="47" width="56" height="32" rx="10"></rect>
+<rect x="131" y="45" width="56" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="141" y="65">USER</text>
+<rect x="249" y="35" width="34" height="32" rx="10"></rect>
+<rect x="247" y="33" width="34" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="257" y="53">IF</text>
+<rect x="303" y="35" width="70" height="32" rx="10"></rect>
+<rect x="301" y="33" width="70" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="311" y="53">EXISTS</text>
+<rect x="413" y="3" width="56" height="32"></rect>
+<rect x="411" y="1" width="56" height="32" class="nonterminal"></rect>
+<text class="nonterminal" x="421" y="21">name</text><a xlink:href="sql-grammar.html#opt_with" xlink:title="opt_with">
+<rect x="509" y="35" width="74" height="32"></rect>
+<rect x="507" y="33" width="74" height="32" class="nonterminal"></rect>
+<text class="nonterminal" x="517" y="53">opt_with</text></a><a xlink:href="sql-grammar.html#role_options" xlink:title="role_options">
+<rect x="603" y="35" width="100" height="32"></rect>
+<rect x="601" y="33" width="100" height="32" class="nonterminal"></rect>
+<text class="nonterminal" x="611" y="53">role_options</text></a><path class="line" d="m17 17 h2 m0 0 h10 m62 0 h10 m20 0 h10 m56 0 h10 m-96 0 h20 m76 0 h20 m-116 0 q10 0 10 10 m96 0 q0 -10 10 -10 m-106 10 v24 m96 0 v-24 m-96 24 q0 10 10 10 m76 0 q10 0 10 -10 m-86 10 h10 m56 0 h10 m40 -44 h10 m0 0 h134 m-164 0 h20 m144 0 h20 m-184 0 q10 0 10 10 m164 0 q0 -10 10 -10 m-174 10 v12 m164 0 v-12 m-164 12 q0 10 10 10 m144 0 q10 0 10 -10 m-154 10 h10 m34 0 h10 m0 0 h10 m70 0 h10 m20 -32 h10 m56 0 h10 m20 0 h10 m0 0 h204 m-234 0 h20 m214 0 h20 m-254 0 q10 0 10 10 m234 0 q0 -10 10 -10 m-244 10 v12 m234 0 v-12 m-234 12 q0 10 10 10 m214 0 q10 0 10 -10 m-224 10 h10 m74 0 h10 m0 0 h10 m100 0 h10 m23 -32 h-3"></path>
+<polygon points="741 17 749 13 749 21"></polygon>
+<polygon points="741 17 733 13 733 21"></polygon></svg></div>

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
+---
+
+<span class="version-tag">New in v20.1</span>: 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
+
+<span class="version-tag">New in v20.1:</span> To alter other roles, the role must have the [`CREATEROLE`](create-role.html#allow-the-role-to-create-other-roles) parameter set.
+
+## Synopsis
+
+<div>{% include {{ page.version.version }}/sql/diagrams/alter_role.html %}</div>
+
+## Parameters
+
+<style>
+table td:first-child {
+    min-width: 225px;
+}
+</style>
+
+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). <br><br>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. <br><br>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 <privileges>`](grant.html)
+- [`SHOW GRANTS`](show-grants.html)
+- [Create Security Certificates](cockroach-cert.html)
+- [Other SQL Statements](sql-statements.html)

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}}
-<span class="version-tag">New in v20.1</span>: 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`.
+<span class="version-tag">New in v20.1</span>: 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.
+<span class="version-tag">New in v20.1:</span> 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). <br><br>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` | <span class="version-tag">New in v20.1:</span> The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid.
+`LOGIN`/`NOLOGIN` | <span class="version-tag">New in v20.1:</span> 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` | <span class="version-tag">New in v20.1:</span> Allow or disallow the user to create, alter, and drop other users. <br><br>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)

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 %}

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 <privileges>`](grant.html) and [`REVOKE <privileges>`](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 <privileges>`](grant.html) and [`REVOKE <privileges>`](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