From 793a52b31771280a6c8660efb9e48b9b763477ff Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Thu, 11 Jun 2020 17:43:51 -0700 Subject: [PATCH] Link to datasett-auth-tokens and datasette-permissions-sql in docs, refs #806 --- docs/authentication.rst | 4 ++-- docs/changelog.rst | 4 ++-- docs/ecosystem.rst | 10 ++++++++++ docs/internals.rst | 2 +- docs/plugins.rst | 17 ++++++++++------- 5 files changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/authentication.rst b/docs/authentication.rst index 6a526f34..2a6fa9bc 100644 --- a/docs/authentication.rst +++ b/docs/authentication.rst @@ -19,7 +19,7 @@ Every request to Datasette has an associated actor value, available in the code The actor dictionary can be any shape - the design of that data structure is left up to the plugins. A useful convention is to include an ``"id"`` string, as demonstrated by the "root" actor below. -Plugins can use the :ref:`plugin_actor_from_request` hook to implement custom logic for authenticating an actor based on the incoming HTTP request. +Plugins can use the :ref:`plugin_hook_actor_from_request` hook to implement custom logic for authenticating an actor based on the incoming HTTP request. .. _authentication_root: @@ -314,7 +314,7 @@ Checking permissions in plugins Datasette plugins can check if an actor has permission to perform an action using the :ref:`datasette.permission_allowed(...)` method. -Datasette core performs a number of permission checks, :ref:`documented below `. Plugins can implement the :ref:`plugin_permission_allowed` plugin hook to participate in decisions about whether an actor should be able to perform a specified action. +Datasette core performs a number of permission checks, :ref:`documented below `. Plugins can implement the :ref:`plugin_hook_permission_allowed` plugin hook to participate in decisions about whether an actor should be able to perform a specified action. .. _authentication_actor_matches_allow: diff --git a/docs/changelog.rst b/docs/changelog.rst index aca8f8c2..3a7f9562 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -27,7 +27,7 @@ You'll need to install plugins if you want full user accounts, but default Datas INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit) -Plugins can implement new ways of authenticating users using the new :ref:`plugin_actor_from_request` hook. +Plugins can implement new ways of authenticating users using the new :ref:`plugin_hook_actor_from_request` hook. Permissions ~~~~~~~~~~~ @@ -52,7 +52,7 @@ You can use the new ``"allow"`` block syntax in ``metadata.json`` (or ``metadata See :ref:`authentication_permissions_allow` for more details. -Plugins can implement their own custom permission checks using the new :ref:`plugin_permission_allowed` hook. +Plugins can implement their own custom permission checks using the new :ref:`plugin_hook_permission_allowed` hook. A new debug page at ``/-/permissions`` shows recent permission checks, to help administrators and plugin authors understand exactly what checks are being performed. This tool defaults to only being available to the root user, but can be exposed to other users by plugins that respond to the ``permissions-debug`` permission. (`#788 `__) diff --git a/docs/ecosystem.rst b/docs/ecosystem.rst index 4777cc16..dcb5a887 100644 --- a/docs/ecosystem.rst +++ b/docs/ecosystem.rst @@ -87,6 +87,16 @@ datasette-auth-github `datasette-auth-github `__ adds an authentication layer to Datasette. Users will have to sign in using their GitHub account before they can view data or interact with Datasette. You can also use it to restrict access to specific GitHub users, or to members of specified GitHub `organizations `__ or `teams `__. +datasette-auth-tokens +--------------------- + +`datasette-auth-tokens `__ provides a mechanism for creating secret API tokens that can then be used with Datasette's :ref:`authentication` system. + +datasette-permissions-sql +--------------------- + +`datasette-permissions-sql `__ lets you configure Datasette permissions checks to use custom SQL queries, which means you can make permisison decisions based on data contained within your databases. + datasette-upload-csvs --------------------- diff --git a/docs/internals.rst b/docs/internals.rst index d75544e1..ab9da410 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -219,7 +219,7 @@ await .permission_allowed(actor, action, resource=None, default=False) Check if the given actor has :ref:`permission ` to perform the given action on the given resource. -Some permission checks are carried out against :ref:`rules defined in metadata.json `, while other custom permissions may be decided by plugins that implement the :ref:`plugin_permission_allowed` plugin hook. +Some permission checks are carried out against :ref:`rules defined in metadata.json `, while other custom permissions may be decided by plugins that implement the :ref:`plugin_hook_permission_allowed` plugin hook. If neither ``metadata.json`` nor any of the plugins provide an answer to the permission query the ``default`` argument will be returned. diff --git a/docs/plugins.rst b/docs/plugins.rst index 989cf672..608f93da 100644 --- a/docs/plugins.rst +++ b/docs/plugins.rst @@ -25,9 +25,8 @@ Things you can do with plugins include: * Customize how database values are rendered in the Datasette interface, for example `datasette-render-binary `__ and `datasette-pretty-json `__. -* Wrap the entire Datasette application in custom ASGI middleware to add new pages - or implement authentication, for example - `datasette-auth-github `__. +* Customize how Datasette's authentication and permissions systems work, for example `datasette-auth-tokens `__ and + `datasette-permissions-sql `__. .. _plugins_installing: @@ -996,7 +995,7 @@ This example plugin adds a ``x-databases`` HTTP header listing the currently att Examples: `datasette-auth-github `_, `datasette-search-all `_, `datasette-media `_ -.. _plugin_actor_from_request: +.. _plugin_hook_actor_from_request: actor_from_request(datasette, request) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1055,7 +1054,9 @@ Instead of returning a dictionary, this function can return an awaitable functio return inner -.. _plugin_permission_allowed: +Example: `datasette-auth-tokens `_ + +.. _plugin_hook_permission_allowed: permission_allowed(datasette, actor, action, resource) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1064,7 +1065,7 @@ permission_allowed(datasette, actor, action, resource) You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``, or to execute SQL queries. ``actor`` - dictionary - The current actor, as decided by :ref:`plugin_actor_from_request`. + The current actor, as decided by :ref:`plugin_hook_actor_from_request`. ``action`` - string The action to be performed, e.g. ``"edit-table"``. @@ -1110,4 +1111,6 @@ Here's an example that allows users to view the ``admin_log`` table only if thei return inner -See :ref:`permissions` for a full list of permissions that are included in Datasette core. +See :ref:`built-in permissions ` for a full list of permissions that are included in Datasette core. + +Example: `datasette-permissions-sql `_