Document role management

Extracted-From: prestodb/presto#10904

presto-docs/src/main/sphinx/connector/hive-security.rst

@@ -38,8 +38,30 @@ Property Value                                     Description
                                                    queries based on the privileges defined in Hive metastore.
                                                    To alter these privileges, use the :doc:`/sql/grant` and
                                                    :doc:`/sql/revoke` commands.
+                                                   See :ref:`hive-sql-standard-based-authorization` for details.
 ================================================== ============================================================
 
+.. _hive-sql-standard-based-authorization:
+
+SQL Standard Based Authorization
+--------------------------------
+
+When ``sql-standard`` security is enabled, Presto enforces the same SQL
+standard based authorization as Hive does.
+
+Since Presto's ``ROLE`` syntax support matches the SQL standard, and
+Hive does not exactly follow the SQL standard, there are the following
+limitations and differences:
+
+* ``CREATE ROLE role WITH ADMIN`` is not supported.
+* The ``admin`` role must be enabled to execute ``CREATE ROLE`` or ``DROP ROLE``.
+* ``GRANT role TO user GRANTED BY someone`` is not supported.
+* ``REVOKE role FROM user GRANTED BY someone`` is not supported.
+* By default, all a user's roles except ``admin`` are enabled in a new user session.
+* One particular role can be selected by executing ``SET ROLE role``.
+* ``SET ROLE ALL`` enables all of a user's roles except ``admin``.
+* The ``admin`` role must be enabled explicitly by executing ``SET ROLE admin``.
+
 Authentication
 ==============
 

presto-docs/src/main/sphinx/sql.rst

@@ -11,6 +11,7 @@ This chapter describes the SQL syntax used in Presto.
     sql/alter-table
     sql/call
     sql/commit
+    sql/create-role
     sql/create-schema
     sql/create-table
     sql/create-table-as
@@ -20,19 +21,23 @@ This chapter describes the SQL syntax used in Presto.
     sql/describe
     sql/describe-input
     sql/describe-output
+    sql/drop-role
     sql/drop-schema
     sql/drop-table
     sql/drop-view
     sql/execute
     sql/explain
     sql/explain-analyze
     sql/grant
+    sql/grant-roles
     sql/insert
     sql/prepare
     sql/reset-session
     sql/revoke
+    sql/revoke-roles
     sql/rollback
     sql/select
+    sql/set-role
     sql/set-session
     sql/show-catalogs
     sql/show-columns

presto-docs/src/main/sphinx/sql/create-role.rst

@@ -0,0 +1,49 @@
+===========
+CREATE ROLE
+===========
+
+Synopsis
+--------
+
+.. code-block:: none
+
+    CREATE ROLE role_name
+    [ WITH ADMIN ( user | USER user | ROLE role | CURRENT_USER | CURRENT_ROLE ) ]
+    [ IN catalog ]
+
+Description
+-----------
+
+``CREATE ROLE`` creates the specified role in ``catalog`` or in the
+current catalog if ``catalog`` is not specified.
+
+The optional ``WITH ADMIN`` clause causes the role to be created with
+the specified user as a role admin. A role admin has permission to drop
+or grant a role. If the optional ``WITH ADMIN`` clause is not
+specified, the role is created with current user as admin.
+
+Examples
+--------
+
+Create role ``admin`` ::
+
+    CREATE ROLE admin;
+
+Create role ``moderator`` with admin ``bob``::
+
+    CREATE ROLE moderator WITH ADMIN USER bob;
+
+Create role ``foo`` in catalog ``bar``::
+
+    CREATE ROLE foo IN bar;
+
+Limitations
+-----------
+
+Some connectors do not support role management.
+See connector documentation for more details.
+
+See Also
+--------
+
+:doc:`drop-role`, :doc:`set-role`, :doc:`grant-roles`, :doc:`revoke-roles`

presto-docs/src/main/sphinx/sql/drop-role.rst

@@ -0,0 +1,41 @@
+=========
+DROP ROLE
+=========
+
+Synopsis
+--------
+
+.. code-block:: none
+
+    DROP ROLE role_name [ IN catalog ]
+
+Description
+-----------
+
+``DROP ROLE`` drops the specified role in ``catalog`` or in the
+current catalog if ``catalog`` is not specified.
+
+For ``DROP ROLE`` statement to succeed, the user executing it should possess
+admin privileges for the given role.
+
+Examples
+--------
+
+Drop role ``admin`` ::
+
+    DROP ROLE admin;
+
+Drop role ``foo`` in catalog ``bar``::
+
+    DROP ROLE foo IN bar;
+
+Limitations
+-----------
+
+Some connectors do not support role management.
+See connector documentation for more details.
+
+See Also
+--------
+
+:doc:`create-role`, :doc:`set-role`, :doc:`grant-roles`, :doc:`revoke-roles`

presto-docs/src/main/sphinx/sql/grant-roles.rst

