From 5dac191edf1816860993e5f43b817eafcece1166 Mon Sep 17 00:00:00 2001 From: Robert Haas Date: Tue, 3 Jan 2023 14:50:40 -0500 Subject: [PATCH] Improve documentation of the CREATEROLE attibute. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In user-manag.sgml, document precisely what privileges are conveyed by CREATEROLE. Make particular note of the fact that it allows changing passwords and granting access to high-privilege roles. Also remove the suggestion of using a user with CREATEROLE and CREATEDB instead of a superuser, as there is no real security advantage to this approach. Elsewhere in the documentation, adjust text that suggests that CREATEROLE only allows for role creation, and refer to the documentation in user-manag.sgml as appropriate. Patch by me, reviewed by Álvaro Herrera Discussion: http://postgr.es/m/CA+TgmoZBsPL8nPhvYecx7iGo5qpDRqa9k_AcaW1SbOjugAY1Ag@mail.gmail.com --- doc/src/sgml/ref/alter_role.sgml | 2 +- doc/src/sgml/ref/create_role.sgml | 10 +++---- doc/src/sgml/ref/createuser.sgml | 18 ++++++++---- doc/src/sgml/user-manag.sgml | 47 ++++++++++++++++++++++--------- 4 files changed, 52 insertions(+), 25 deletions(-) diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml index 43ae1629ea..583c189b69 100644 --- a/doc/src/sgml/ref/alter_role.sgml +++ b/doc/src/sgml/ref/alter_role.sgml @@ -305,7 +305,7 @@ ALTER ROLE fred VALID UNTIL 'infinity'; - Give a role the ability to create other roles and new databases: + Give a role the ability to manage other roles and create new databases: ALTER ROLE miriam CREATEROLE CREATEDB; diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml index c03b11a575..4829893422 100644 --- a/doc/src/sgml/ref/create_role.sgml +++ b/doc/src/sgml/ref/create_role.sgml @@ -119,11 +119,11 @@ in sync when changing the above synopsis! These clauses determine whether a role will be permitted to - create new roles (that is, execute CREATE ROLE). - A role with CREATEROLE privilege can also alter - and drop other roles. - If not specified, - NOCREATEROLE is the default. + create, alter, drop, comment on, change the security label for, + and grant or revoke membership in other roles. + See for more details about what + capabilities are conferred by this privilege. + If not specified, NOCREATEROLE is the default. diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml index f43b4a4ada..64d386431e 100644 --- a/doc/src/sgml/ref/createuser.sgml +++ b/doc/src/sgml/ref/createuser.sgml @@ -41,10 +41,14 @@ PostgreSQL documentation - If you wish to create a new superuser, you must connect as a - superuser, not merely with CREATEROLE privilege. + If you wish to create a role with the SUPERUSER, + REPLICATION, or BYPASSRLS privilege, + you must connect as a superuser, not merely with + CREATEROLE privilege. Being a superuser implies the ability to bypass all access permission - checks within the database, so superuser access should not be granted lightly. + checks within the database, so superuser access should not be granted + lightly. CREATEROLE also conveys + very extensive privileges. @@ -221,8 +225,12 @@ PostgreSQL documentation - The new user will be allowed to create new roles (that is, - this user will have CREATEROLE privilege). + The new user will be allowed to create, alter, drop, comment on, + change the security label for, and grant or revoke membership in + other roles; that is, + this user will have CREATEROLE privilege. + See for more details about what + capabilities are conferred by this privilege. diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml index c64c470f76..6358efe820 100644 --- a/doc/src/sgml/user-manag.sgml +++ b/doc/src/sgml/user-manag.sgml @@ -191,7 +191,7 @@ CREATE USER name; - role creationroleprivilege to create + role creationroleprivilege to create A role must be explicitly given permission to create more roles @@ -200,9 +200,38 @@ CREATE USER name; name CREATEROLE. A role with CREATEROLE privilege can alter and drop other roles, too, as well as grant or revoke membership in them. - However, to create, alter, drop, or change membership of a - superuser role, superuser status is required; - CREATEROLE is insufficient for that. + Altering a role includes most changes that can be made using + ALTER ROLE, including, for example, changing + passwords. It also includes modifications to a role that can + be made using the COMMENT and + SECURITY LABEL commands. + + + However, CREATEROLE does not convey the ability to + create SUPERUSER roles, nor does it convey any + power over SUPERUSER roles that already exist. + Furthermore, CREATEROLE does not convey the power + to create REPLICATION users, nor the ability to + grant or revoke the REPLICATION privilege, nor the + ability to modify the role properties of such users. However, it does + allow ALTER ROLE ... SET and + ALTER ROLE ... RENAME to be used on + REPLICATION roles, as well as the use of + COMMENT ON ROLE, + SECURITY LABEL ON ROLE, + and DROP ROLE. + Finally, CREATEROLE does not + confer the ability to grant or revoke the BYPASSRLS + privilege. + + + Because the CREATEROLE privilege allows a user + to grant or revoke membership even in roles to which it does not (yet) + have any access, a CREATEROLE user can obtain access + to the capabilities of every predefined role in the system, including + highly privileged roles such as + pg_execute_server_program and + pg_write_server_files. @@ -277,16 +306,6 @@ CREATE USER name; and commands for details. - - - It is good practice to create a role that has the CREATEDB - and CREATEROLE privileges, but is not a superuser, and then - use this role for all routine management of databases and roles. This - approach avoids the dangers of operating as a superuser for tasks that - do not really require it. - - - A role can also have role-specific defaults for many of the run-time configuration settings described in