RE: SET ROLE documentation not entirely correct

From: Steven Winfield <Steven(dot)Winfield(at)cantabcapital(dot)com>
To: Joe Conway <mail(at)joeconway(dot)com>, "pgsql-docs(at)lists(dot)postgresql(dot)org" <pgsql-docs(at)lists(dot)postgresql(dot)org>
Subject: RE: SET ROLE documentation not entirely correct
Date: 2019-04-25 15:25:34
Message-ID: E9FA92C2921F31408041863B74EE4C2001BD62E4D4@CCPMAILDAG03.cantab.local
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

> Additionally s/INHERITS/INHERIT/

Good spot.

> The wording should be something like
>
> 8<-----------
> The specified role_name must be a role that the current session user is
> a member of directly or indirectly.
> 8<-----------

That’s certainly much better (perhaps with a comma after “of”, if I’m being pedantic).

> I believe the paragraph you cite should be reworded, but I am at a loss
> as to how best to describe the actual situation clearly. Maybe something
> like:
>
> 8<-----------
> If the session user role has the INHERIT attribute, then it
> automatically has all the privileges of every role that it is a member
> of directly, and any that it is a member of indirectly which is not
> blocked by a NOINHERIT attribute of another reachable role; in this case
> SET ROLE 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.
> 8<-----------
>
> Thoughts?

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".

Just my 2p, but being fairly new to postgres' roles and privilege set-up I can tell you that the things I have found difficult, but important, to get my head around are:

* A role either pulls in all privileges it can (INHERIT) or none at all (NOINHERIT). It is not possible to create a role that all direct members are guaranteed to require, or not require, a "SET ROLE" to use (i.e. you can't mark a role as "inheritable" or "not inheritable")

* 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.

* As mentioned above, "X is a member of Y" implies "X can SET ROLE Y". Membership requires a GRANT chain from X to Y.

* Also mentioned above, "X has usage of Y" implies "X doesn't need to SET ROLE Y, other than to use Y's attributes". Usage requires everything apart from Y in the GRANT chain to be marked INHERIT.

Is there the ability to include diagrams or other images in the postgres docs? I think it could really help. Boxes for roles, arrows for membership - pointing from group to member (to show the flow of privileges), with a solid line if the member has INHERIT and a broken line if they have NOINHERIT... that sort of thing.

Steve.

This email is confidential. If you are not the intended recipient, please advise us immediately and delete this message.
The registered name of Cantab- part of GAM Systematic is Cantab Capital Partners LLP.
See - http://www.gam.com/en/Legal/Email+disclosures+EU for further information on confidentiality, the risks of non-secure electronic communication, and certain disclosures which we are required to make in accordance with applicable legislation and regulations.
If you cannot access this link, please notify us by reply message and we will send the contents to you.

GAM Holding AG and its subsidiaries (Cantab – GAM Systematic) will collect and use information about you in the course of your interactions with us.
Full details about the data types we collect and what we use this for and your related rights is set out in our online privacy policy at https://www.gam.com/en/legal/privacy-policy.
Please familiarise yourself with this policy and check it from time to time for updates as it supplements this notice.

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Joe Conway 2019-04-25 15:46:00 Re: SET ROLE documentation not entirely correct
Previous Message PG Doc comments form 2019-04-25 10:57:00 cube grouping