Add a SET option to the GRANT command.

Similar to how the INHERIT option controls whether or not the
permissions of the granted role are automatically available to the
grantee, the new SET permission controls whether or not the grantee
may use the SET ROLE command to assume the privileges of the granted
role.

In addition, the new SET permission controls whether or not it
is possible to transfer ownership of objects to the target role
or to create new objects owned by the target role using commands
such as CREATE DATABASE .. OWNER. We could alternatively have made
this controlled by the INHERIT option, or allow it when either
option is given. An advantage of this approach is that if you
are granted a predefined role with INHERIT TRUE, SET FALSE, you
can't go and create objects owned by that role.

The underlying theory here is that the ability to create objects
as a target role is not a privilege per se, and thus does not
depend on whether you inherit the target role's privileges. However,
it's surely something you could do anyway if you could SET ROLE
to the target role, and thus making it contingent on whether you
have that ability is reasonable.

Design review by Nathan Bossat, Wolfgang Walther, Jeff Davis,
Peter Eisentraut, and Stephen Frost.

Discussion: http://postgr.es/m/CA+Tgmob+zDSRS6JXYrgq0NWdzCXuTNzT5eK54Dn2hhgt17nm8A@mail.gmail.com

6 files changed, 64 insertions, 25 deletions

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 00f833d210..9ed2b020b7 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1727,6 +1727,17 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        granted role
       </para></entry>
      </row>
+
+     <row>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>set_option</structfield> <type>bool</type>
+      </para>
+      <para>
+       True if the member can
+       <link linkend="sql-set-role"><command>SET ROLE</command></link>
+       to the granted role
+      </para></entry>
+     </row>
     </tbody>
    </tgroup>
   </table>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6e0425cb3d..82fba48d5f 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -23033,11 +23033,14 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
        <para>
         Does user have privilege for role?
         Allowable privilege types are
-        <literal>MEMBER</literal> and <literal>USAGE</literal>.
+        <literal>MEMBER</literal>, <literal>USAGE</literal>,
+        and <literal>SET</literal>.
         <literal>MEMBER</literal> denotes direct or indirect membership in
-        the role (that is, the right to do <command>SET ROLE</command>), while
+        the role without regard to what specific privileges may be conferred.
         <literal>USAGE</literal> denotes whether the privileges of the role
-        are immediately available without doing <command>SET ROLE</command>.
+        are immediately available without doing <command>SET ROLE</command>,
+        while <literal>SET</literal> denotes whether it is possible to change
+        to the role using the <literal>SET ROLE</literal> command.
         This function does not allow the special case of
         setting <parameter>user</parameter> to <literal>public</literal>,
         because the PUBLIC pseudo-role can never be a member of real roles.
diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index dea19cd348..d5911ff942 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -98,7 +98,7 @@ GRANT { USAGE | ALL [ PRIVILEGES ] }
     [ GRANTED BY <replaceable class="parameter">role_specification</replaceable> ]
 
 GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replaceable class="parameter">role_specification</replaceable> [, ...]
-    [ WITH { ADMIN | INHERIT } { OPTION | TRUE | FALSE } ]
+    [ WITH { ADMIN | INHERIT | SET } { OPTION | TRUE | FALSE } ]
     [ GRANTED BY <replaceable class="parameter">role_specification</replaceable> ]
 
 <phrase>where <replaceable class="parameter">role_specification</replaceable> can be:</phrase>
@@ -250,17 +250,17 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
   <para>
    This variant of the <command>GRANT</command> command grants membership
    in a role to one or more other roles.  Membership in a role is significant
-   because it conveys the privileges granted to a role to each of its
-   members.
+   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 actualy permisions conferred depend on
+   the options associated with the grant.
   </para>
 
   <para>
-   The effect of membership in a role can be modified by specifying the
-   <literal>ADMIN</literal> or <literal>INHERIT</literal> option, each
-   of which can be set to either <literal>TRUE</literal> or
-   <literal>FALSE</literal>. The keyword <literal>OPTION</literal> is accepted
-   as a synonym for <literal>TRUE</literal>, so that
-   <literal>WITH ADMIN OPTION</literal>
+   Each of the options described below can be set to either
+   <literal>TRUE</literal> or <literal>FALSE</literal>. The keyword
+   <literal>OPTION</literal> is accepted as a synonym for
+   <literal>TRUE</literal>, so that <literal>WITH ADMIN OPTION</literal>
    is a synonym for <literal>WITH ADMIN TRUE</literal>.
   </para>
 
@@ -272,7 +272,8 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
    OPTION</literal> on itself.  Database superusers can grant or revoke
    membership in any role to anyone.  Roles having
    <literal>CREATEROLE</literal> privilege can grant or revoke membership
-   in any role that is not a superuser.
+   in any role that is not a superuser. This option defaults to
+   <literal>FALSE</literal>.
   </para>
 
   <para>
@@ -288,6 +289,17 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
   </para>
 
   <para>
+   The <literal>SET</literal> option, if it is set to
+   <literal>TRUE</literal>, allows the member to change to the granted
+   role using the
+   <link linkend="sql-set-role"><command>SET ROLE</command></link>
+   command. If a role is an indirect member of another role, it can use
+   <literal>SET ROLE</literal> to change to that role only if there is a
+   chain of grants each of which has <literal>SET TRUE</literal>.
+   This option defaults to <literal>TRUE</literal>.
+  </para>
+
+  <para>
    If <literal>GRANTED BY</literal> is specified, the grant is recorded as
    having been done by the specified role. A user can only attribute a grant
    to another role if they possess the privileges of that role. The role
diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml
index 4fd4bfb3d7..2db66bbf37 100644
--- a/doc/src/sgml/ref/revoke.sgml
+++ b/doc/src/sgml/ref/revoke.sgml
@@ -125,7 +125,7 @@ REVOKE [ GRANT OPTION FOR ]
     [ GRANTED BY <replaceable class="parameter">role_specification</replaceable> ]
     [ CASCADE | RESTRICT ]
 
-REVOKE [ { ADMIN | INHERIT } OPTION FOR ]
+REVOKE [ { ADMIN | INHERIT | SET } OPTION FOR ]
     <replaceable class="parameter">role_name</replaceable> [, ...] FROM <replaceable class="parameter">role_specification</replaceable> [, ...]
     [ GRANTED BY <replaceable class="parameter">role_specification</replaceable> ]
     [ CASCADE | RESTRICT ]
@@ -209,9 +209,9 @@ REVOKE [ { ADMIN | INHERIT } OPTION FOR ]
 
   <para>
    Just as <literal>ADMIN OPTION</literal> can be removed from an existing
-   role grant, it is also possible to revoke <literal>INHERIT OPTION</literal>.
-   This is equivalent to setting the value of that option to
-   <literal>FALSE</literal>.
+   role grant, it is also possible to revoke <literal>INHERIT OPTION</literal>
+   or <literal>SET OPTION</literal>.  This is equivalent to setting the value
+   of the corresponding option to <literal>FALSE</literal>.
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/set_role.sgml b/doc/src/sgml/ref/set_role.sgml
index deecfe4120..13bad1bf66 100644
--- a/doc/src/sgml/ref/set_role.sgml
+++ b/doc/src/sgml/ref/set_role.sgml
@@ -77,14 +77,17 @@ RESET ROLE
    effectively drops all the privileges except for those which the target role
    directly possesses or inherits.  On the other hand, if the session user role
    has been granted memberships <literal>WITH INHERIT FALSE</literal>, the
-   privileges of the granted roles can't be accessed by default. However, the
+   privileges of the granted roles can't be accessed by default. However, if
+   the role was granted <literal>WITH SET TRUE</literal>, the
    session user can use <command>SET ROLE</command> to drop the privileges
    assigned directly to the session user and instead acquire the privileges
-   available to the named role.
+   available to the named role. If the role was granted <literal>WITH INHERIT
+   FALSE, SET FALSE</literal> then the privileges of that role cannot be
+   exercised either with or without <literal>SET ROLE</literal>.
   </para>
 
   <para>
-   In particular, when a superuser chooses to <command>SET ROLE</command> to a
+   Note that when a superuser chooses to <command>SET ROLE</command> to a
    non-superuser role, they lose their superuser privileges.
   </para>
 
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index fc836d5748..601fff3e6b 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -354,7 +354,8 @@ REVOKE <replaceable>group_role</replaceable> FROM <replaceable>role1</replaceabl
 
   <para>
    The members of a group role can use the privileges of the role in two
-   ways.  First, every member of a group can explicitly do
+   ways.  First, member roles that have been granted membership with the
+   <literal>SET</literal> option can do
    <link linkend="sql-set-role"><command>SET ROLE</command></link> to
    temporarily <quote>become</quote> the group role.  In this state, the
    database session has access to the privileges of the group role rather
@@ -369,13 +370,16 @@ REVOKE <replaceable>group_role</replaceable> FROM <replaceable>role1</replaceabl
 CREATE ROLE joe LOGIN;
 CREATE ROLE admin;
 CREATE ROLE wheel;
+CREATE ROLE island;
 GRANT admin TO joe WITH INHERIT TRUE;
 GRANT wheel TO admin WITH INHERIT FALSE;
+GRANT island TO joe WITH INHERIT TRUE, SET FALSE;
 </programlisting>
    Immediately after connecting as role <literal>joe</literal>, a database
    session will have use of privileges granted directly to <literal>joe</literal>
-   plus any privileges granted to <literal>admin</literal>, because <literal>joe</literal>
-   <quote>inherits</quote> <literal>admin</literal>'s privileges.  However, privileges
+   plus any privileges granted to <literal>admin</literal> and
+   <literal>island</literal>, because <literal>joe</literal>
+   <quote>inherits</quote> those privileges.  However, privileges
    granted to <literal>wheel</literal> are not available, because even though
    <literal>joe</literal> is indirectly a member of <literal>wheel</literal>, the
    membership is via <literal>admin</literal> which was granted using
@@ -384,7 +388,8 @@ GRANT wheel TO admin WITH INHERIT FALSE;
 SET ROLE admin;
 </programlisting>
    the session would have use of only those privileges granted to
-   <literal>admin</literal>, and not those granted to <literal>joe</literal>.  After:
+   <literal>admin</literal>, and not those granted to <literal>joe</literal> or
+   <literal>island</literal>.  After:
 <programlisting>
 SET ROLE wheel;
 </programlisting>
@@ -402,9 +407,14 @@ RESET ROLE;
   <note>
    <para>
     The <command>SET ROLE</command> command always allows selecting any role
-    that the original login role is directly or indirectly a member of.
+    that the original login role is directly or indirectly a member of,
+    provided that there is a chain of membership grants each of which has
+    <literal>SET TRUE</literal> (which is the default).
     Thus, in the above example, it is not necessary to become
     <literal>admin</literal> before becoming <literal>wheel</literal>.
+    On the other hand, it is not possible to become <literal>island</literal>
+    at all; <literal>joe</literal> can only access those privileges via
+    inheritance.
    </para>
   </note>