From 21912e3c0262e2cfe64856e028799d6927862563 Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Thu, 1 Feb 2024 06:11:53 -0500 Subject: [PATCH] doc: improve role option documentation Role option management was changed in Postgres 16. This patch improves the docs around these changes, including CREATE ROLE's INHERIT option, inheritance handling, and grant's ability to change role options. Discussion: https://postgr.es/m/Zab9GiV63EENDcWG@momjian.us Co-authored-by: David G. Johnston Backpatch-through: 16 --- doc/src/sgml/ref/create_role.sgml | 87 +++++++++++++++++++------------ doc/src/sgml/ref/grant.sgml | 29 ++++++----- doc/src/sgml/user-manag.sgml | 8 +-- 3 files changed, 74 insertions(+), 50 deletions(-) diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml index 8dd2a6395c..f3b89e7239 100644 --- a/doc/src/sgml/ref/create_role.sgml +++ b/doc/src/sgml/ref/create_role.sgml @@ -66,6 +66,17 @@ in sync when changing the above synopsis! Note that roles are defined at the database cluster level, and so are valid in all databases in the cluster. + + + During role creation it is possible to immediately assign the newly created + role to be a member of an existing role, and also assign existing roles + to be members of the newly created role. The rules for which initial + role membership options are enabled described below in the + IN ROLE, ROLE, and + ADMIN clauses. The + command has fine-grained option control during membership creation, + and the ability to modify these options after the new role is created. + @@ -133,24 +144,21 @@ in sync when changing the above synopsis! NOINHERIT - When the GRANT statement is used to confer - membership in one role to another role, the GRANT - may use the WITH INHERIT clause to specify whether - the privileges of the granted role should be inherited - by the new member. If the GRANT statement does not - specify either inheritance behavior, the new GRANT - will be created WITH INHERIT TRUE if the member - role is set to INHERIT and to - WITH INHERIT FALSE if it is set to - NOINHERIT. + This affects the membership inheritance status when this + role is added as a member of another role, both in this and + future commands. Specifically, it controls the inheritance + status of memberships added with this command using the + IN ROLE clause, and in later commands using + the ROLE clause. It is also used as the + default inheritance status when adding this role as a member + using the GRANT command. If not specified, + INHERIT is the default. In PostgreSQL versions before 16, - the GRANT statement did not support - WITH INHERIT. Therefore, changing this role-level - property would also change the behavior of already-existing grants. - This is no longer the case. + inheritance was a role-level attribute that controlled all runtime + membership checks for that role. @@ -285,9 +293,10 @@ in sync when changing the above synopsis! The IN ROLE clause causes the new role to be automatically added as a member of the specified existing - roles. (Note that there is no option to add the new role as an - administrator; use a separate GRANT command - to do that.) + roles. The new membership will have the SET + option enabled and the ADMIN option disabled. + The INHERIT option will be enabled unless the + NOINHERIT option is specified. @@ -297,8 +306,12 @@ in sync when changing the above synopsis! The ROLE clause causes one or more specified - existing roles to be automatically added as members of the new - role. This in effect makes the new role a group. + existing roles to be automatically added as members, with the + SET option enabled. This in effect makes the + new role a group. Roles named in this clause + with role-level the INHERIT attribute will have + the INHERIT option enabled in the new membership. + New memberships will have the ADMIN option disabled. @@ -307,10 +320,10 @@ in sync when changing the above synopsis! ADMIN role_name - The ADMIN clause is like ROLE, - but the named roles are added to the new role WITH ADMIN - OPTION, giving them the right to grant membership in this role - to others. + The ADMIN clause has the same effect as + ROLE, but the named roles are added as members + of the new role with ADMIN enabled, giving + them the right to grant membership in the new role to others. @@ -353,15 +366,19 @@ in sync when changing the above synopsis! - The INHERIT attribute governs inheritance of grantable - privileges (that is, access privileges for database objects and role - memberships). It does not apply to the special role attributes set by - CREATE ROLE and ALTER ROLE. For example, being - a member of a role with CREATEDB privilege does not immediately - grant the ability to create databases, even if INHERIT is set; - it would be necessary to become that role via - SET ROLE before - creating a database. + The role attributes defined here are non-inheritable, i.e., being a + member of a role with, e.g., CREATEDB will not + allow the member to create new databases even if the membership grant + has the INHERIT option. Of course, if the membership + grant has the SET option the member role would be able to + SET ROLE to the + createdb role and then create a new database. + + + + The membership grants created by the + IN ROLE, ROLE, and ADMIN + clauses have the role executing this command as the grantee. @@ -460,8 +477,10 @@ CREATE ROLE name [ WITH ADMIN The behavior specified by the SQL standard is most closely approximated - by giving users the NOINHERIT attribute, while roles are - given the INHERIT attribute. + creating SQL-standard users as PostgreSQL + roles with the NOINHERIT option, and SQL-standard + roles as PostgreSQL roles with the + INHERIT option. diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index 1ae5770fbb..9d27b7fcde 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -249,11 +249,16 @@ GRANT role_name [, ...] TO This variant of the GRANT command grants membership - in a role to one or more other roles. Membership in a role is significant + in a role to one or more other roles, and the modification of + membership options SET, INHERIT, + and ADMIN; see + for details. Membership in a role is significant because it potentially allows access to the privileges granted to a role to each of its members, and potentially also the ability to make changes to the role itself. However, the actual permissions conferred depend on - the options associated with the grant. + the options associated with the grant. To modify that options of + an existing membership, simply specify the membership with updated + option values. @@ -261,7 +266,9 @@ GRANT role_name [, ...] TO TRUE or FALSE. The keyword OPTION is accepted as a synonym for TRUE, so that WITH ADMIN OPTION - is a synonym for WITH ADMIN TRUE. + is a synonym for WITH ADMIN TRUE. When altering + an existing membership the omission of an option results in the current + value being retained. @@ -275,15 +282,13 @@ GRANT role_name [, ...] TO - The INHERIT option, if it is set to - TRUE, causes the member to inherit the privileges of - the granted role. That is, it can automatically use whatever database - privileges have been granted to that role. If set to - FALSE, the member does not inherit the privileges - of the granted role. If this clause is not specified, it defaults to - true if the member role is set to INHERIT and to false - if the member role is set to NOINHERIT. - See CREATE ROLE. + The INHERIT option controls the inheritance status + of the new membership; see for + details on inheritance. If it is set to TRUE, + it causes the new member to inherit from the granted role. If + set to FALSE, the new member does not inherit. + If unspecified when create a new role membership this defaults to + the inheritance attribute of the role being added. diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml index 1c011ac62b..e026a4e271 100644 --- a/doc/src/sgml/user-manag.sgml +++ b/doc/src/sgml/user-manag.sgml @@ -409,10 +409,10 @@ REVOKE group_role FROM role1INHERIT option automatically have use - of the privileges of those roles, including any - privileges inherited by those roles. - As an example, suppose we have done: + INHERIT option automatically have use of the + privileges of those directly or indirectly a member of, though the + chain stops at memberships lacking the inherit option. As an example, + suppose we have done: CREATE ROLE joe LOGIN; CREATE ROLE admin;