@@ -0,0 +1,56 @@
+===========
+GRANT ROLES
+===========
+
+Synopsis
+--------
+
+.. code-block:: none
+
+    GRANT role [, ...]
+    TO ( user | USER user | ROLE role) [, ...]
+    [ GRANTED BY ( user | USER user | ROLE role | CURRENT_USER | CURRENT_ROLE ) ]
+    [ WITH ADMIN OPTION ]
+    [ IN catalog ]
+
+Description
+-----------
+
+Grants the specified role(s) to the specified principal(s) in ``catalog`` or
+in the current catalog if ``catalog`` is not specified.
+
+If the ``WITH ADMIN OPTION`` clause is specified, the role(s) are granted
+to the users with ``GRANT`` option.
+
+For the ``GRANT`` statement for roles to succeed, the user executing it either should
+be the role admin or should possess the ``GRANT`` option for the given role.
+
+The optional ``GRANTED BY`` clause causes the role(s) to be granted with
+the specified principal as a grantor. If the ``GRANTED BY`` clause is not
+specified, the roles are granted with the current user as a grantor.
+
+Examples
+--------
+
+Grant role ``bar`` to user ``foo`` ::
+
+    GRANT bar TO USER foo;
+
+Grant roles ``bar`` and ``foo`` to user ``baz`` and role ``qux`` with admin option ::
+
+    GRANT bar, foo TO USER baz, ROLE qux WITH ADMIN OPTION;
+
+Grant role ``bar`` to user ``foo`` in catalog ``baz`` ::
+
+    GRANT bar TO USER foo IN baz;
+
+Limitations
+-----------
+
+Some connectors do not support role management.
+See connector documentation for more details.
+
+See Also
+--------
+
+:doc:`create-role`, :doc:`drop-role`, :doc:`set-role`, :doc:`revoke-roles`

presto-docs/src/main/sphinx/sql/grant.rst

@@ -18,7 +18,7 @@ Grants the specified privileges to the specified grantee.
 
 Specifying ``ALL PRIVILEGES`` grants :doc:`delete`, :doc:`insert` and :doc:`select` privileges.
 
-Specifying ``PUBLIC`` grants privileges to the ``PUBLIC`` role and hence to all users.
+Specifying ``ROLE PUBLIC`` grants privileges to the ``PUBLIC`` role and hence to all users.
 
 The optional ``WITH GRANT OPTION`` clause allows the grantee to grant these same privileges to others.
 

presto-docs/src/main/sphinx/sql/revoke-roles.rst

@@ -0,0 +1,57 @@
+============
+REVOKE ROLES
+============
+
+Synopsis
+--------
+
+.. code-block:: none
+
+    REVOKE
+    [ ADMIN OPTION FOR ]
+    role [, ...]
+    FROM ( user | USER user | ROLE role) [, ...]
+    [ GRANTED BY ( user | USER user | ROLE role | CURRENT_USER | CURRENT_ROLE ) ]
+    [ IN catalog ]
+
+Description
+-----------
+
+Revokes the specified role(s) from the specified principal(s) in ``catalog`` or
+in the current catalog if ``catalog`` is not specified.
+
+If the ``ADMIN OPTION FOR`` clause is specified, the ``GRANT`` permission is
+revoked instead of the role.
+
+For the ``REVOKE`` statement for roles to succeed, the user executing it either should
+be the role admin or should possess the ``GRANT`` option for the given role.
+
+The optional ``GRANTED BY`` clause causes the role(s) to be revoked with
+the specified principal as a revoker. If the ``GRANTED BY`` clause is not
+specified, the roles are revoked by the current user as a revoker.
+
+Examples
+--------
+
+Revoke role ``bar`` from user ``foo`` ::
+
+    REVOKE bar FROM USER foo;
+
+Revoke admin option for roles ``bar`` and ``foo`` from user ``baz`` and role ``qux`` ::
+
+    REVOKE ADMIN OPTION FOR bar, foo FROM USER baz, ROLE qux;
+
+Revoke role ``bar`` from user ``foo`` in catalog ``baz`` ::
+
+    REVOKE bar FROM USER foo IN baz;
+
+Limitations
+-----------
+
+Some connectors do not support role management.
+See connector documentation for more details.
+
+See Also
+--------
+
+:doc:`create-role`, :doc:`drop-role`, :doc:`set-role`, :doc:`grant-roles`

presto-docs/src/main/sphinx/sql/revoke.rst

@@ -18,7 +18,7 @@ Revokes the specified privileges from the specified grantee.
 
 Specifying ``ALL PRIVILEGES`` revokes :doc:`delete`, :doc:`insert` and :doc:`select` privileges.
 
-Specifying ``PUBLIC`` revokes privileges from the ``PUBLIC`` role. Users will retain privileges assigned to them directly or via other roles.
+Specifying ``ROLE PUBLIC`` revokes privileges from the ``PUBLIC`` role. Users will retain privileges assigned to them directly or via other roles.
 
 The optional ``GRANT OPTION FOR`` clause also revokes the privileges to grant the specified privileges.
 

presto-docs/src/main/sphinx/sql/set-role.rst

@@ -0,0 +1,37 @@
+========
+SET ROLE
+========
+
+Synopsis
+--------
+
+.. code-block:: none
+
+    SET ROLE ( role | ALL | NONE ) [ IN catalog ]
+
+Description
+-----------
+
+``SET ROLE`` sets the enabled role for the current session in ``catalog``
+or in the current catalog if ``catalog`` is not specified.
+
+``SET ROLE role`` enables a single specified role for the current session.
+For the ``SET ROLE role`` statement to succeed, the user executing it should
+have a grant for the given role.
+
+``SET ROLE ALL`` enables all roles that the current user has been granted for the
+current session.
+
+``SET ROLE NONE`` disables all the roles granted to the current user for the
+current session.
+
+Limitations
+-----------
+
+Some connectors do not support role management.
+See connector documentation for more details.
+
+See Also
+--------
+
+:doc:`create-role`, :doc:`drop-role`, :doc:`grant-roles`, :doc:`revoke-roles`