[docs][ysql]Added new default roles in ysql. (#10873)

yugabyte · Jan 5, 2022 · d104dde · d104dde
1 parent f44b377
commit d104dde
Show file tree

Hide file tree

Showing 6 changed files with 226 additions and 45 deletions.
diff --git a/docs/content/latest/secure/authorization/rbac-model.md b/docs/content/latest/secure/authorization/rbac-model.md
@@ -38,15 +38,75 @@ The role-based access control (RBAC) model in YSQL is a collection of privileges
 
 Roles in YSQL can represent individual users or a group of users. They encapsulate a set of privileges that can be assigned to other roles (or users). Roles are essential to implementing and administering access control on a YugabyteDB cluster. Below are some important points about roles:
 
-* Roles which have `LOGIN` privilege are users. Hence, all users are roles, but all roles are not users.
+* Roles which have `LOGIN` privilege are users. Hence, all users are roles, but not all roles are users.
 
 * Roles can be granted to other roles, making it possible to organize roles into a hierarchy.
 
 * Roles inherit the privileges of all other roles granted to them.
 
+YugabyteDB inherits a number of roles from PostgreSQL, including the `postgres` user, and adds several new roles. View the YugabyteDB-specific roles for your clusters with the following command (or use `\duS` to display all roles):
+
+```sql
+yugabyte=> \du
+```
+
+```output
+                                     List of roles
+  Role name   |                         Attributes                         | Member of
+--------------+------------------------------------------------------------+-----------
+ postgres     | Superuser, Create role, Create DB, Replication, Bypass RLS | {}
+ yb_extension | Cannot login                                               | {}
+ yb_fdw       | Cannot login                                               | {}
+ yugabyte     | Superuser, Create role, Create DB, Replication, Bypass RLS | {}
+```
+
+The following table describes the default YSQL roles and users in YugabyteDB clusters.
+<!-- Portions of this table are also under Database authorization in Yugabyte cloud -->
+
+| Role | Description |
+| :--- | :---------- |
+| postgres | Superuser role created during database creation. |
+| yb_extension | Role that allows non-superuser users to create PostgreSQL extensions. |
+| yb_fdw | Role that allows non-superuser users to [CREATE](https://www.postgresql.org/docs/11/sql-createforeigndatawrapper.html), [ALTER](https://www.postgresql.org/docs/11/sql-alterforeigndatawrapper.html), and [DROP](https://www.postgresql.org/docs/11/sql-dropforeigndatawrapper.html) the [Foreign data wrapper](https://www.postgresql.org/docs/12/ddl-foreign-data.html)(beta feature). |
+| yugabyte | Superuser role used during database creation, by Yugabyte support to perform maintenance operations, and for backups (using ysql_dump). |
+
+### yb_extension
+
+The `yb_extension` role allows non-superuser roles to [create extensions](../../../api/ysql/the-sql-language/statements/ddl_create_extension/). A user granted this role can create all the extensions that are bundled in YugabyteDB.
+
+Create a role `test` and grant `yb_extension` to this role.
+
+```sql
+yugabyte=# create role test;
+yugabyte=# grant yb_extension to test;
+yugabyte=# set role test;
+yugabyte=> select * from current_user;
+```
+
+```output
+ current_user
+--------------
+ test
+(1 row)
+```
+
+Create an extension as the test user and check if it's created.
+
+```sql
+yugabyte=> create extension pgcrypto;
+yugabyte=> select * from pg_extension where extname='pgcrypto';
+```
+
+```output
+ extname  | extowner | extnamespace | extrelocatable | extversion | extconfig | extcondition
+----------+----------+--------------+----------------+------------+-----------+--------------
+ pgcrypto |    16386 |         2200 | t              | 1.3        |           |
+(1 row)
+```
+
 ## Resources
 
-YSQL defines a number of specific resources, that represent underlying database objects. A resource can denote one object or a collection of objects. YSQL resources are hierarchical as described below:
+YSQL defines a number of specific resources that represent underlying database objects. A resource can represent one object or a collection of objects. YSQL resources are hierarchical as described below:
 
 * Databases and tables follow the hierarchy: `ALL DATABASES` > `DATABASE` > `TABLE`
 * ROLES are hierarchical (they can be assigned to other roles). They follow the hierarchy: `ALL ROLES` > `ROLE #1` > `ROLE #2` ...

diff --git a/docs/content/latest/secure/enable-authentication/ysql.md b/docs/content/latest/secure/enable-authentication/ysql.md
@@ -37,19 +37,19 @@ showAsideToc: true
   </li>
 </ul>
 
-YSQL authentication, the process of identifying that YSQL users are who they say they are, is based on roles. Users, groups, and roles within YugabyteDB are created using roles. Typically, a role that has login privileges is known as a *user*, while a *group* is a role that can have multiple users as members. 
+YSQL authentication, the process of identifying that YSQL users are who they say they are, is based on roles. Users, groups, and roles within YugabyteDB are created using roles. Typically, a role that has login privileges is known as a *user*, while a *group* is a role that can have multiple users as members.
 
-Users, roles, and groups allow administrators to verify whether a particular user or role is authorized to create, access, change, or remove databases or manage users and roles. Authentication verifies the identity of a user while authorization determines the verified user’s database access privileges. 
+Users, roles, and groups allow administrators to verify whether a particular user or role is authorized to create, access, change, or remove databases or manage users and roles. Authentication verifies the identity of a user while authorization determines the verified user’s database access privileges.
 
-[Authorization](../../authorization/) is the process of managing access control based on roles. For YSQL, enabling authentication automatically enables authorization and the [role-based access control (RBAC) model](../../authorization/rbac-model/), to determine the access privileges. Privileges are managed using [`GRANT`](../../../api/ysql/the-sql-language/statements/dcl_grant/), [`REVOKE`](../../../api/ysql/the-sql-language/statements/dcl_revoke/), [`CREATE ROLE`](../../../api/ysql/the-sql-language/statements/dcl_create_role/), [`ALTER ROLE`](../../../api/ysql/the-sql-language/statements/dcl_alter_role/), and [`DROP ROLE`](../../../api/ysql/the-sql-language/statements/dcl_drop_role/). 
+[Authorization](../../authorization/) is the process of managing access control based on roles. For YSQL, enabling authentication automatically enables authorization and the [role-based access control (RBAC) model](../../authorization/rbac-model/), to determine the access privileges. Privileges are managed using [`GRANT`](../../../api/ysql/the-sql-language/statements/dcl_grant/), [`REVOKE`](../../../api/ysql/the-sql-language/statements/dcl_revoke/), [`CREATE ROLE`](../../../api/ysql/the-sql-language/statements/dcl_create_role/), [`ALTER ROLE`](../../../api/ysql/the-sql-language/statements/dcl_alter_role/), and [`DROP ROLE`](../../../api/ysql/the-sql-language/statements/dcl_drop_role/).
 
 Users and roles can be created with superuser, non-superuser, and login privileges, and the roles that users have are used to determine what access privileges are available. Administrators can create users and roles using the [`CREATE ROLE`](../../../api/ysql/the-sql-language/statements/dcl_create_role/) statement (or its alias, [`CREATE USER`](../../../api/ysql/the-sql-language/statements/dcl_create_user/)). After users and roles have been created, [`ALTER ROLE`](../../../api/ysql/the-sql-language/statements/dcl_alter_role/) and [`DROP ROLE`](../../../api/ysql/the-sql-language/statements/dcl_drop_role/) statements are used to change or remove users and roles.
 
 ## Default user and password
 
-When you start a YugabyteDB cluster, the YB-Master and YB-TServer services are launched using the default user, named `yugabyte`, and then this user is connected to the default database, also named `yugabyte`. 
+When you start a YugabyteDB cluster, the YB-Master and YB-TServer services are launched using the default user, named `yugabyte`, and then this user is connected to the default database, also named `yugabyte`.
 
-Once YSQL authentication is enabled, all users (including `yugabyte`) require a password to log in to a YugabyteDB database. The default `yugabyte` user has a default password of `yugabyte` that lets this user sign into YugabyteDB when YSQL authentication is enabled. 
+Once YSQL authentication is enabled, all users (including `yugabyte`) require a password to log in to a YugabyteDB database. The default `yugabyte` user has a default password of `yugabyte` that lets this user sign into YugabyteDB when YSQL authentication is enabled.
 
 {{< note title="Note" >}}
 Versions of YugabyteDB prior to 2.0.1 do not have a default password. In this case, before you start YugabyteDB with YSQL authentication enabled, you need to make sure that the `yugabyte` user has a password.
@@ -153,7 +153,7 @@ yugabyte=# SELECT rolname, rolsuper, rolcanlogin FROM pg_roles;
 You should see the following output.
 
 ```output
-          rolname          | rolsuper | rolcanlogin 
+          rolname          | rolsuper | rolcanlogin
 ---------------------------+----------+-------------
  postgres                  | t        | t
  pg_monitor                | f        | f
@@ -164,6 +164,8 @@ You should see the following output.
  pg_read_server_files      | f        | f
  pg_write_server_files     | f        | f
  pg_execute_server_program | f        | f
+ yb_extension              | f        | f
+ yb_fdw                    | f        | f
  yugabyte                  | t        | t
  john                      | f        | t
 (11 rows)
@@ -190,7 +192,7 @@ yugabyte=# SELECT rolname, rolsuper, rolcanlogin FROM pg_roles;
 You should see a table output similar to the following:
 
 ```output
-          rolname          | rolsuper | rolcanlogin 
+          rolname          | rolsuper | rolcanlogin
 ---------------------------+----------+-------------
  postgres                  | t        | t
  ...
@@ -212,7 +214,7 @@ yugabyte=# \du
 
 ```output
                                    List of roles
- Role name |                         Attributes                         | Member of 
+ Role name |                         Attributes                         | Member of
 -----------+------------------------------------------------------------+-----------
  admin     | Superuser                                                  | {}
  john      |                                                            | {}
@@ -279,7 +281,7 @@ yugabyte=# \du
 
 ```output
                                    List of roles
- Role name |                         Attributes                         | Member of 
+ Role name |                         Attributes                         | Member of
 -----------+------------------------------------------------------------+-----------
  admin     | Superuser                                                  | {}
  john      | Superuser                                                  | {}
@@ -327,7 +329,7 @@ yugabyte=# SELECT rolname, rolcanlogin FROM pg_roles WHERE rolname='john';
 ```
 
 ```output
- rolname | rolcanlogin 
+ rolname | rolcanlogin
 ---------+-------------
  john    | f
 (1 row)
@@ -370,7 +372,7 @@ yugabyte=# \du
 
 ```output
                                    List of roles
- Role name |                         Attributes                         | Member of 
+ Role name |                         Attributes                         | Member of
 -----------+------------------------------------------------------------+-----------
  admin     | Superuser                                                  | {}
  postgres  | Superuser, Create role, Create DB, Replication, Bypass RLS | {}

diff --git a/docs/content/stable/secure/authorization/rbac-model.md b/docs/content/stable/secure/authorization/rbac-model.md
@@ -38,15 +38,73 @@ The role-based access control (RBAC) model in YSQL is a collection of privileges
 
 Roles in YSQL can represent individual users or a group of users. They encapsulate a set of privileges that can be assigned to other roles (or users). Roles are essential to implementing and administering access control on a YugabyteDB cluster. Below are some important points about roles:
 
-* Roles which have `LOGIN` privilege are users. Hence, all users are roles, but all roles are not users.
+* Roles which have `LOGIN` privilege are users. Hence, all users are roles, but not all roles are users.
 
 * Roles can be granted to other roles, making it possible to organize roles into a hierarchy.
 
 * Roles inherit the privileges of all other roles granted to them.
 
+YugabyteDB inherits a number of roles from PostgreSQL, including the `postgres` user, and adds several new roles. View the YugabyteDB-specific roles for your clusters with the following command (or use `\duS` to display all roles):
+
+```sql
+yugabyte=> \du
+```
+
+```output
+                                     List of roles
+  Role name   |                         Attributes                         | Member of
+--------------+------------------------------------------------------------+-----------
+ postgres     | Superuser, Create role, Create DB, Replication, Bypass RLS | {}
+ yb_extension | Cannot login                                               | {}
+ yugabyte     | Superuser, Create role, Create DB, Replication, Bypass RLS | {}
+```
+
+The following table describes the default YSQL roles and users in YugabyteDB clusters.
+<!-- Portions of this table are also under Database authorization in Yugabyte cloud -->
+
+| Role | Description |
+| :--- | :---------- |
+| postgres | Superuser role created during database creation. |
+| yb_extension | Role that allows non-superuser users to create PostgreSQL extensions. |
+| yugabyte | Superuser role used during database creation, by Yugabyte support to perform maintenance operations, and for backups (using ysql_dump). |
+
+### yb_extension
+
+The `yb_extension` role allows non-superuser roles to [create extensions](../../../api/ysql/the-sql-language/statements/ddl_create_extension/). A user granted this role can create all the extensions that are bundled in YugabyteDB.
+
+Create a role `test` and grant `yb_extension` to this role.
+
+```sql
+yugabyte=# create role test;
+yugabyte=# grant yb_extension to test;
+yugabyte=# set role test;
+yugabyte=> select * from current_user;
+```
+
+```output
+ current_user
+--------------
+ test
+(1 row)
+```
+
+Create an extension as the test user and check if it's created.
+
+```sql
+yugabyte=> create extension pgcrypto;
+yugabyte=> select * from pg_extension where extname='pgcrypto';
+```
+
+```output
+ extname  | extowner | extnamespace | extrelocatable | extversion | extconfig | extcondition
+----------+----------+--------------+----------------+------------+-----------+--------------
+ pgcrypto |    16386 |         2200 | t              | 1.3        |           |
+(1 row)
+```
+
 ## Resources
 
-YSQL defines a number of specific resources, that represent underlying database objects. A resource can denote one object or a collection of objects. YSQL resources are hierarchical as described below:
+YSQL defines a number of specific resources that represent underlying database objects. A resource can represent one object or a collection of objects. YSQL resources are hierarchical as described below:
 
 * Databases and tables follow the hierarchy: `ALL DATABASES` > `DATABASE` > `TABLE`
 * ROLES are hierarchical (they can be assigned to other roles). They follow the hierarchy: `ALL ROLES` > `ROLE #1` > `ROLE #2` ...