Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document function rules for File-based Access Control #14774

Merged
merged 1 commit into from
Nov 4, 2022
Merged

Document function rules for File-based Access Control #14774

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 139 additions & 3 deletions docs/src/main/sphinx/security/file-system-access-control.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,12 @@ cluster in a single JSON file.
Configuration
-------------

.. warning::
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be part of the release notes. If we add warnings like that we may end up with messy docs.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, and it should be in a breaking change section, as this will break expected security behaviors.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was told though that there are no special sections, and release notes are generated from issues?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Release notes are not generated. We write them .. but we do not have a dedicated breaking changes section. But this can be added .. probably was already .. @colebow ?

Also the warning is still appropriate .. maybe without the version info and past behavior though

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I remove information about Trino versions

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we still need this too in release notes.


Access to all functions including :doc:`table functions </functions/table>` is allowed by default.
To mitigate unwanted access, you must add a ``function``
:ref:`rule <system-file-function-rules>` to deny the ``TABLE`` function type.

To use the access control plugin, add an ``etc/access-control.properties`` file
containing two required properties: ``access-control.name``, which must be set
to ``file``, and ``security.config-file``, which must be set to the location
Expand Down Expand Up @@ -106,6 +112,28 @@ DELETE FROM all delete
UPDATE all update
==================================== ========== ======= ==================== ===================================================

Permissions required for executing functions:

.. list-table::
:widths: 30, 10, 15, 15, 30
:header-rows: 1

* - SQL command
- Catalog
- Function permission
- Function kind
- Note
* - ``SELECT function()``
-
- ``execute``, ``grant_execute*``
- ``aggregate``, ``scalar``, ``window``
- ``grant_execute`` is required when function is executed with view owner privileges.
* - ``SELECT FROM TABLE(table_function())``
- ``all``
- ``execute``, ``grant_execute*``
- ``table``
- ``grant_execute`` is required when :doc:`table function </functions/table>` is executed with view owner privileges.

.. _system-file-auth-visibility:

Visibility
Expand All @@ -117,10 +145,10 @@ items do not need to already exist as any potential permission makes the item
visible. Specifically:

* ``catalog``: Visible if user is the owner of any nested schema, has
permissions on any nested table, or has permissions to set session properties
in the catalog.
permissions on any nested table or :doc:`table function </functions/table>`, or has permissions to
set session properties in the catalog.
* ``schema``: Visible if the user is the owner of the schema, or has permissions
on any nested table.
on any nested table or :doc:`table function </functions/table>`.
* ``table``: Visible if the user has any permissions on the table.

Catalog rules
Expand Down Expand Up @@ -331,6 +359,96 @@ The example below defines the following table access policy:
]
}

.. _system-file-function-rules:

Function rules
^^^^^^^^^^^^^^

These rules control the user's ability to execute SQL all function kinds,
such as :doc:`aggregate functions </functions/aggregate>`, scalar functions,
:doc:`table functions </functions/table>` and :doc:`window functions </functions/window>`.

huberty89 marked this conversation as resolved.
Show resolved Hide resolved
Each function rule is composed of the following fields:

* ``user`` (optional): regular expression to match against user name.
Defaults to ``.*``.
* ``role`` (optional): regular expression to match against role names.
Defaults to ``.*``.
* ``group`` (optional): regular expression to match against group names.
Defaults to ``.*``.
* ``catalog`` (optional): regular expression to match against catalog name.
Defaults to ``.*``.
* ``schema`` (optional): regular expression to match against schema name.
Defaults to ``.*``.
* ``function`` (optional): regular expression to match against function names.
Defaults to ``.*``.
* ``privileges`` (required): zero or more of ``EXECUTE``, ``GRANT_EXECUTE``.
* ``function_kinds`` (required): one or more of ``AGGREGATE``, ``SCALAR``,
``TABLES``, ``WINDOW``. When a user defines a rule for ``AGGREGATE``, ``SCALAR``
or ``WINDOW`` functions, the ``catalog`` and ``schema`` fields are disallowed
because those functions are available globally without any catalogs involvement.

huberty89 marked this conversation as resolved.
Show resolved Hide resolved
To deny all :doc:`table functions </functions/table>` from any catalog,
use the following rules:

.. code-block:: json

{
"functions": [
{
"privileges": [
"EXECUTE",
"GRANT_EXECUTE"
],
"function_kinds": [
"SCALAR",
"AGGREGATE",
"WINDOW"
]
},
{
"privileges": [],
"function_kinds": [
"TABLE"
]
}
]
}

It's a good practice to limit access to ``query`` table function because this
table function works like a query passthrough and ignores ``tables`` rules.
The following example allows the ``admin`` user to execute ``query`` table
function from any catalog:

.. code-block:: json

{
"functions": [
{
"privileges": [
"EXECUTE",
"GRANT_EXECUTE"
],
"function_kinds": [
"SCALAR",
"AGGREGATE",
"WINDOW"
]
},
{
"user": "admin",
"function": "query",
"privileges": [
"EXECUTE"
],
"function_kinds": [
"TABLE"
]
}
]
}


.. _system-file-auth-session-property:

Session property rules
Expand Down Expand Up @@ -633,6 +751,24 @@ These rules apply to ``filter_environment`` and ``mask_environment``.

``mask`` can contain conditional expressions such as ``IF`` or ``CASE``, which achieves conditional masking.

Function rules
^^^^^^^^^^^^^^

Each function rule is composed of the following fields:

* ``user`` (optional): regular expression to match against user name.
Defaults to ``.*``.
* ``group`` (optional): regular expression to match against group names.
Defaults to ``.*``.
* ``schema`` (optional): regular expression to match against schema name.
Defaults to ``.*``.
* ``function`` (optional): regular expression to match against function names.
Defaults to ``.*``.
* ``privileges`` (required): zero or more of ``EXECUTE``, ``GRANT_EXECUTE``.
* ``function_kinds`` (required): one or more of ``AGGREGATE``, ``SCALAR``,
``TABLES``, ``WINDOW``. When a user defines a rule for ``AGGREGATE``, ``SCALAR``
or ``WINDOW`` functions, the ``catalog`` and ``schema`` fields are disallowed.
huberty89 marked this conversation as resolved.
Show resolved Hide resolved

Session property rules
^^^^^^^^^^^^^^^^^^^^^^

Expand Down