hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-12-17 04:24:35 +03:00
Code Issues Projects Releases Wiki Activity
ee7c7b1672
graphql-engine/docs/graphql/manual/api-reference/schema-metadata-api/permission.rst
Rakesh Emmadi d52bfcda4e
backend only insert permissions (rfc #4120) (#4224) 
* move user info related code to Hasura.User module

* the RFC #4120 implementation; insert permissions with admin secret

* revert back to old RoleName based schema maps

An attempt made to avoid duplication of schema contexts in types
if any role doesn't possess any admin secret specific schema

* fix compile errors in haskell test

* keep 'user_vars' for session variables in http-logs

* no-op refacto

* tests for admin only inserts

* update docs for admin only inserts

* updated CHANGELOG.md

* default behaviour when admin secret is not set

* fix x-hasura-role to X-Hasura-Role in pytests

* introduce effective timeout in actions async tests

* update docs for admin-secret not configured case

* Update docs/graphql/manual/api-reference/schema-metadata-api/permission.rst

Co-Authored-By: Marion Schleifer <marion@hasura.io>

* Apply suggestions from code review

Co-Authored-By: Marion Schleifer <marion@hasura.io>

* a complete iteration

backend insert permissions accessable via 'x-hasura-backend-privilege'
session variable

* console changes for backend-only permissions

* provide tooltip id; update labels and tooltips;

* requested changes

* requested changes

- remove className from Toggle component
- use appropriate function name (capitalizeFirstChar -> capitalize)

* use toggle props from definitelyTyped

* fix accidental commit

* Revert "introduce effective timeout in actions async tests"

This reverts commit b7a59c19d6.

* generate complete schema for both 'default' and 'backend' sessions

* Apply suggestions from code review

Co-Authored-By: Marion Schleifer <marion@hasura.io>

* remove unnecessary import, export Toggle as is

* update session variable in tooltip

* 'x-hasura-use-backend-only-permissions' variable to switch

* update help texts

* update docs

* update docs

* update console help text

* regenerate package-lock

* serve no backend schema when backend_only: false and header set to true

- Few type name refactor as suggested by @0x777

* update CHANGELOG.md

* Update CHANGELOG.md

* Update CHANGELOG.md

* fix a merge bug where a certain entity didn't get removed

Co-authored-by: Marion Schleifer <marion@hasura.io>
Co-authored-by: Rishichandra Wawhal <rishi@hasura.io>
Co-authored-by: rikinsk <rikin.kachhia@gmail.com>
Co-authored-by: Tirumarai Selvan <tiru@hasura.io>
2020-04-24 14:40:53 +05:30

633 lines
14 KiB
ReStructuredText
Raw Blame History

.. meta::
:description: Manage permissions with the Hasura schema/metadata API
:keywords: hasura, docs, schema/metadata API, API reference, permission
.. _api_permission:
Schema/Metadata API Reference: Permissions
==========================================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
The permission layer is designed to restrict the operations that can be
performed by various users. Permissions can be defined on various operations
(insert/select/update/delete) at a role level granularity. By default, the ``admin``
role has unrestricted access to all operations.
.. admonition:: Variables in rules
All ``X-Hasura-*`` header values can be used in the permission rules. These
values can come with the request and can be validated using webhook or can be
sent with the JWT token.
.. _create_insert_permission:
create_insert_permission
------------------------
An insert permission is used to enforce constraints on the data that is being
inserted.
Let's look at an example, a permission for the ``user`` role to insert into the
``article`` table. What is the constraint that we would like to enforce here? *A
user can only insert articles for themselves* .
.. code-block:: http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_insert_permission",
"args" : {
"table" : "article",
"role" : "user",
"permission" : {
"check" : {
"author_id" : "X-HASURA-USER-ID"
},
"set":{
"id":"X-HASURA-USER-ID"
},
"columns":["name","author_id"]
}
}
}
This reads as follows - for the ``user`` role:
* For every row that is being inserted into the *article* table, allow insert only if the ``check`` passes i.e. that the ``author_id`` column value is the same as the value in the request header ``X-HASURA-USER-ID``".
* If the above ``check`` passes, then access for insert will be limited to columns ``name`` and ``author_id`` only.
* When this insert happens, the value of the column ``id`` will be automatically ``set`` to the value of the resolved session variable ``X-HASURA-USER-ID``.
The argument for ``check`` is a boolean expression which has the same syntax as the ``where`` clause in the ``select`` query, making it extremely expressive. For example,
.. code-block:: http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_insert_permission",
"args" : {
"table" : "article",
"role" : "user",
"permission" : {
"check" : {
"author_id" : "X-HASURA-USER-ID",
"$or" : [
{
"category" : "editorial",
"is_reviewed" : false
},
{
"category" : { "$neq" : "editorial"}
}
]
}
}
}
}
In the above definition, the row is allowed to be inserted if the ``author_id``
is the same as the request's user id and ``is_reviewed`` is ``false`` when the
``category`` is "editorial".
.. _create_insert_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - permission
- true
- InsertPermission_
- The permission definition
* - comment
- false
- text
- Comment
.. _InsertPermission:
InsertPermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - check
- true
- :ref:`BoolExp`
- This expression has to hold true for every new row that is inserted
* - set
- false
- :ref:`ColumnPresetExp`
- Preset values for columns that can be sourced from session variables or static values
* - columns
- false
- :ref:`PGColumn` array (or) ``'*'``
- Can insert into only these columns (or all when ``'*'`` is specified)
* - backend_only
- false
- Boolean
- When set to ``true`` the mutation is accessible only if ``x-hasura-use-backend-only-permissions``
session variable exists and is set to ``true`` and request is made with ``x-hasura-admin-secret``
set if any auth is configured
.. _drop_insert_permission:
drop_insert_permission
----------------------
Drop an existing insert permission for a role on a table.
.. _drop_insert_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
.. _create_select_permission:
create_select_permission
------------------------
A select permission is used to restrict access to only the specified columns and rows.
Let's look at an example, a permission for the ``user`` role to select from the
``article`` table: all columns can be read, as well as the rows that have been published or
authored by the user themselves.
.. code-block:: http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_select_permission",
"args" : {
"table" : "article",
"role" : "user",
"permission" : {
"columns" : "*",
"filter" : {
"$or" : [
{ "author_id" : "X-HASURA-USER-ID" },
{ "is_published" : true }
]
},
"limit": 10,
"allow_aggregations": true
}
}
}
This reads as follows - For the ``user`` role:
* Allow selecting rows where the ``check`` passes i.e. ``is_published`` is ``true`` or the ``author_id`` matches the value of the session variable ``X-HASURA-USER-ID``.
* Allow selecting all columns (because the ``columns`` key is set to ``*``).
* ``limit`` the numbers of rows returned by this query to a maximum of 10.
* Allow aggregate queries.
.. _create_select_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - permission
- true
- SelectPermission_
- The permission definition
* - comment
- false
- text
- Comment
.. _SelectPermission:
SelectPermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - columns
- true
- :ref:`PGColumn` array (or) ``'*'``
- Only these columns are selectable (or all when ``'*'`` is specified)
* - computed_fields
- false
- :ref:`ComputedFieldName` array
- Only these computed fields are selectable
* - filter
- true
- :ref:`BoolExp`
- Only the rows where this expression holds true are selectable
* - limit
- false
- ``Integer``
- The maximum number of rows that can be returned
* - allow_aggregations
- false
- ``Boolean``
- Toggle allowing aggregate queries
.. _drop_select_permission:
drop_select_permission
----------------------
Drop an existing select permission for a role on a table.
.. _drop_select_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
.. _create_update_permission:
create_update_permission
------------------------
An update permission is used to restrict the columns and rows that can be
updated. Its structure is quite similar to the select permission.
An example:
.. code-block:: http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_update_permission",
"args" : {
"table" : "article",
"role" : "user",
"permission" : {
"columns" : ["title", "content", "category"],
"filter" : {
"author_id" : "X-HASURA-USER-ID"
},
"check" : {
"content" : {
"_ne": ""
}
},
"set":{
"updated_at" : "NOW()"
}
}
}
}
This reads as follows - for the ``user`` role:
* Allow updating only those rows where the ``filter`` passes i.e. the value of the ``author_id`` column of a row matches the value of the session variable ``X-HASURA-USER-ID``.
* If the above ``filter`` passes for a given row, allow updating only the ``title``, ``content`` and ``category`` columns (*as specified in the* ``columns`` *key*).
* After the update happens, verify that the ``check`` condition holds for the updated row i.e. that the value in the ``content`` column is not empty.
* When this update happens, the value of the column ``updated_at`` will be automatically ``set`` to the current timestamp.
.. note::
It is important to deny updates to columns that will determine the row
ownership. In the above example, the ``author_id`` column determines the
ownership of a row in the ``article`` table. Columns such as this should
never be allowed to be updated.
.. _create_update_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - permission
- true
- UpdatePermission_
- The permission definition
* - comment
- false
- text
- Comment
.. _UpdatePermission:
UpdatePermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - columns
- true
- :ref:`PGColumn` array (or) ``'*'``
- Only these columns are selectable (or all when ``'*'`` is specified)
* - filter
- true
- :ref:`BoolExp`
- Only the rows where this precondition holds true are updatable
* - check
- false
- :ref:`BoolExp`
- Postcondition which must be satisfied by rows which have been updated
* - set
- false
- :ref:`ColumnPresetExp`
- Preset values for columns that can be sourced from session variables or static values.
.. _drop_update_permission:
drop_update_permission
----------------------
Drop an existing update permission for a role on a table.
.. _drop_update_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
.. _create_delete_permission:
create_delete_permission
------------------------
A delete permission is used to restrict the rows that can be deleted.
An example:
.. code-block:: http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type" : "create_delete_permission",
"args" : {
"table" : "article",
"role" : "user",
"permission" : {
"filter" : {
"author_id" : "X-HASURA-USER-ID"
}
}
}
}
This reads as follows:
"``delete`` for the ``user`` role on the ``article`` table is allowed on rows where
``author_id`` is the same as the request header ``X-HASURA-USER-ID`` value."
.. _create_delete_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
* - permission
- true
- DeletePermission_
- The permission definition
* - comment
- false
- text
- Comment
.. _DeletePermission:
DeletePermission
&&&&&&&&&&&&&&&&
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - filter
- true
- :ref:`BoolExp`
- Only the rows where this expression holds true are deletable
.. _drop_delete_permission:
drop_delete_permission
----------------------
Drop an existing delete permission for a role on a table.
.. _drop_delete_permission_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- Role
.. _set_permission_comment:
set_permission_comment
----------------------
``set_permission_comment`` is used to set/update the comment on a permission.
Setting the comment to ``null`` removes it.
An example:
.. code-block:: http
POST /v1/query HTTP/1.1
Content-Type: application/json
Authorization: Bearer <auth-token> # optional if cookie is set
X-Hasura-Role: admin
{
"type": "set_permission_comment",
"args": {
"table": "article",
"role": "user",
"type" : "update",
"comment" : "can only modify his/her own rows"
}
}
.. _set_permission_comment_syntax:
Args syntax
^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Key
- Required
- Schema
- Description
* - table
- true
- :ref:`TableName`
- Name of the table
* - role
- true
- :ref:`RoleName`
- The role in the permission
* - type
- true
- permission type (one of select/update/delete/insert)
- The type of the permission
* - comment
- false
- Text
- Comment
Reference in New Issue View Git Blame Copy Permalink