Re: SET ROLE documentation not entirely correct

Joe Conway <[email protected]> Sat, 27 Apr 2019 16:02:13 -0400

Newsgroups	gmane.comp.db.postgresql.devel.documentation
Message-ID	<[email protected]>

On 4/25/19 11:25 AM, Steven Winfield wrote:
> Again, that's much clearer than what is currently there. It might help
> if some of the language/definitions from pg_has_role() is used, though.
> 
> For example:
> A role X is a "MEMBER" of another role Y if there is a chain of GRANTs
> from X to Y via zero or more intermediate roles. This allows X to
> execute "SET ROLE Y".
> Additionally X has "USAGE" of Y if X and all the intermediate roles (but
> *not* necessarily Y) are marked INHERIT. In this case X automatically
> has the privileges of Y, without the need to "SET ROLE Y".


I've been whacking this around for the better part of the afternoon and
came up with the attached. I think it is correct, and better than my
previous proposal, but possibly need more polish. Comments welcome.


> * A role's attributes are not inherited by its members - SUPERUSER,
> CREATEROLE, etc. The CREATE ROLE docs refer to these things as both
> "attributes" and "privileges", which is a bit unhelpful. It would be
> better to refer to them only as "attributes" everywhere, so it is clear
> that "attributes" are never inherited whereas "privileges" can be inherited.

Sounds reasonable but probably a separate patch.

Joe

-- 
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development

set-role-docs-00.diff (text/x-patch, 3.2 KB)

diff --git a/doc/src/sgml/ref/set_role.sgml b/doc/src/sgml/ref/set_role.sgml
index 0ef6eb9..d219a1e 100644
*** a/doc/src/sgml/ref/set_role.sgml
--- b/doc/src/sgml/ref/set_role.sgml
*************** RESET ROLE
*** 42,48 ****
  
    <para>
     The specified <replaceable class="parameter">role_name</replaceable>
!    must be a role that the current session user is a member of.
     (If the session user is a superuser, any role can be selected.)
    </para>
  
--- 42,48 ----
  
    <para>
     The specified <replaceable class="parameter">role_name</replaceable>
!    must be a role that the current session user is a <literal>MEMBER</literal> of.
     (If the session user is a superuser, any role can be selected.)
    </para>
  
*************** RESET ROLE
*** 63,78 ****
    <title>Notes</title>
  
    <para>
!    Using this command, it is possible to either add privileges or restrict
!    one's privileges.  If the session user role has the <literal>INHERITS</literal>
!    attribute, then it automatically has all the privileges of every role that
!    it could <command>SET ROLE</command> to; in this case <command>SET ROLE</command>
!    effectively drops all the privileges assigned directly to the session user
!    and to the other roles it is a member of, leaving only the privileges
!    available to the named role.  On the other hand, if the session user role
!    has the <literal>NOINHERITS</literal> attribute, <command>SET ROLE</command> drops the
!    privileges assigned directly to the session user and instead acquires the
!    privileges available to the named role.
    </para>
  
    <para>
--- 63,94 ----
    <title>Notes</title>
  
    <para>
!    Role "X" is a <literal>MEMBER</literal> of role "Y" if there is a chain of
!    grants between them. Additionally, role "X" has <literal>USAGE</literal>
!    of "Y", if "X", and all intermediate roles (but not necessarily "Y" itself),
!    are marked with the <literal>INHERIT</literal> attribute (which is the default).
!    See the <link linkend="functions-info"><function>pg_has_role()</function>
!    </link> for more information.
!   </para>
! 
!   <para>
!    Every role automatically has all the privileges it has been granted directly,
!    as well as that of every role with which it has <literal>USAGE</literal>.
!    However role attributes (as defined by <command>CREATE ROLE</command> or
!    <command>ALTER ROLE</command>) are not directly acquired from other roles.
!    Role attributes may only be gained via the <command>SET ROLE</command> command.
!   </para>
! 
!   <para>
!    The <command>SET ROLE</command> command drops all privileges assigned directly
!    to the session user and instead acquires the privileges available to the target
!    role, including any roles for which the target has <literal>USAGE</literal>.
!    The net effect is that the <command>SET ROLE</command> command may either add
!    privileges or restrict privileges. When the session role has
!    <literal>USAGE</literal> on the target role, the remaining privileges will be
!    equal to, or a subset of, the original privileges. On the other hand,
!    when the session role does not have <literal>USAGE</literal> on the target
!    role, the privileges may be completely different, and possibly expanded.
    </para>
  
    <para>

signature.asc (application/pgp-signature, 833 B)