2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/user-manag.sgml -->
|
2002-08-16 06:47:43 +02:00
|
|
|
|
|
|
|
<chapter id="user-manag">
|
2005-08-15 01:35:38 +02:00
|
|
|
<title>Database Roles and Privileges</title>
|
2000-06-18 23:24:54 +02:00
|
|
|
|
|
|
|
<para>
|
2005-08-15 01:35:38 +02:00
|
|
|
<productname>PostgreSQL</productname> manages database access permissions
|
|
|
|
using the concept of <firstterm>roles</>. A role can be thought of as
|
|
|
|
either a database user, or a group of database users, depending on how
|
|
|
|
the role is set up. Roles can own database objects (for example,
|
|
|
|
tables) and can assign privileges on those objects to other roles to
|
|
|
|
control who has access to which objects. Furthermore, it is possible
|
|
|
|
to grant <firstterm>membership</> in a role to another role, thus
|
2010-02-03 18:25:06 +01:00
|
|
|
allowing the member role to use privileges assigned to another role.
|
2002-09-25 23:16:10 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2005-08-15 01:35:38 +02:00
|
|
|
The concept of roles subsumes the concepts of <quote>users</> and
|
|
|
|
<quote>groups</>. In <productname>PostgreSQL</productname> versions
|
|
|
|
before 8.1, users and groups were distinct kinds of entities, but now
|
|
|
|
there are only roles. Any role can act as a user, a group, or both.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This chapter describes how to create and manage roles and introduces
|
2002-09-25 23:16:10 +02:00
|
|
|
the privilege system. More information about the various types of
|
2005-08-15 01:35:38 +02:00
|
|
|
database objects and the effects of privileges can be found in
|
|
|
|
<xref linkend="ddl">.
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
|
|
|
|
2005-08-15 01:35:38 +02:00
|
|
|
<sect1 id="database-roles">
|
|
|
|
<title>Database Roles</title>
|
2000-06-18 23:24:54 +02:00
|
|
|
|
2005-08-15 01:35:38 +02:00
|
|
|
<indexterm zone="database-roles">
|
|
|
|
<primary>role</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm zone="database-roles">
|
2003-08-31 19:32:24 +02:00
|
|
|
<primary>user</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm>
|
2005-08-15 01:35:38 +02:00
|
|
|
<primary>CREATE ROLE</primary>
|
2003-08-31 19:32:24 +02:00
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm>
|
2005-08-15 01:35:38 +02:00
|
|
|
<primary>DROP ROLE</primary>
|
2003-08-31 19:32:24 +02:00
|
|
|
</indexterm>
|
|
|
|
|
2000-06-18 23:24:54 +02:00
|
|
|
<para>
|
2005-08-15 01:35:38 +02:00
|
|
|
Database roles are conceptually completely separate from
|
2000-06-18 23:24:54 +02:00
|
|
|
operating system users. In practice it might be convenient to
|
2005-08-15 01:35:38 +02:00
|
|
|
maintain a correspondence, but this is not required. Database roles
|
|
|
|
are global across a database cluster installation (and not
|
|
|
|
per individual database). To create a role use the <xref
|
2010-04-03 09:23:02 +02:00
|
|
|
linkend="sql-createrole"> SQL command:
|
2000-06-18 23:24:54 +02:00
|
|
|
<synopsis>
|
2005-08-15 01:35:38 +02:00
|
|
|
CREATE ROLE <replaceable>name</replaceable>;
|
2000-06-18 23:24:54 +02:00
|
|
|
</synopsis>
|
|
|
|
<replaceable>name</replaceable> follows the rules for SQL
|
|
|
|
identifiers: either unadorned without special characters, or
|
2005-08-15 01:35:38 +02:00
|
|
|
double-quoted. (In practice, you will usually want to add additional
|
|
|
|
options, such as <literal>LOGIN</>, to the command. More details appear
|
|
|
|
below.) To remove an existing role, use the analogous
|
2010-04-03 09:23:02 +02:00
|
|
|
<xref linkend="sql-droprole"> command:
|
2002-09-25 23:16:10 +02:00
|
|
|
<synopsis>
|
2005-08-15 01:35:38 +02:00
|
|
|
DROP ROLE <replaceable>name</replaceable>;
|
2002-09-25 23:16:10 +02:00
|
|
|
</synopsis>
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm>
|
|
|
|
<primary>createuser</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>dropuser</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2000-06-18 23:24:54 +02:00
|
|
|
<para>
|
2005-01-08 23:13:38 +01:00
|
|
|
For convenience, the programs <xref linkend="app-createuser">
|
|
|
|
and <xref linkend="app-dropuser"> are provided as wrappers
|
2002-09-25 23:16:10 +02:00
|
|
|
around these SQL commands that can be called from the shell command
|
|
|
|
line:
|
|
|
|
<synopsis>
|
|
|
|
createuser <replaceable>name</replaceable>
|
|
|
|
dropuser <replaceable>name</replaceable>
|
|
|
|
</synopsis>
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
|
|
|
|
2005-01-08 23:13:38 +01:00
|
|
|
<para>
|
2005-08-15 01:35:38 +02:00
|
|
|
To determine the set of existing roles, examine the <structname>pg_roles</>
|
2005-01-08 23:13:38 +01:00
|
|
|
system catalog, for example
|
|
|
|
<synopsis>
|
2005-08-15 01:35:38 +02:00
|
|
|
SELECT rolname FROM pg_roles;
|
2005-01-08 23:13:38 +01:00
|
|
|
</synopsis>
|
|
|
|
The <xref linkend="app-psql"> program's <literal>\du</> meta-command
|
2005-08-15 01:35:38 +02:00
|
|
|
is also useful for listing the existing roles.
|
2005-01-08 23:13:38 +01:00
|
|
|
</para>
|
|
|
|
|
2000-06-18 23:24:54 +02:00
|
|
|
<para>
|
|
|
|
In order to bootstrap the database system, a freshly initialized
|
2005-08-15 01:35:38 +02:00
|
|
|
system always contains one predefined role. This role is always
|
|
|
|
a <quote>superuser</>, and by default (unless altered when running
|
2003-03-13 02:30:29 +01:00
|
|
|
<command>initdb</command>) it will have the same name as the
|
|
|
|
operating system user that initialized the database
|
2005-08-15 01:35:38 +02:00
|
|
|
cluster. Customarily, this role will be named
|
|
|
|
<literal>postgres</literal>. In order to create more roles you
|
|
|
|
first have to connect as this initial role.
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-02-03 18:25:06 +01:00
|
|
|
Every connection to the database server is made using the name of some
|
2005-08-15 01:35:38 +02:00
|
|
|
particular role, and this role determines the initial access privileges for
|
2010-02-03 18:25:06 +01:00
|
|
|
commands issued in that connection.
|
2005-08-15 01:35:38 +02:00
|
|
|
The role name to use for a particular database
|
2002-09-25 23:16:10 +02:00
|
|
|
connection is indicated by the client that is initiating the
|
|
|
|
connection request in an application-specific fashion. For example,
|
2003-03-13 02:30:29 +01:00
|
|
|
the <command>psql</command> program uses the
|
2005-08-15 01:35:38 +02:00
|
|
|
<option>-U</option> command line option to indicate the role to
|
2002-09-25 23:16:10 +02:00
|
|
|
connect as. Many applications assume the name of the current
|
|
|
|
operating system user by default (including
|
2003-03-13 02:30:29 +01:00
|
|
|
<command>createuser</> and <command>psql</>). Therefore it
|
2005-08-15 01:35:38 +02:00
|
|
|
is often convenient to maintain a naming correspondence between
|
|
|
|
roles and operating system users.
|
2002-09-25 23:16:10 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
The set of database roles a given client connection can connect as
|
2002-09-25 23:16:10 +02:00
|
|
|
is determined by the client authentication setup, as explained in
|
2000-06-18 23:24:54 +02:00
|
|
|
<xref linkend="client-authentication">. (Thus, a client is not
|
2010-02-03 18:25:06 +01:00
|
|
|
limited to connect as the role matching
|
2010-10-06 00:48:13 +02:00
|
|
|
its operating system user, just as a person's login name
|
2005-08-15 01:35:38 +02:00
|
|
|
need not match her real name.) Since the role
|
2002-09-25 23:16:10 +02:00
|
|
|
identity determines the set of privileges available to a connected
|
2010-02-03 18:25:06 +01:00
|
|
|
client, it is important to carefully configure privileges when setting up
|
2002-09-25 23:16:10 +02:00
|
|
|
a multiuser environment.
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
2002-09-25 23:16:10 +02:00
|
|
|
</sect1>
|
2000-06-18 23:24:54 +02:00
|
|
|
|
2005-08-15 01:35:38 +02:00
|
|
|
<sect1 id="role-attributes">
|
|
|
|
<title>Role Attributes</title>
|
2000-06-18 23:24:54 +02:00
|
|
|
|
|
|
|
<para>
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
A database role can have a number of attributes that define its
|
2000-06-18 23:24:54 +02:00
|
|
|
privileges and interact with the client authentication system.
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2005-08-15 01:35:38 +02:00
|
|
|
<term>login privilege<indexterm><primary>login privilege</></></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Only roles that have the <literal>LOGIN</> attribute can be used
|
|
|
|
as the initial role name for a database connection. A role with
|
2010-02-03 18:25:06 +01:00
|
|
|
the <literal>LOGIN</> attribute can be considered the same
|
2005-08-15 01:35:38 +02:00
|
|
|
as a <quote>database user</>. To create a role with login privilege,
|
2007-02-01 01:28:19 +01:00
|
|
|
use either:
|
2005-08-15 01:35:38 +02:00
|
|
|
<programlisting>
|
|
|
|
CREATE ROLE <replaceable>name</replaceable> LOGIN;
|
|
|
|
CREATE USER <replaceable>name</replaceable>;
|
|
|
|
</programlisting>
|
|
|
|
(<command>CREATE USER</> is equivalent to <command>CREATE ROLE</>
|
|
|
|
except that <command>CREATE USER</> assumes <literal>LOGIN</> by
|
|
|
|
default, while <command>CREATE ROLE</> does not.)
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>superuser status<indexterm><primary>superuser</></></term>
|
2000-06-18 23:24:54 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2011-01-03 12:00:09 +01:00
|
|
|
A database superuser bypasses all permission checks, except the right
|
|
|
|
to log in or the right to initiate replication. This is a
|
2005-08-15 01:35:38 +02:00
|
|
|
dangerous privilege and should not be used carelessly; it is best
|
|
|
|
to do most of your work as a role that is not a superuser.
|
|
|
|
To create a new database superuser, use <literal>CREATE ROLE
|
|
|
|
<replaceable>name</replaceable> SUPERUSER</literal>. You must do
|
2011-01-05 14:24:17 +01:00
|
|
|
this as a role that is already a superuser. Creating a superuser
|
|
|
|
will by default also grant permissions to initiate streaming
|
|
|
|
replication. For increased security this can be disallowed using
|
|
|
|
<literal>CREATE ROLE <replaceable>name</replaceable> SUPERUSER
|
|
|
|
NOREPLICATION</literal>.
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-08-31 19:32:24 +02:00
|
|
|
<term>database creation<indexterm><primary>database</><secondary>privilege to create</></></term>
|
2000-06-18 23:24:54 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2005-08-15 01:35:38 +02:00
|
|
|
A role must be explicitly given permission to create databases
|
2000-06-18 23:24:54 +02:00
|
|
|
(except for superusers, since those bypass all permission
|
2005-08-15 01:35:38 +02:00
|
|
|
checks). To create such a role, use <literal>CREATE ROLE
|
2002-08-16 06:47:43 +02:00
|
|
|
<replaceable>name</replaceable> CREATEDB</literal>.
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2005-08-15 01:35:38 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term>role creation<indexterm><primary>role</><secondary>privilege to create</></></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
A role must be explicitly given permission to create more roles
|
|
|
|
(except for superusers, since those bypass all permission
|
|
|
|
checks). To create such a role, use <literal>CREATE ROLE
|
|
|
|
<replaceable>name</replaceable> CREATEROLE</literal>.
|
|
|
|
A role with <literal>CREATEROLE</> privilege can alter and drop
|
2005-10-14 01:26:00 +02:00
|
|
|
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;
|
2010-02-03 18:25:06 +01:00
|
|
|
<literal>CREATEROLE</> is insufficient for that.
|
2005-08-15 01:35:38 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2011-01-03 12:00:09 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term>initiating replication<indexterm><primary>role</><secondary>privilege to initiate replication</></></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
A role must explicitly be given permission to initiate streaming
|
2011-01-05 14:24:17 +01:00
|
|
|
replication. A role used for streaming replication must always
|
|
|
|
have <literal>LOGIN</> permission as well. To create such a role, use
|
2011-01-03 12:00:09 +01:00
|
|
|
<literal>CREATE ROLE <replaceable>name</replaceable> REPLICATION
|
|
|
|
LOGIN</literal>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2000-06-18 23:24:54 +02:00
|
|
|
<varlistentry>
|
2003-08-31 19:32:24 +02:00
|
|
|
<term>password<indexterm><primary>password</></></term>
|
2000-06-18 23:24:54 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2002-08-16 06:47:43 +02:00
|
|
|
A password is only significant if the client authentication
|
|
|
|
method requires the user to supply a password when connecting
|
2008-10-28 13:10:44 +01:00
|
|
|
to the database. The <option>password</> and
|
|
|
|
<option>md5</> authentication methods
|
2002-08-16 06:47:43 +02:00
|
|
|
make use of passwords. Database passwords are separate from
|
2005-08-15 01:35:38 +02:00
|
|
|
operating system passwords. Specify a password upon role
|
|
|
|
creation with <literal>CREATE ROLE
|
2010-10-06 00:48:13 +02:00
|
|
|
<replaceable>name</replaceable> PASSWORD '<replaceable>string</>'</literal>.
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
|
2005-08-15 01:35:38 +02:00
|
|
|
A role's attributes can be modified after creation with
|
|
|
|
<command>ALTER ROLE</command>.<indexterm><primary>ALTER ROLE</></>
|
|
|
|
See the reference pages for the <xref linkend="sql-createrole"
|
2010-04-03 09:23:02 +02:00
|
|
|
> and <xref linkend="sql-alterrole"
|
|
|
|
> commands for details.
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
2002-09-25 23:16:10 +02:00
|
|
|
|
2005-10-14 01:26:00 +02:00
|
|
|
<tip>
|
|
|
|
<para>
|
|
|
|
It is good practice to create a role that has the <literal>CREATEDB</>
|
|
|
|
and <literal>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.
|
|
|
|
</para>
|
|
|
|
</tip>
|
|
|
|
|
2002-09-25 23:16:10 +02:00
|
|
|
<para>
|
2005-08-15 01:35:38 +02:00
|
|
|
A role can also have role-specific defaults for many of the run-time
|
2002-09-25 23:16:10 +02:00
|
|
|
configuration settings described in <xref
|
|
|
|
linkend="runtime-config">. For example, if for some reason you
|
|
|
|
want to disable index scans (hint: not a good idea) anytime you
|
2007-02-01 01:28:19 +01:00
|
|
|
connect, you can use:
|
2002-09-25 23:16:10 +02:00
|
|
|
<programlisting>
|
2010-10-06 00:48:13 +02:00
|
|
|
ALTER ROLE myname SET enable_indexscan TO off;
|
2002-09-25 23:16:10 +02:00
|
|
|
</programlisting>
|
2004-12-27 23:30:10 +01:00
|
|
|
This will save the setting (but not set it immediately). In
|
2005-08-15 01:35:38 +02:00
|
|
|
subsequent connections by this role it will appear as though
|
2010-10-06 00:48:13 +02:00
|
|
|
<literal>SET enable_indexscan TO off</literal> had been executed
|
2004-12-27 23:30:10 +01:00
|
|
|
just before the session started.
|
2002-09-25 23:16:10 +02:00
|
|
|
You can still alter this setting during the session; it will only
|
2005-08-15 01:35:38 +02:00
|
|
|
be the default. To remove a role-specific default setting, use
|
2010-02-03 18:25:06 +01:00
|
|
|
<literal>ALTER ROLE <replaceable>rolename</> RESET <replaceable>varname</></literal>.
|
2005-08-15 01:35:38 +02:00
|
|
|
Note that role-specific defaults attached to roles without
|
|
|
|
<literal>LOGIN</> privilege are fairly useless, since they will never
|
|
|
|
be invoked.
|
2002-09-25 23:16:10 +02:00
|
|
|
</para>
|
2000-06-18 23:24:54 +02:00
|
|
|
</sect1>
|
|
|
|
|
2005-10-20 21:18:01 +02:00
|
|
|
<sect1 id="privileges">
|
|
|
|
<title>Privileges</title>
|
|
|
|
|
|
|
|
<indexterm zone="privileges">
|
|
|
|
<primary>privilege</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm zone="privileges">
|
|
|
|
<primary>owner</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm zone="privileges">
|
|
|
|
<primary>GRANT</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm zone="privileges">
|
|
|
|
<primary>REVOKE</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
When an object is created, it is assigned an owner. The
|
|
|
|
owner is normally the role that executed the creation statement.
|
|
|
|
For most kinds of objects, the initial state is that only the owner
|
|
|
|
(or a superuser) can do anything with the object. To allow
|
|
|
|
other roles to use it, <firstterm>privileges</firstterm> must be
|
|
|
|
granted.
|
|
|
|
There are several different kinds of privilege: <literal>SELECT</>,
|
|
|
|
<literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>,
|
2008-09-08 02:47:41 +02:00
|
|
|
<literal>TRUNCATE</>, <literal>REFERENCES</>, <literal>TRIGGER</>,
|
2006-04-30 23:15:33 +02:00
|
|
|
<literal>CREATE</>, <literal>CONNECT</>, <literal>TEMPORARY</>,
|
|
|
|
<literal>EXECUTE</>, and <literal>USAGE</>.
|
|
|
|
For more information on the different types of privileges supported by
|
2005-10-20 21:18:01 +02:00
|
|
|
<productname>PostgreSQL</productname>, see the
|
2010-04-03 09:23:02 +02:00
|
|
|
<xref linkend="sql-grant"> reference page.
|
2005-10-20 21:18:01 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To assign privileges, the <command>GRANT</command> command is
|
|
|
|
used. So, if <literal>joe</literal> is an existing role, and
|
|
|
|
<literal>accounts</literal> is an existing table, the privilege to
|
2007-02-01 01:28:19 +01:00
|
|
|
update the table can be granted with:
|
2005-10-20 21:18:01 +02:00
|
|
|
<programlisting>
|
|
|
|
GRANT UPDATE ON accounts TO joe;
|
|
|
|
</programlisting>
|
|
|
|
The special name <literal>PUBLIC</literal> can
|
|
|
|
be used to grant a privilege to every role on the system. Writing
|
|
|
|
<literal>ALL</literal> in place of a specific privilege specifies that all
|
|
|
|
privileges that apply to the object will be granted.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To revoke a privilege, use the fittingly named
|
2010-04-03 09:23:02 +02:00
|
|
|
<xref linkend="sql-revoke"> command:
|
2005-10-20 21:18:01 +02:00
|
|
|
<programlisting>
|
|
|
|
REVOKE ALL ON accounts FROM PUBLIC;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The special privileges of an object's owner (i.e., the right to modify
|
|
|
|
or destroy the object) are always implicit in being the owner,
|
|
|
|
and cannot be granted or revoked. But the owner can choose
|
|
|
|
to revoke his own ordinary privileges, for example to make a
|
|
|
|
table read-only for himself as well as others.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
An object can be assigned to a new owner with an <command>ALTER</command>
|
|
|
|
command of the appropriate kind for the object. Superusers can always do
|
|
|
|
this; ordinary roles can only do it if they are both the current owner
|
|
|
|
of the object (or a member of the owning role) and a member of the new
|
|
|
|
owning role.
|
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
2005-08-15 01:35:38 +02:00
|
|
|
<sect1 id="role-membership">
|
|
|
|
<title>Role Membership</title>
|
2000-06-18 23:24:54 +02:00
|
|
|
|
2005-08-15 01:35:38 +02:00
|
|
|
<indexterm zone="role-membership">
|
|
|
|
<primary>role</><secondary>membership in</>
|
2003-08-31 19:32:24 +02:00
|
|
|
</indexterm>
|
|
|
|
|
2000-06-18 23:24:54 +02:00
|
|
|
<para>
|
2005-08-15 01:35:38 +02:00
|
|
|
It is frequently convenient to group users together to ease
|
|
|
|
management of privileges: that way, privileges can be granted to, or
|
|
|
|
revoked from, a group as a whole. In <productname>PostgreSQL</productname>
|
|
|
|
this is done by creating a role that represents the group, and then
|
|
|
|
granting <firstterm>membership</> in the group role to individual user
|
|
|
|
roles.
|
|
|
|
</para>
|
2005-01-08 23:13:38 +01:00
|
|
|
|
2005-08-15 01:35:38 +02:00
|
|
|
<para>
|
|
|
|
To set up a group role, first create the role:
|
2000-06-18 23:24:54 +02:00
|
|
|
<synopsis>
|
2005-08-15 01:35:38 +02:00
|
|
|
CREATE ROLE <replaceable>name</replaceable>;
|
2000-06-18 23:24:54 +02:00
|
|
|
</synopsis>
|
2005-08-15 01:35:38 +02:00
|
|
|
Typically a role being used as a group would not have the <literal>LOGIN</>
|
|
|
|
attribute, though you can set it if you wish.
|
|
|
|
</para>
|
2005-01-08 23:13:38 +01:00
|
|
|
|
2005-08-15 01:35:38 +02:00
|
|
|
<para>
|
|
|
|
Once the group role exists, you can add and remove members using the
|
2010-04-03 09:23:02 +02:00
|
|
|
<xref linkend="sql-grant"> and
|
|
|
|
<xref linkend="sql-revoke"> commands:
|
2005-01-08 23:13:38 +01:00
|
|
|
<synopsis>
|
2005-08-15 01:35:38 +02:00
|
|
|
GRANT <replaceable>group_role</replaceable> TO <replaceable>role1</replaceable>, ... ;
|
|
|
|
REVOKE <replaceable>group_role</replaceable> FROM <replaceable>role1</replaceable>, ... ;
|
2005-01-08 23:13:38 +01:00
|
|
|
</synopsis>
|
2005-08-15 01:35:38 +02:00
|
|
|
You can grant membership to other group roles, too (since there isn't
|
|
|
|
really any distinction between group roles and non-group roles). The
|
2006-08-02 18:29:49 +02:00
|
|
|
database will not let you set up circular membership loops. Also,
|
|
|
|
it is not permitted to grant membership in a role to
|
|
|
|
<literal>PUBLIC</literal>.
|
2005-01-08 23:13:38 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-02-03 18:25:06 +01:00
|
|
|
The members of a group role can use the privileges of the role in two
|
2005-08-15 01:35:38 +02:00
|
|
|
ways. First, every member of a group can explicitly do
|
2010-04-03 09:23:02 +02:00
|
|
|
<xref linkend="sql-set-role"> to
|
2005-08-15 01:35:38 +02:00
|
|
|
temporarily <quote>become</> the group role. In this state, the
|
|
|
|
database session has access to the privileges of the group role rather
|
|
|
|
than the original login role, and any database objects created are
|
|
|
|
considered owned by the group role not the login role. Second, member
|
2010-10-06 00:48:13 +02:00
|
|
|
roles that have the <literal>INHERIT</> attribute automatically have use
|
|
|
|
of the privileges of roles of which they are members, including any
|
|
|
|
privileges inherited by those roles.
|
|
|
|
As an example, suppose we have done:
|
2005-08-15 01:35:38 +02:00
|
|
|
<programlisting>
|
|
|
|
CREATE ROLE joe LOGIN INHERIT;
|
|
|
|
CREATE ROLE admin NOINHERIT;
|
|
|
|
CREATE ROLE wheel NOINHERIT;
|
|
|
|
GRANT admin TO joe;
|
|
|
|
GRANT wheel TO admin;
|
|
|
|
</programlisting>
|
|
|
|
Immediately after connecting as role <literal>joe</>, a database
|
|
|
|
session will have use of privileges granted directly to <literal>joe</>
|
|
|
|
plus any privileges granted to <literal>admin</>, because <literal>joe</>
|
|
|
|
<quote>inherits</> <literal>admin</>'s privileges. However, privileges
|
|
|
|
granted to <literal>wheel</> are not available, because even though
|
|
|
|
<literal>joe</> is indirectly a member of <literal>wheel</>, the
|
|
|
|
membership is via <literal>admin</> which has the <literal>NOINHERIT</>
|
2007-02-01 01:28:19 +01:00
|
|
|
attribute. After:
|
2005-08-15 01:35:38 +02:00
|
|
|
<programlisting>
|
|
|
|
SET ROLE admin;
|
|
|
|
</programlisting>
|
|
|
|
the session would have use of only those privileges granted to
|
2007-02-01 01:28:19 +01:00
|
|
|
<literal>admin</>, and not those granted to <literal>joe</>. After:
|
2005-08-15 01:35:38 +02:00
|
|
|
<programlisting>
|
|
|
|
SET ROLE wheel;
|
|
|
|
</programlisting>
|
|
|
|
the session would have use of only those privileges granted to
|
|
|
|
<literal>wheel</>, and not those granted to either <literal>joe</>
|
|
|
|
or <literal>admin</>. The original privilege state can be restored
|
2007-02-01 01:28:19 +01:00
|
|
|
with any of:
|
2005-08-15 01:35:38 +02:00
|
|
|
<programlisting>
|
|
|
|
SET ROLE joe;
|
|
|
|
SET ROLE NONE;
|
|
|
|
RESET ROLE;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
The <command>SET ROLE</> command always allows selecting any role
|
|
|
|
that the original login role is directly or indirectly a member of.
|
|
|
|
Thus, in the above example, it is not necessary to become
|
|
|
|
<literal>admin</> before becoming <literal>wheel</>.
|
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
In the SQL standard, there is a clear distinction between users and roles,
|
|
|
|
and users do not automatically inherit privileges while roles do. This
|
|
|
|
behavior can be obtained in <productname>PostgreSQL</productname> by giving
|
|
|
|
roles being used as SQL roles the <literal>INHERIT</> attribute, while
|
|
|
|
giving roles being used as SQL users the <literal>NOINHERIT</> attribute.
|
|
|
|
However, <productname>PostgreSQL</productname> defaults to giving all roles
|
|
|
|
the <literal>INHERIT</> attribute, for backwards compatibility with pre-8.1
|
|
|
|
releases in which users always had use of permissions granted to groups
|
|
|
|
they were members of.
|
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
|
2005-10-20 21:18:01 +02:00
|
|
|
<para>
|
|
|
|
The role attributes <literal>LOGIN</>, <literal>SUPERUSER</>,
|
|
|
|
<literal>CREATEDB</>, and <literal>CREATEROLE</> can be thought of as
|
|
|
|
special privileges, but they are never inherited as ordinary privileges
|
|
|
|
on database objects are. You must actually <command>SET ROLE</> to a
|
|
|
|
specific role having one of these attributes in order to make use of
|
2010-02-03 18:25:06 +01:00
|
|
|
the attribute. Continuing the above example, we might choose to
|
2005-10-20 21:18:01 +02:00
|
|
|
grant <literal>CREATEDB</> and <literal>CREATEROLE</> to the
|
|
|
|
<literal>admin</> role. Then a session connecting as role <literal>joe</>
|
|
|
|
would not have these privileges immediately, only after doing
|
|
|
|
<command>SET ROLE admin</>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
2005-08-15 01:35:38 +02:00
|
|
|
<para>
|
|
|
|
To destroy a group role, use <xref
|
2010-04-03 09:23:02 +02:00
|
|
|
linkend="sql-droprole">:
|
2005-01-08 23:13:38 +01:00
|
|
|
<synopsis>
|
2005-08-15 01:35:38 +02:00
|
|
|
DROP ROLE <replaceable>name</replaceable>;
|
2005-01-08 23:13:38 +01:00
|
|
|
</synopsis>
|
2005-08-15 01:35:38 +02:00
|
|
|
Any memberships in the group role are automatically revoked (but the
|
|
|
|
member roles are not otherwise affected). Note however that any objects
|
|
|
|
owned by the group role must first be dropped or reassigned to other
|
|
|
|
owners; and any permissions granted to the group role must be revoked.
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
2000-09-29 22:21:34 +02:00
|
|
|
<sect1 id="perm-functions">
|
2010-02-03 18:25:06 +01:00
|
|
|
<title>Function and Trigger Security</title>
|
2000-06-18 23:24:54 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Functions and triggers allow users to insert code into the backend
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
server that other users might execute unintentionally. Hence, both
|
2003-03-13 02:30:29 +01:00
|
|
|
mechanisms permit users to <quote>Trojan horse</quote>
|
2004-12-27 23:30:10 +01:00
|
|
|
others with relative ease. The only real protection is tight
|
2002-09-25 23:16:10 +02:00
|
|
|
control over who can define functions.
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2004-12-27 23:30:10 +01:00
|
|
|
Functions run inside the backend
|
|
|
|
server process with the operating system permissions of the
|
2005-10-15 22:12:33 +02:00
|
|
|
database server daemon. If the programming language
|
2004-12-27 23:30:10 +01:00
|
|
|
used for the function allows unchecked memory accesses, it is
|
|
|
|
possible to change the server's internal data structures.
|
2000-06-18 23:24:54 +02:00
|
|
|
Hence, among many other things, such functions can circumvent any
|
2004-12-27 23:30:10 +01:00
|
|
|
system access controls. Function languages that allow such access
|
|
|
|
are considered <quote>untrusted</>, and
|
|
|
|
<productname>PostgreSQL</productname> allows only superusers to
|
|
|
|
create functions written in those languages.
|
2000-06-18 23:24:54 +02:00
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
2002-08-16 06:47:43 +02:00
|
|
|
</chapter>
|