{"id":15432902,"url":"https://github.com/simonw/datasette-permissions-sql","last_synced_at":"2025-04-19T17:46:37.748Z","repository":{"id":57417934,"uuid":"271408895","full_name":"simonw/datasette-permissions-sql","owner":"simonw","description":"Datasette plugin for configuring permission checks using SQL queries","archived":false,"fork":false,"pushed_at":"2020-06-12T07:06:15.000Z","size":25,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-18T07:53:12.361Z","etag":null,"topics":["datasette","datasette-io","datasette-plugin"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simonw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-10T23:48:13.000Z","updated_at":"2023-08-14T15:55:15.000Z","dependencies_parsed_at":"2022-09-03T09:41:29.208Z","dependency_job_id":null,"html_url":"https://github.com/simonw/datasette-permissions-sql","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Fdatasette-permissions-sql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Fdatasette-permissions-sql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Fdatasette-permissions-sql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Fdatasette-permissions-sql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonw","download_url":"https://codeload.github.com/simonw/datasette-permissions-sql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249752143,"owners_count":21320449,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["datasette","datasette-io","datasette-plugin"],"created_at":"2024-10-01T18:29:06.202Z","updated_at":"2025-04-19T17:46:37.731Z","avatar_url":"https://github.com/simonw.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# datasette-permissions-sql\n\n[![PyPI](https://img.shields.io/pypi/v/datasette-permissions-sql.svg)](https://pypi.org/project/datasette-permissions-sql/)\n[![CircleCI](https://circleci.com/gh/simonw/datasette-permissions-sql.svg?style=svg)](https://circleci.com/gh/simonw/datasette-permissions-sql)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/simonw/datasette-permissions-sql/blob/master/LICENSE)\n\nDatasette plugin for configuring permission checks using SQL queries\n\n## Installation\n\nInstall this plugin in the same environment as Datasette.\n\n    $ pip install datasette-permissions-sql\n\n## Usage\n\nFirst, read up on how Datasette's [authentication and permissions system](https://datasette.readthedocs.io/en/latest/authentication.html) works.\n\nThis plugin lets you define rules containing SQL queries that are executed to see if the currently authenticated actor has permission to perform certain actions.\n\nConsider a canned query which authenticated users should only be able to execute if a row in the `users` table says that they are a member of staff.\n\nThat `users` table in the `mydatabase.db` database could look like this:\n\n| id | username | is_staff |\n|--|--------|--------|\n| 1 | cleopaws | 0 |\n| 2 | simon | 1 |\n\nAuthenticated users have an `actor` that looks like this:\n\n```json\n{\n    \"id\": 2,\n    \"username\": \"simon\"\n}\n```\n\nTo configure the canned query to only be executable by staff users, add the following to your `metadata.json`:\n\n```json\n{\n    \"plugins\": {\n        \"datasette-permissions-sql\": [\n            {\n                \"action\": \"view-query\",\n                \"resource\": [\"mydatabase\", \"promote_to_staff\"],\n                \"sql\": \"SELECT * FROM users WHERE is_staff = 1 AND id = :actor_id\"\n            }\n        ]\n    },\n    \"databases\": {\n        \"mydatabase\": {\n            \"queries\": {\n                \"promote_to_staff\": {\n                    \"sql\": \"UPDATE users SET is is_staff=1 WHERE id=:id\",\n                    \"write\": true\n                }\n            }\n        }\n    }\n}\n```\n\nThe `\"datasette-permissions-sql\"` key is a list of rules. Each of those rules has the following shape:\n\n```json\n{\n    \"action\": \"name-of-action\",\n    \"resource\": [\"resource identifier to run this on\"],\n    \"sql\": \"SQL query to execute\",\n    \"database\": \"mydatabase\"\n}\n```\n\nBoth `\"action\"` and `\"resource\"` are optional. If present, the SQL query will only be executed on permission checks that match the action and, if present, the resource indicators.\n\n`\"database\"` is also optional: it specifies the named database that the query should be executed against. If it is not present the first connected database will be used.\n\nThe Datasette documentation includes a [list of built-in permissions](https://datasette.readthedocs.io/en/stable/authentication.html#built-in-permissions) that you might want to use here.\n\n### The SQL query\n\nIf the SQL query returns any rows the action will be allowed. If it returns no rows, the plugin hook will return `False` and deny access to that action.\n\nThe SQL query is called with a number of named parameters. You can use any of these as part of the query.\n\nThe list of parameters is as follows:\n\n* `action` - the action, e.g. `\"view-database\"`\n* `resource_1` - the first component of the resource, if one was passed\n* `resource_2` - the second component of the resource, if available\n* `actor_*` - a parameter for every key on the actor. Usually `actor_id` is present.\n\nIf any rows are returned, the permission check passes. If no rows are returned the check fails.\n\nAnother example table, this time granting explicit access to individual tables. Consider a table called `table_access` that looks like this:\n\n| user_id | database | table |\n| - | - | - |\n| 1 | mydb | dogs |\n| 2 | mydb | dogs |\n| 1 | mydb | cats |\n\nThe following SQL query would grant access to the `dogs` ttable in the `mydb.db` database to users 1 and 2 - but would forbid access for user 2 to the `cats` table:\n\n```sql\nSELECT\n    *\nFROM\n    table_access\nWHERE\n    user_id = :actor_id\n    AND \"database\" = :resource_1\n    AND \"table\" = :resource_2\n```\nIn a `metadata.yaml` configuration file that would look like this:\n\n```yaml\ndatabases:\n  mydb:\n    allow_sql: {}\nplugins:\n  datasette-permissions-sql:\n  - action: view-table\n    sql: |-\n      SELECT\n        *\n      FROM\n        table_access\n      WHERE\n        user_id = :actor_id\n        AND \"database\" = :resource_1\n        AND \"table\" = :resource_2\n```\nWe're using `allow_sql: {}` here to disable arbitrary SQL queries. This prevents users from running `select * from cats` directly to work around the permissions limits.\n\n### Fallback mode\n\nThe default behaviour of this plugin is to take full control of specified permissions. The SQL query will directly control if the user is allowed or denied access to the permission.\n\nThis means that the default policy for each permission (which in Datasette core is \"allow\" for `view-database` and friends) will be ignored. It also means that any other `permission_allowed` plugins will not get their turn once this plugin has executed.\n\nYou can change this on a per-rule basis using ``\"fallback\": true``:\n\n```json\n{\n    \"action\": \"view-table\",\n    \"resource\": [\"mydatabase\", \"mytable\"],\n    \"sql\": \"select * from admins where user_id = :actor_id\",\n    \"fallback\": true\n}\n```\n\nWhen running in fallback mode, a query result returning no rows will cause the plugin hook to return ``None`` - which means \"I have no opinion on this permission, fall back to other plugins or the default\".\n\nIn this mode you can still return `False` (for \"deny access\") by returning a single row with a single value of `-1`. For example:\n\n```json\n{\n    \"action\": \"view-table\",\n    \"resource\": [\"mydatabase\", \"mytable\"],\n    \"sql\": \"select -1 from banned where user_id = :actor_id\",\n    \"fallback\": true\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonw%2Fdatasette-permissions-sql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonw%2Fdatasette-permissions-sql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonw%2Fdatasette-permissions-sql/lists"}