{"id": "authentication:authentication-permissions-other", "page": "authentication", "ref": "authentication-permissions-other", "title": "Other permissions in ", "content": "For all other permissions, you can use one or more  \"permissions\"  blocks in your  datasette.yaml  configuration file. \n             To grant access to the  permissions debug tool  to all signed in users, you can grant  permissions-debug  to any actor with an  id  matching the wildcard  *  by adding this a the root of your configuration: \n             [[[cog\nconfig_example(cog, \"\"\"\n    permissions:\n      debug-menu:\n        id: '*'\n\"\"\") \n             ]]] \n             [[[end]]] \n             To grant  create-table  to the user with  id  of  editor  for the  docs  database: \n             [[[cog\nconfig_example(cog, \"\"\"\n    databases:\n      docs:\n        permissions:\n          create-table:\n            id: editor\n\"\"\") \n             ]]] \n             [[[end]]] \n             And for  insert-row  against the  reports  table in that  docs  database: \n             [[[cog\nconfig_example(cog, \"\"\"\n    databases:\n      docs:\n        tables:\n          reports:\n            permissions:\n              insert-row:\n                id: editor\n\"\"\") \n             ]]] \n             [[[end]]] \n             The  permissions debug tool  can be useful for helping test permissions that you have configured in this way.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:authentication-permissions-instance", "page": "authentication", "ref": "authentication-permissions-instance", "title": "Access to an instance", "content": "Here's how to restrict access to your entire Datasette instance to just the  \"id\": \"root\"  user: \n                 [[[cog\nfrom metadata_doc import config_example\nconfig_example(cog, \"\"\"\n    title: My private Datasette instance\n    allow:\n      id: root\n  \"\"\") \n                 ]]] \n                 [[[end]]] \n                 To deny access to all users, you can use  \"allow\": false : \n                 [[[cog\nconfig_example(cog, \"\"\"\n    title: My entirely inaccessible instance\n    allow: false\n\"\"\") \n                 ]]] \n                 [[[end]]] \n                 One reason to do this is if you are using a Datasette plugin - such as  datasette-permissions-sql  - to control permissions instead.", "breadcrumbs": "[\"Authentication and permissions\", \"Access permissions in \"]", "references": "[{\"href\": \"https://github.com/simonw/datasette-permissions-sql\", \"label\": \"datasette-permissions-sql\"}]"}
{"id": "authentication:authentication-actor-matches-allow", "page": "authentication", "ref": "authentication-actor-matches-allow", "title": "actor_matches_allow()", "content": "Plugins that wish to implement this same  \"allow\"  block permissions scheme can take advantage of the  datasette.utils.actor_matches_allow(actor, allow)  function: \n             from datasette.utils import actor_matches_allow\n\nactor_matches_allow({\"id\": \"root\"}, {\"id\": \"*\"})\n# returns True \n             The currently authenticated actor is made available to plugins as  request.actor .", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:allowdebugview", "page": "authentication", "ref": "allowdebugview", "title": "The /-/allow-debug tool", "content": "The  /-/allow-debug  tool lets you try out different   \"action\"  blocks against different  \"actor\"  JSON objects. You can try that out here:  https://latest.datasette.io/-/allow-debug", "breadcrumbs": "[\"Authentication and permissions\", \"Permissions\"]", "references": "[{\"href\": \"https://latest.datasette.io/-/allow-debug\", \"label\": \"https://latest.datasette.io/-/allow-debug\"}]"}
{"id": "authentication:authentication-permissions-explained", "page": "authentication", "ref": "authentication-permissions-explained", "title": "How permissions are resolved", "content": "The  datasette.permission_allowed(actor, action, resource=None, default=...)  method is called to check if an actor is allowed to perform a specific action. \n                 This method asks every plugin that implements the  permission_allowed(datasette, actor, action, resource)  hook if the actor is allowed to perform the action. \n                 Each plugin can return  True  to indicate that the actor is allowed to perform the action,  False  if they are not allowed and  None  if the plugin has no opinion on the matter. \n                 False  acts as a veto - if any plugin returns  False  then the permission check is denied. Otherwise, if any plugin returns  True  then the permission check is allowed. \n                 The  resource  argument can be used to specify a specific resource that the action is being performed against. Some permissions, such as  view-instance , do not involve a resource. Others such as  view-database  have a resource that is a string naming the database. Permissions that take both a database name and the name of a table, view or canned query within that database use a resource that is a tuple of two strings,  (database_name, resource_name) . \n                 Plugins that implement the  permission_allowed()  hook can decide if they are going to consider the provided resource or not.", "breadcrumbs": "[\"Authentication and permissions\", \"Permissions\"]", "references": "[]"}
{"id": "authentication:permissionsdebugview", "page": "authentication", "ref": "permissionsdebugview", "title": "The permissions debug tool", "content": "The debug tool at  /-/permissions  is only available to the  authenticated root user  (or any actor granted the  permissions-debug  action). \n             It shows the thirty most recent permission checks that have been carried out by the Datasette instance. \n             It also provides an interface for running hypothetical permission checks against a hypothetical actor. This is a useful way of confirming that your configured permissions work in the way you expect. \n             This is designed to help administrators and plugin authors understand exactly how permission checks are being carried out, in order to effectively configure Datasette's permission system.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:logoutview", "page": "authentication", "ref": "logoutview", "title": "The /-/logout page", "content": "The page at  /-/logout  provides the ability to log out of a  ds_actor  cookie authentication session.", "breadcrumbs": "[\"Authentication and permissions\", \"The ds_actor cookie\"]", "references": "[]"}
{"id": "authentication:authentication-permissions-allow", "page": "authentication", "ref": "authentication-permissions-allow", "title": "Defining permissions with \"allow\" blocks", "content": "The standard way to define permissions in Datasette is to use an  \"allow\"  block  in the datasette.yaml file . This is a JSON document describing which actors are allowed to perform a permission. \n                 The most basic form of allow block is this ( allow demo ,  deny demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      id: root\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 This will match any actors with an  \"id\"  property of  \"root\"  - for example, an actor that looks like this: \n                 {\n    \"id\": \"root\",\n    \"name\": \"Root User\"\n} \n                 An allow block can specify \"deny all\" using  false  ( demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow: false\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 An  \"allow\"  of  true  allows all access ( demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow: true\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 Allow keys can provide a list of values. These will match any actor that has any of those values ( allow demo ,  deny demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      id:\n      - simon\n      - cleopaws\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 This will match any actor with an  \"id\"  of either  \"simon\"  or  \"cleopaws\" . \n                 Actors can have properties that feature a list of values. These will be matched against the list of values in an allow block. Consider the following actor: \n                 {\n    \"id\": \"simon\",\n    \"roles\": [\"staff\", \"developer\"]\n} \n                 This allow block will provide access to any actor that has  \"developer\"  as one of their roles ( allow demo ,  deny demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      roles:\n      - developer\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 Note that \"roles\" is not a concept that is baked into Datasette - it's a convention that plugins can choose to implement and act on. \n                 If you want to provide access to any actor with a value for a specific key, use  \"*\" . For example, to match any logged-in user specify the following ( allow demo ,  deny demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      id: \"*\"\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 You can specify that only unauthenticated actors (from anonymous HTTP requests) should be allowed access using the special  \"unauthenticated\": true  key in an allow block ( allow demo ,  deny demo ): \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      unauthenticated: true\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 Allow keys act as an \"or\" mechanism. An actor will be able to execute the query if any of their JSON properties match any of the values in the corresponding lists in the  allow  block. The following block will allow users with either a  role  of  \"ops\"  OR users who have an  id  of  \"simon\"  or  \"cleopaws\" : \n                 [[[cog\nfrom metadata_doc import config_example\nimport textwrap\nconfig_example(cog, textwrap.dedent(\n  \"\"\"\n    allow:\n      id:\n      - simon\n      - cleopaws\n      role: ops\n    \"\"\").strip(),\n    \"YAML\", \"JSON\"\n  ) \n                 ]]] \n                 [[[end]]] \n                 Demo for cleopaws ,  demo for ops role ,  demo for an actor matching neither rule .", "breadcrumbs": "[\"Authentication and permissions\", \"Permissions\"]", "references": "[{\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%22id%22%3A+%22root%22%7D&allow=%7B%0D%0A++++++++%22id%22%3A+%22root%22%0D%0A++++%7D\", \"label\": \"allow demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%22id%22%3A+%22trevor%22%7D&allow=%7B%0D%0A++++++++%22id%22%3A+%22root%22%0D%0A++++%7D\", \"label\": \"deny demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22root%22%0D%0A%7D&allow=false\", \"label\": \"demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22root%22%0D%0A%7D&allow=true\", \"label\": \"demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22cleopaws%22%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%5B%0D%0A++++++++%22simon%22%2C%0D%0A++++++++%22cleopaws%22%0D%0A++++%5D%0D%0A%7D\", \"label\": \"allow demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22pancakes%22%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%5B%0D%0A++++++++%22simon%22%2C%0D%0A++++++++%22cleopaws%22%0D%0A++++%5D%0D%0A%7D\", \"label\": \"deny demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22simon%22%2C%0D%0A++++%22roles%22%3A+%5B%0D%0A++++++++%22staff%22%2C%0D%0A++++++++%22developer%22%0D%0A++++%5D%0D%0A%7D&allow=%7B%0D%0A++++%22roles%22%3A+%5B%0D%0A++++++++%22developer%22%0D%0A++++%5D%0D%0A%7D\", \"label\": \"allow demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22cleopaws%22%2C%0D%0A++++%22roles%22%3A+%5B%22dog%22%5D%0D%0A%7D&allow=%7B%0D%0A++++%22roles%22%3A+%5B%0D%0A++++++++%22developer%22%0D%0A++++%5D%0D%0A%7D\", \"label\": \"deny demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22simon%22%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%22*%22%0D%0A%7D\", \"label\": \"allow demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22bot%22%3A+%22readme-bot%22%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%22*%22%0D%0A%7D\", \"label\": \"deny demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=null&allow=%7B%0D%0A++++%22unauthenticated%22%3A+true%0D%0A%7D\", \"label\": \"allow demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22hello%22%0D%0A%7D&allow=%7B%0D%0A++++%22unauthenticated%22%3A+true%0D%0A%7D\", \"label\": \"deny demo\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22cleopaws%22%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%5B%0D%0A++++++++%22simon%22%2C%0D%0A++++++++%22cleopaws%22%0D%0A++++%5D%2C%0D%0A++++%22role%22%3A+%22ops%22%0D%0A%7D\", \"label\": \"Demo for cleopaws\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22trevor%22%2C%0D%0A++++%22role%22%3A+%5B%0D%0A++++++++%22ops%22%2C%0D%0A++++++++%22staff%22%0D%0A++++%5D%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%5B%0D%0A++++++++%22simon%22%2C%0D%0A++++++++%22cleopaws%22%0D%0A++++%5D%2C%0D%0A++++%22role%22%3A+%22ops%22%0D%0A%7D\", \"label\": \"demo for ops role\"}, {\"href\": \"https://latest.datasette.io/-/allow-debug?actor=%7B%0D%0A++++%22id%22%3A+%22percy%22%2C%0D%0A++++%22role%22%3A+%5B%0D%0A++++++++%22staff%22%0D%0A++++%5D%0D%0A%7D&allow=%7B%0D%0A++++%22id%22%3A+%5B%0D%0A++++++++%22simon%22%2C%0D%0A++++++++%22cleopaws%22%0D%0A++++%5D%2C%0D%0A++++%22role%22%3A+%22ops%22%0D%0A%7D\", \"label\": \"demo for an actor matching neither rule\"}]"}
{"id": "authentication:authentication-permissions-config", "page": "authentication", "ref": "authentication-permissions-config", "title": "Access permissions in ", "content": "There are two ways to configure permissions using  datasette.yaml  (or  datasette.json ). \n             For simple visibility permissions you can use  \"allow\"  blocks in the root, database, table and query sections. \n             For other permissions you can use a  \"permissions\"  block, described  in the next section . \n             You can limit who is allowed to view different parts of your Datasette instance using  \"allow\"  keys in your  Configuration . \n             You can control the following: \n             \n                 \n                     Access to the entire Datasette instance \n                 \n                 \n                     Access to specific databases \n                 \n                 \n                     Access to specific tables and views \n                 \n                 \n                     Access to specific  Canned queries \n                 \n             \n             If a user cannot access a specific database, they will not be able to access tables, views or queries within that database. If a user cannot access the instance they will not be able to access any of the databases, tables, views or queries.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:id1", "page": "authentication", "ref": "id1", "title": "Built-in permissions", "content": "This section lists all of the permission checks that are carried out by Datasette core, along with the  resource  if it was passed.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:authentication-actor", "page": "authentication", "ref": "authentication-actor", "title": "Actors", "content": "Through plugins, Datasette can support both authenticated users (with cookies) and authenticated API agents (via authentication tokens). The word \"actor\" is used to cover both of these cases. \n             Every request to Datasette has an associated actor value, available in the code as  request.actor . This can be  None  for unauthenticated requests, or a JSON compatible Python dictionary for authenticated users or API agents. \n             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. \n             Plugins can use the  actor_from_request(datasette, request)  hook to implement custom logic for authenticating an actor based on the incoming HTTP request.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:authentication-permissions-database", "page": "authentication", "ref": "authentication-permissions-database", "title": "Access to specific databases", "content": "To limit access to a specific  private.db  database to just authenticated users, use the  \"allow\"  block like this: \n                 [[[cog\nconfig_example(cog, \"\"\"\n    databases:\n      private:\n        allow:\n          id: \"*\"\n\"\"\") \n                 ]]] \n                 [[[end]]]", "breadcrumbs": "[\"Authentication and permissions\", \"Access permissions in \"]", "references": "[]"}
{"id": "authentication:authentication-permissions-table", "page": "authentication", "ref": "authentication-permissions-table", "title": "Access to specific tables and views", "content": "To limit access to the  users  table in your  bakery.db  database: \n                 [[[cog\nconfig_example(cog, \"\"\"\n    databases:\n      bakery:\n        tables:\n          users:\n            allow:\n              id: '*'\n\"\"\") \n                 ]]] \n                 [[[end]]] \n                 This works for SQL views as well - you can list their names in the  \"tables\"  block above in the same way as regular tables. \n                 \n                     Restricting access to tables and views in this way will NOT prevent users from querying them using arbitrary SQL queries,  like this  for example. \n                     If you are restricting access to specific tables you should also use the  \"allow_sql\"  block to prevent users from bypassing the limit with their own SQL queries - see  Controlling the ability to execute arbitrary SQL .", "breadcrumbs": "[\"Authentication and permissions\", \"Access permissions in \"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures?sql=select+*+from+facetable\", \"label\": \"like this\"}]"}
{"id": "authentication:authentication-cli-create-token-restrict", "page": "authentication", "ref": "authentication-cli-create-token-restrict", "title": "Restricting the actions that a token can perform", "content": "Tokens created using  datasette create-token ACTOR_ID  will inherit all of the permissions of the actor that they are associated with. \n                     You can pass additional options to create tokens that are restricted to a subset of that actor's permissions. \n                     To restrict the token to just specific permissions against all available databases, use the  --all  option: \n                     datasette create-token root --all insert-row --all update-row \n                     This option can be passed as many times as you like. In the above example the token will only be allowed to insert and update rows. \n                     You can also restrict permissions such that they can only be used within specific databases: \n                     datasette create-token root --database mydatabase insert-row \n                     The resulting token will only be able to insert rows, and only to tables in the  mydatabase  database. \n                     Finally, you can restrict permissions to individual resources - tables, SQL views and  named queries  - within a specific database: \n                     datasette create-token root --resource mydatabase mytable insert-row \n                     These options have short versions:  -a  for  --all ,  -d  for  --database  and  -r  for  --resource . \n                     You can add  --debug  to see a JSON representation of the token that has been created. Here's a full example: \n                     datasette create-token root \\\n    --secret mysecret \\\n    --all view-instance \\\n    --all view-table \\\n    --database docs view-query \\\n    --resource docs documents insert-row \\\n    --resource docs documents update-row \\\n    --debug \n                     This example outputs the following: \n                     dstok_.eJxFizEKgDAMRe_y5w4qYrFXERGxDkVsMI0uxbubdjFL8l_ez1jhwEQCA6Fjjxp90qtkuHawzdjYrh8MFobLxZ_wBH0_gtnAF-hpS5VfmF8D_lnd97lHqUJgLd6sls4H1qwlhA.nH_7RecYHj5qSzvjhMU95iy0Xlc\n\nDecoded:\n\n{\n  \"a\": \"root\",\n  \"token\": \"dstok\",\n  \"t\": 1670907246,\n  \"_r\": {\n    \"a\": [\n      \"vi\",\n      \"vt\"\n    ],\n    \"d\": {\n      \"docs\": [\n        \"vq\"\n      ]\n    },\n    \"r\": {\n      \"docs\": {\n        \"documents\": [\n          \"ir\",\n          \"ur\"\n        ]\n      }\n    }\n  }\n}", "breadcrumbs": "[\"Authentication and permissions\", \"API Tokens\", \"datasette create-token\"]", "references": "[]"}
{"id": "authentication:permissions-view-instance", "page": "authentication", "ref": "permissions-view-instance", "title": "view-instance", "content": "Top level permission - Actor is allowed to view any pages within this instance, starting at  https://latest.datasette.io/ \n                 Default  allow .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[{\"href\": \"https://latest.datasette.io/\", \"label\": \"https://latest.datasette.io/\"}]"}
{"id": "authentication:authentication-cli-create-token", "page": "authentication", "ref": "authentication-cli-create-token", "title": "datasette create-token", "content": "You can also create tokens on the command line using the  datasette create-token  command. \n                 This command takes one required argument - the ID of the actor to be associated with the created token. \n                 You can specify a  -e/--expires-after  option in seconds. If omitted, the token will never expire. \n                 The command will sign the token using the  DATASETTE_SECRET  environment variable, if available. You can also pass the secret using the  --secret  option. \n                 This means you can run the command locally to create tokens for use with a deployed Datasette instance, provided you know that instance's secret. \n                 To create a token for the  root  actor that will expire in one hour: \n                 datasette create-token root --expires-after 3600 \n                 To create a token that never expires using a specific secret: \n                 datasette create-token root --secret my-secret-goes-here", "breadcrumbs": "[\"Authentication and permissions\", \"API Tokens\"]", "references": "[]"}
{"id": "authentication:authentication-ds-actor-expiry", "page": "authentication", "ref": "authentication-ds-actor-expiry", "title": "Including an expiry time", "content": "ds_actor  cookies can optionally include a signed expiry timestamp, after which the cookies will no longer be valid. Authentication plugins may chose to use this mechanism to limit the lifetime of the cookie. For example, if a plugin implements single-sign-on against another source it may decide to set short-lived cookies so that if the user is removed from the SSO system their existing Datasette cookies will stop working shortly afterwards. \n                 To include an expiry, add a  \"e\"  key to the cookie value containing a base62-encoded integer representing the timestamp when the cookie should expire. For example, here's how to set a cookie that expires after 24 hours: \n                 import time\nfrom datasette.utils import baseconv\n\nexpires_at = int(time.time()) + (24 * 60 * 60)\n\nresponse = Response.redirect(\"/\")\nresponse.set_cookie(\n    \"ds_actor\",\n    datasette.sign(\n        {\n            \"a\": {\"id\": \"cleopaws\"},\n            \"e\": baseconv.base62.encode(expires_at),\n        },\n        \"actor\",\n    ),\n) \n                 The resulting cookie will encode data that looks something like this: \n                 {\n    \"a\": {\n        \"id\": \"cleopaws\"\n    },\n    \"e\": \"1jjSji\"\n}", "breadcrumbs": "[\"Authentication and permissions\", \"The ds_actor cookie\"]", "references": "[]"}