| Name | datasette-acl JSON |
| Version |
0.4a4
JSON |
| download |
| home_page | None |
| Summary | Advanced permission management for Datasette |
| upload_time | 2024-09-10 16:18:23 |
| maintainer | None |
| docs_url | None |
| author | Simon Willison |
| requires_python | >=3.8 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# datasette-acl
[](https://pypi.org/project/datasette-acl/)
[](https://github.com/datasette/datasette-acl/releases)
[](https://github.com/datasette/datasette-acl/actions/workflows/test.yml)
[](https://github.com/datasette/datasette-acl/blob/main/LICENSE)
Advanced permission management for Datasette. **Highly experimental**.
## Installation
Install this plugin in the same environment as Datasette. This plugin requires Datasette 1.0a15 or higher.
```bash
datasette install datasette-acl
```
## Usage
This plugin is under active development. It currently only supports configuring [permissions](https://docs.datasette.io/en/latest/authentication.html#permissions) for individual tables, controlling the following:
- `insert-row`
- `delete-row`
- `update-row`
- `alter-table`
- `drop-table`
Permissions are saved in the internal database. This means you should run Datasette with the `--internal path/to/internal.db` option, otherwise your permissions will be reset every time you restart Datasette.
### Managing permissions for a table
The interface for configuring table permissions lives at `/database-name/table-name/-/acl`. It can be accessed from the table actions menu on the table page.
Permission can be granted for each of the above table actions. They can be assigned to both groups and individual users, who can be added using their `actor["id"]`.
An audit log tracks which permissions were added and removed, displayed at the bottom of the table permissions page.
### Controlling who can edit permissions
Users with the new `datasette-acl` permission will have the ability to access a UI for setting permissions for users and groups on a table.
To configure the root user to have this permission, add the following to your Datasette configuration:
```yaml
permissions:
datasette-acl:
id: root
```
Alternatively you can start Datasette running like this:
```bash
datasette mydata.db --root --internal internal.db \
-s permissions.datasette-acl.id root
```
### User groups
Users can be assigned to groups, and those groups can then be used to quickly assign permissions to all of those users at once.
To manage your groups, visit `/-/acl/groups` or use the "Manage user groups" item in the Datasette application menu.
Add users to a group by typing in their actor ID. Remove them using the remove user button.
The page for each group includes an audit log showing changes made to that group's list of members.
When you delete a group its members will all be removed and it will be marked as deleted. Creating a group with the same name will reuse that group's record and display its existing audit log, but will not re-add the members that were removed.
### Dynamic groups
You may wish to define permission rules against groups of actors based on their actor attributes, without needing to manually add those actors to a group. This can be achieved by defining a dynamic group in the `datasette-acl` configuration.
Dynamic groups are defined in terms of [allow blocks](https://docs.datasette.io/en/stable/authentication.html#defining-permissions-with-allow-blocks). The following configuration defines two dynamic groups - one called `admin` that contains all users with `"is_admin": true` in their attributes, and another called `sales` that explicitly includes users with `"sales"` as one of the values in their `departments` array.
```yaml
plugins:
datasette-acl:
dynamic-groups:
admin:
is_admin: true
sales:
departments: ["sales"]
```
Any time an actor has their permissions checked they will be dynamically added to or removed from these groups based on the current value of their actor attributes.
Dynamic groups are displayed in the list of groups, but their members cannot be manually added or removed.
### Table creator permissions
If you allow regular users to create tables in Datasette, you may want them to maintain a level of "ownership" over those tables, such that other users are unable to modify those tables without the creator's permission.
The `table-creator-permissions` plugin setting can be used to automatically configure permissions for the actor who created a table.
Enable that like this:
```yaml
plugins:
datasette-acl:
table-creator-permissions:
- alter-table
- drop-table
- insert-row
- update-row
- delete-row
```
### Configuring autocomplete against actor IDs
By default, users of this plugin can assign permissions to any actor ID by entering that ID, whether or not that ID corresponds to a user that exists elsewhere in the current Datasette configuration.
If you are running this plugin in an environment with a fixed, known list of actor IDs you can implement a plugin using the `datasette_acl_valid_actors(datasette)` plugin hook which returns an iterable sequence of string actor IDs or `{"id": "actor-id", "display": "Actor Name"}` dictionaries
These will then be used for both validation and autocomplete, ensuring users do not attach actor IDs that are not in that list.
Example plugin implementation:
```python
from datasette import hookimpl
@hookimpl
def datasette_acl_valid_actors(datasette):
return ["paulo", "rohan", "simon"]
```
This function can also return an async inner function, for making async calls. This example uses the `[{"id": "actor-id", "display": "Actor Name"}]` format:
```python
from datasette import hookimpl
@hookimpl
def datasette_acl_valid_actors(datasette):
async def inner():
db = datasette.get_internal_database()
return (await db.execute("select id, username as display from users")).dicts()
return inner
```
## Development
To set up this plugin locally, first checkout the code. Then create a new virtual environment:
```bash
cd datasette-acl
python -m venv venv
source venv/bin/activate
```
Now install the dependencies and test dependencies:
```bash
pip install -e '.[test]'
```
To run the tests:
```bash
python -m pytest
```
### Tips for local development
Here's how to run the plugin with all of its features enabled.
First, grab a test database:
```bash
wget https://latest.datasette.io/fixtures.db
```
Install the [datasette-unsafe-actor-debug](https://github.com/datasette/datasette-unsafe-actor-debug) plugin, so you can use the `http://127.0.0.1:8001/-/unsafe-actor` page to quickly imitate any actor for testing purposes:
```bash
datasette install datasette-unsafe-actor-debug
```
And [datasette-visible-internal-db](https://github.com/datasette/datasette-visible-internal-db) to make it easy to see what's going on in the internal database:
```bash
datasette install datasette-visible-internal-db
```
Then start Datasette like this:
```bash
datasette fixtures.db --internal internal.db \
-s permissions.datasette-acl.id root \
-s plugins.datasette-unsafe-actor-debug.enabled 1 \
-s plugins.datasette-acl.table-creator-permissions '["insert-row", "update-row"]' \
-s plugins.datasette-acl.dynamic-groups.staff.is_staff true \
--root \
--secret 1 \
--reload
```
This configures Datasette to provide a URL for you to sign in as root, which will give you access to the permission editing tool.
It ensures that any user who creates a table (which you can test using the `/-/api` API explorer tool) will be granted initial `insert-row` and `update-row` permissions.
It sets up a dynamic group such that any actor with `{"is_staff": true}` in their JSON will be treated as a member of that group.
`--reload` means Datasette will reload on any code changes to the plugin, and `--secret 1` ensures your Datasette authentication cookies will continue to work across server restarts.
Raw data
{
"_id": null,
"home_page": null,
"name": "datasette-acl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Simon Willison",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/bb/53/02d5eabacb892dff792649fea53616356566842cb989ec877ee849160dca/datasette_acl-0.4a4.tar.gz",
"platform": null,
"description": "# datasette-acl\n\n[](https://pypi.org/project/datasette-acl/)\n[](https://github.com/datasette/datasette-acl/releases)\n[](https://github.com/datasette/datasette-acl/actions/workflows/test.yml)\n[](https://github.com/datasette/datasette-acl/blob/main/LICENSE)\n\nAdvanced permission management for Datasette. **Highly experimental**.\n\n## Installation\n\nInstall this plugin in the same environment as Datasette. This plugin requires Datasette 1.0a15 or higher.\n```bash\ndatasette install datasette-acl\n```\n## Usage\n\nThis plugin is under active development. It currently only supports configuring [permissions](https://docs.datasette.io/en/latest/authentication.html#permissions) for individual tables, controlling the following:\n\n- `insert-row`\n- `delete-row`\n- `update-row`\n- `alter-table`\n- `drop-table`\n\nPermissions are saved in the internal database. This means you should run Datasette with the `--internal path/to/internal.db` option, otherwise your permissions will be reset every time you restart Datasette.\n\n### Managing permissions for a table\n\nThe interface for configuring table permissions lives at `/database-name/table-name/-/acl`. It can be accessed from the table actions menu on the table page.\n\nPermission can be granted for each of the above table actions. They can be assigned to both groups and individual users, who can be added using their `actor[\"id\"]`.\n\nAn audit log tracks which permissions were added and removed, displayed at the bottom of the table permissions page.\n\n### Controlling who can edit permissions\n\nUsers with the new `datasette-acl` permission will have the ability to access a UI for setting permissions for users and groups on a table.\n\nTo configure the root user to have this permission, add the following to your Datasette configuration:\n\n```yaml\npermissions:\n datasette-acl:\n id: root\n```\nAlternatively you can start Datasette running like this:\n```bash\ndatasette mydata.db --root --internal internal.db \\\n -s permissions.datasette-acl.id root\n```\n\n### User groups\n\nUsers can be assigned to groups, and those groups can then be used to quickly assign permissions to all of those users at once.\n\nTo manage your groups, visit `/-/acl/groups` or use the \"Manage user groups\" item in the Datasette application menu.\n\nAdd users to a group by typing in their actor ID. Remove them using the remove user button.\n\nThe page for each group includes an audit log showing changes made to that group's list of members.\n\nWhen you delete a group its members will all be removed and it will be marked as deleted. Creating a group with the same name will reuse that group's record and display its existing audit log, but will not re-add the members that were removed.\n\n### Dynamic groups\n\nYou may wish to define permission rules against groups of actors based on their actor attributes, without needing to manually add those actors to a group. This can be achieved by defining a dynamic group in the `datasette-acl` configuration.\n\nDynamic groups are defined in terms of [allow blocks](https://docs.datasette.io/en/stable/authentication.html#defining-permissions-with-allow-blocks). The following configuration defines two dynamic groups - one called `admin` that contains all users with `\"is_admin\": true` in their attributes, and another called `sales` that explicitly includes users with `\"sales\"` as one of the values in their `departments` array.\n\n```yaml\nplugins:\n datasette-acl:\n dynamic-groups:\n admin:\n is_admin: true\n sales:\n departments: [\"sales\"]\n```\n\nAny time an actor has their permissions checked they will be dynamically added to or removed from these groups based on the current value of their actor attributes.\n\nDynamic groups are displayed in the list of groups, but their members cannot be manually added or removed.\n\n### Table creator permissions\n\nIf you allow regular users to create tables in Datasette, you may want them to maintain a level of \"ownership\" over those tables, such that other users are unable to modify those tables without the creator's permission.\n\nThe `table-creator-permissions` plugin setting can be used to automatically configure permissions for the actor who created a table.\n\nEnable that like this:\n```yaml\nplugins:\n datasette-acl:\n table-creator-permissions:\n - alter-table\n - drop-table\n - insert-row\n - update-row\n - delete-row\n```\n### Configuring autocomplete against actor IDs\n\nBy default, users of this plugin can assign permissions to any actor ID by entering that ID, whether or not that ID corresponds to a user that exists elsewhere in the current Datasette configuration.\n\nIf you are running this plugin in an environment with a fixed, known list of actor IDs you can implement a plugin using the `datasette_acl_valid_actors(datasette)` plugin hook which returns an iterable sequence of string actor IDs or `{\"id\": \"actor-id\", \"display\": \"Actor Name\"}` dictionaries\n\nThese will then be used for both validation and autocomplete, ensuring users do not attach actor IDs that are not in that list.\n\nExample plugin implementation:\n```python\nfrom datasette import hookimpl\n\n@hookimpl\ndef datasette_acl_valid_actors(datasette):\n return [\"paulo\", \"rohan\", \"simon\"]\n```\nThis function can also return an async inner function, for making async calls. This example uses the `[{\"id\": \"actor-id\", \"display\": \"Actor Name\"}]` format:\n```python\nfrom datasette import hookimpl\n\n@hookimpl\ndef datasette_acl_valid_actors(datasette):\n async def inner():\n db = datasette.get_internal_database()\n return (await db.execute(\"select id, username as display from users\")).dicts()\n return inner\n```\n\n## Development\n\nTo set up this plugin locally, first checkout the code. Then create a new virtual environment:\n```bash\ncd datasette-acl\npython -m venv venv\nsource venv/bin/activate\n```\nNow install the dependencies and test dependencies:\n```bash\npip install -e '.[test]'\n```\nTo run the tests:\n```bash\npython -m pytest\n```\n\n### Tips for local development\n\nHere's how to run the plugin with all of its features enabled.\n\nFirst, grab a test database:\n```bash\nwget https://latest.datasette.io/fixtures.db\n```\nInstall the [datasette-unsafe-actor-debug](https://github.com/datasette/datasette-unsafe-actor-debug) plugin, so you can use the `http://127.0.0.1:8001/-/unsafe-actor` page to quickly imitate any actor for testing purposes:\n```bash\ndatasette install datasette-unsafe-actor-debug\n```\nAnd [datasette-visible-internal-db](https://github.com/datasette/datasette-visible-internal-db) to make it easy to see what's going on in the internal database:\n```bash\ndatasette install datasette-visible-internal-db\n```\nThen start Datasette like this:\n```bash\ndatasette fixtures.db --internal internal.db \\\n -s permissions.datasette-acl.id root \\\n -s plugins.datasette-unsafe-actor-debug.enabled 1 \\\n -s plugins.datasette-acl.table-creator-permissions '[\"insert-row\", \"update-row\"]' \\\n -s plugins.datasette-acl.dynamic-groups.staff.is_staff true \\\n --root \\\n --secret 1 \\\n --reload\n```\nThis configures Datasette to provide a URL for you to sign in as root, which will give you access to the permission editing tool.\n\nIt ensures that any user who creates a table (which you can test using the `/-/api` API explorer tool) will be granted initial `insert-row` and `update-row` permissions.\n\nIt sets up a dynamic group such that any actor with `{\"is_staff\": true}` in their JSON will be treated as a member of that group.\n\n`--reload` means Datasette will reload on any code changes to the plugin, and `--secret 1` ensures your Datasette authentication cookies will continue to work across server restarts.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Advanced permission management for Datasette",
"version": "0.4a4",
"project_urls": {
"CI": "https://github.com/datasette/datasette-acl/actions",
"Changelog": "https://github.com/datasette/datasette-acl/releases",
"Homepage": "https://github.com/datasette/datasette-acl",
"Issues": "https://github.com/datasette/datasette-acl/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "32380845eb0471f58da4d23389ef9661d079b33215e3c4e4b06f128266365a94",
"md5": "de987e796c416e4f79f83c015b93ee12",
"sha256": "578ef0d349c7af30ab70baed260ed7c9bc6771826eccfb57b57899020f79c903"
},
"downloads": -1,
"filename": "datasette_acl-0.4a4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de987e796c416e4f79f83c015b93ee12",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 43795,
"upload_time": "2024-09-10T16:18:22",
"upload_time_iso_8601": "2024-09-10T16:18:22.070089Z",
"url": "https://files.pythonhosted.org/packages/32/38/0845eb0471f58da4d23389ef9661d079b33215e3c4e4b06f128266365a94/datasette_acl-0.4a4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bb5302d5eabacb892dff792649fea53616356566842cb989ec877ee849160dca",
"md5": "b4fbc90d22d87cd5f2b277f1ec1063b4",
"sha256": "4df4ed797aca031c34ff48c740ef589055e316beba0c97ee957e9579f59e9265"
},
"downloads": -1,
"filename": "datasette_acl-0.4a4.tar.gz",
"has_sig": false,
"md5_digest": "b4fbc90d22d87cd5f2b277f1ec1063b4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 46917,
"upload_time": "2024-09-10T16:18:23",
"upload_time_iso_8601": "2024-09-10T16:18:23.918172Z",
"url": "https://files.pythonhosted.org/packages/bb/53/02d5eabacb892dff792649fea53616356566842cb989ec877ee849160dca/datasette_acl-0.4a4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-10 16:18:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "datasette",
"github_project": "datasette-acl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "datasette-acl"
}
