This release is a pre-release and may not be stable for production use.
arches-abac-permissions
An Attribute Based Access Control (ABAC) framework for Arches resource and nodegroup permissions.
Arches ABAC Permissions extends Arches' default-deny permission framework with inclusion rules: a rule describes a set of resource instances by their attributes (for example, the value of a node), and a group assigned to the rule is granted permissions on every resource the rule matches.
Installation
Arches ABAC Permissions requires Arches 8.2.
If installing for deployment
The package is not yet published to PyPI. Install it from GitHub:
pip install "arches-abac-permissions @ git+https://github.com/archesproject/arches-abac-permissions.git@main"
To make it a dependency of your project, add the same requirement to the dependencies in your project's pyproject.toml:
dependencies = [
"arches>=8.2.0a23,<8.3.0",
"arches-abac-permissions @ git+https://github.com/archesproject/arches-abac-permissions.git@main",
]
If installing for development
Clone the repo, then install it into your project's virtual environment in editable mode:
git clone https://github.com/archesproject/arches-abac-permissions.git
pip install -e arches-abac-permissions --group dev
Important: Installing arches-abac-permissions installs Arches as a dependency. If you've installed Arches for development using the --editable flag, reinstall Arches with the --editable flag after installing arches-abac-permissions.
Project Configuration
-
Add
arches_abac_permissionstoINSTALLED_APPSin your project'ssettings.py. List it after the core Arches apps (arches.app.models,arches.management, etc.) and after any other Arches applications, but beforearches.app:INSTALLED_APPS = ( "my_project_name", ... "arches.app.models", "arches.management", ... "pgtrigger", # other arches applications, e.g. "arches_search" "arches.extensions.querysets", "arches.extensions.vue_components", "arches.extensions.controlled_lists", "arches_abac_permissions", ) INSTALLED_APPS += ( "arches", "arches.app", "django.contrib.admin", )
Listing it after other Arches applications keeps their templates (for example
index.htm) taking precedence over the scaffold templates shipped with this package. -
Set the permission framework, and define
RULE_LOCATIONS, insettings.py:PERMISSION_FRAMEWORK = "arches_abac_permission_framework.ArchesAbacPermissionFramework" # Required to load inclusion rule classes. The rules directory of every # installed Arches application is searched automatically, so this can be # empty; add dotted paths here to load rules from other packages. RULE_LOCATIONS = []
PERMISSION_FRAMEWORKis often also set insettings_local.py. Check that it isn't overridden there. -
Run migrations:
python manage.py migrate
-
Changing
PERMISSION_FRAMEWORKrequires reindexing:python manage.py es reindex_database
-
Restart your server.
-
Add the rule permissions URLs to your project's
urls.py, before the Arches core URLs:urlpatterns = [ # project-level urls path("", include("arches_abac_permissions.api_urls")), path("", include("arches.urls")), ]
-
Build the front end so the Rule Permissions plugin is bundled. Add the package to your project's
package.jsonthe same way as other Arches applications, then:npm install npm run build_development
Rule Permissions plugin
Migration 0003 registers a Rule Permissions plugin (/plugins/rule-permissions). It lets you manage inclusion rules without the Django admin:
- Rules (left): filter, add, and delete rules.
- Rule Configuration (middle): name and description, plus the fields of the rule type: resource model and lifecycle state for Resource has Lifecycle State; a resource set for Resource is in Resource Set (only offered when
arches_resource_setsis installed); a resource model, node and value for Resource has Node Value; or a resource model, geometry node, spatial relationship and an area drawn on a map (or entered as GeoJSON) with an optional buffer for Resource is in Area. Search and QuerySet rules are not evaluated yet, so the plugin doesn't offer or list them. To add a rule type, declare arule_typeon its rule class and register a front-end module (form + completeness check) insrc/arches_abac_permissions/rule-types/index.ts. Once a rule is saved, the collapsed Index SQL section below its fields shows the SQL for an index that speeds up evaluating it (see Indexes for rules). - Assign Group Permissions to Rule (right): turn the rule on or off, and grant Read, Update and Delete (
view_/change_/delete_resourceinstance) to groups. Groups can be added and deleted here; a group with members, or a built-in Arches group (tagged Built-in), cannot be deleted. Groups tagged Public apply to logged-out visitors, and the plugin warns when such a group is granted access. Save stores the rule, its definition and all grants together.
The Group Membership view (switch at the top) lists groups, users and an editor. Filter users by group (or those with no group), open one to add or remove its groups, or tick several and choose Edit groups to change them together. Changes apply immediately via api/abac/users and api/abac/users/group_membership.
Only superusers can see the plugin or call its API (api/abac/...). An inactive rule grants nothing.
How inclusion rules work
An inclusion rule has:
- a rule class (
modulename+classname), which decides how resources are matched; - a definition, a JSON object of settings specific to the rule class;
- one or more group permissions, each pairing a Django group with the permissions its members get on matching resources.
When Arches checks a user's permissions on a single resource instance (viewing its report, opening it in the editor, deleting it), the framework adds the permissions from every rule that is assigned to one of the user's groups and that matches the resource.
Things to be aware of:
- SQL-based search (arches-search) honors inclusion rules; Elasticsearch search does not yet. Rules apply to single-resource permission checks and to
filter_resource_queryset, which arches-search uses. Resources a user can access through a rule will not yet appear in core Arches search results or on the search map. - Superusers bypass permission checks, so rules have no visible effect for them. Test with a non-superuser user.
- Users also need the model-level
read_nodegrouppermission ("Models | node group | Read") to read a resource. Arches requires this in addition to resource-instance permissions. - A group permission with no permissions selected grants nothing, and its rule is not evaluated.
- Granting to Guest makes resources public. Arches signs logged-out visitors in as the
anonymoususer, which belongs to Guest, so a rule granted to Guest (or to any group containinganonymous) applies to everyone who isn't logged in.
Available rule classes
modulename |
classname |
Matches |
|---|---|---|
lifecycle_state_rule.py |
LifecycleStateRule |
Resources of a graph that are in a given lifecycle state |
resource_set_rule.py |
ResourceSetRule |
The members of an arches-resource-sets resource set |
tile_node_value_rule.py |
TileNodeValueRule |
Resources of a graph with a tile whose node holds a given value |
spatial_rule.py |
SpatialRule |
Resources of a graph whose geometry in a given node intersects, lies within, or has its centre in an area |
search_rule.py |
SearchRule |
Not yet evaluated; stores a saved search query |
queryset_rule.py |
QuerySetRule |
Not yet evaluated |
Creating a lifecycle state rule
A lifecycle state rule grants permissions on every resource of a given resource model (graph) that is in a given lifecycle state, for example every Active resource of the Person model. When a resource moves to another lifecycle state, it stops matching the rule.
1. Find the graph and lifecycle state ids
The rule needs the id of a resource model and the id of one of the states in that model's resource instance lifecycle. You can list them from the Django shell:
python manage.py shell
>>> from arches.app.models.models import GraphModel
>>> for graph in GraphModel.objects.filter(isresource=True, source_identifier=None):
... print(graph.graphid, graph.name)
... for state in graph.resource_instance_lifecycle.resource_instance_lifecycle_states.all():
... print(" ", state.id, state.name)
Graphs that use Arches' default Standard lifecycle share these states:
| State | Id |
|---|---|
| Draft | 9375c9a7-dad2-4f14-a5c1-d7e329fdde4f |
| Active | f75bb034-36e3-4ab4-8167-f520cf0b4c58 |
| Retired | d95d9c0e-0e2c-4450-93a3-d788b91abcc8 |
2. Add the rule in the admin
Sign in as a superuser, go to /admin/, and under Arches_Abac_Permissions choose Inclusion rules → Add inclusion rule. Enter:
| Field | Example value | Notes |
|---|---|---|
| Owner | select user |
The user responsible for the rule. |
| Name | Active Person resources |
Any descriptive name. |
| Modulename | lifecycle_state_rule.py |
Must be exactly this value. |
| Classname | LifecycleStateRule |
Must be exactly this value. |
| Definition | see below | JSON. |
Definition:
{
"graphid": "22477f01-1a44-11e9-b0a9-000d3ab1e588",
"lifecycle_state_id": "f75bb034-36e3-4ab4-8167-f520cf0b4c58"
}
graphid: the id of the resource model from step 1. Replace the example value with a graph id from your own project.lifecycle_state_id: the id of the lifecycle state from step 1. It must be a state of the graph's lifecycle.
3. Grant permissions to a group
On the same page, under Inclusion rule group permissions, click Add another Inclusion rule group permission and enter:
| Field | Example value |
|---|---|
| Group | Resource Reviewer |
| Permissions | Models | resource instance | Read resource |
Move each permission you want to grant into the Chosen permissions box. The resource-instance permissions are:
| Permission shown in the admin | Codename | Allows |
|---|---|---|
| Models | resource instance | Read resource | view_resourceinstance |
Viewing the resource |
| Models | resource instance | Update resource | change_resourceinstance |
Editing the resource |
| Models | resource instance | Delete resource | delete_resourceinstance |
Deleting the resource |
Click Save. To grant the same rule to several groups, add one group permission per group.
4. Check the rule
Sign in as a non-superuser member of the group and open a resource of the graph that is in the lifecycle state. You can also check from the Django shell which resources the rule matches:
python manage.py shell
>>> from arches_abac_permissions.models import InclusionRule
>>> rule = InclusionRule.objects.get(name="Active Person resources")
>>> rule.get_matching_resources()
>>> rule.get_search_rule_url() # an equivalent Arches search, to view the matches
If the rule has no effect, check that:
- the user is in the group and is not a superuser;
- the group permission has at least one permission chosen;
- the user has the
read_nodegrouppermission; RULE_LOCATIONSis defined in your settings. If it's missing, loading the rule fails withAttributeError: 'Settings' object has no attribute 'RULE_LOCATIONS';- the logs don't show
Inclusion rule ... could not be evaluated. A rule that can't be evaluated, for example because its graph was deleted, is treated as matching nothing, so it grants nothing but doesn't break other permissions.
Creating a resource set rule
A resource set rule grants permissions on every member of a resource set from arches-resource-sets. Membership is read when permissions are checked, so adding a resource to the set or removing it takes effect straight away, with no change to the rule.
It needs the optional dependency, and arches_resource_sets in INSTALLED_APPS:
pip install "arches-abac-permissions[arches-resource-sets]"
Create the rule in the admin as for a lifecycle state rule, with modulename resource_set_rule.py, classname ResourceSetRule and definition:
{
"resource_set_id": "<id of the resource set>"
}
Things to be aware of:
- Deleting the set, or the user who owns it, removes the access silently. The rule then matches nothing, and nothing is logged.
Creating a tile node value rule
A tile node value rule grants permissions on every resource of a resource model that has a tile whose node holds a given value, for example every Person whose Classification is Staff. It reads the tiles table directly, so it doesn't need arches-search. Editing the tile changes access straight away.
Create it in the plugin (Resource has Node Value) or in the admin with modulename tile_node_value_rule.py, classname TileNodeValueRule and definition:
{
"graphid": "<id of the resource model>",
"nodeid": "<id of a node of that model>",
"value": "<the value, always as a string>",
"language": "<language code; string nodes only, empty for any language>"
}
| Node datatype | value |
Matches when |
|---|---|---|
string |
Text | The text in language (or any language) equals value |
non-localized-string |
Text | The text equals value |
number |
A number, e.g. "5" or "2.5" |
The number equals value |
boolean |
"true" or "false" |
The value is the same |
date |
The date as stored, e.g. "2020-01-31" |
The stored text equals value |
domain-value, domain-value-list |
The option id | The node holds that option |
resource-instance, resource-instance-list |
The related resource's id | The node relates to that resource |
reference |
The controlled list item id | The node holds that list item (needs arches.extensions.controlled_lists) |
Things to be aware of:
- Anyone who can edit the node controls access. A user who can save a tile on that node (or a bulk load or ETL writing tiles) can change which resources match, for example making a record public, or giving their own group Delete. Lock the node down with nodegroup permissions so only trusted groups can edit it.
- Matching is exact. Text is case sensitive and must match the whole value; dates aren't compared as dates. Numbers with more precision than a float can hold (e.g.
0.1000000000000000000001) are rejected rather than rounded. - Nodes of draft resource models can't be used; publish the model first.
- Concept and concept-list nodes, and other datatypes, aren't supported.
- Deleting the node or the resource model breaks the rule. It then matches nothing, and an error is logged each time it's evaluated.
Creating a spatial rule
A spatial rule grants permissions on every resource of a resource model whose geometry, in a given geometry node, is in an area, for example every Heritage Asset whose Location is inside a district. The operator sets what "in" means:
operator |
Plugin label | A resource matches when |
|---|---|---|
intersects (default) |
Touches or overlaps the area | Any of its geometries touches or overlaps the area |
within |
Is entirely inside the area | All of its geometries lie inside the area |
centroid |
Has its centre in the area | The centre of any of its geometries is in the area (or on its edge) |
With intersects, a large or linear geometry (a trail, a county) matches every area it touches, so a site on the boundary between two districts is visible to both districts' groups. within or centroid avoid this.
The rule reads Arches' geojson_geometries table. Core refreshes it only through after_update_all, which runs from the tile views (the resource editor), the importers and ETL modules, and Tile.update_node_value. Tiles saved any other way (Tile.save() in the Python API, custom functions, SQL) don't update it, so a geometry moved out of the area keeps matching until the tile is refreshed. Call tile.after_update_all() after such writes, or run SELECT refresh_geojson_geometries(); to rebuild the table.
Create it in the plugin (Resource is in Area), where you draw the area on the map or paste GeoJSON under Edit as GeoJSON, or in the admin with modulename spatial_rule.py, classname SpatialRule and definition:
{
"graphid": "<id of the resource model>",
"nodeid": "<id of a geojson-feature-collection node of that model>",
"geometry": {"type": "Polygon", "coordinates": [[[-0.2, 51.4], [0.1, 51.4], [0.1, 51.6], [-0.2, 51.4]]]},
"buffer": 500,
"operator": "within"
}
The map is core's map component: its tabs offer every basemap and overlay map layer, its Map Tools panel draws points, lines and polygons, and it has a full-screen button. Under Edit as GeoJSON the area is shown as a full GeoJSON FeatureCollection that you can copy or paste back; Copy GeoJSON puts it on the clipboard.
Things to be aware of:
- The area is GeoJSON in longitude/latitude (WGS 84): a polygon, point or line (or their
Multi*forms), or a flatGeometryCollectionof them mixing types. Onlytype,coordinatesandgeometriesare kept, so anycrsis dropped. bufferis an optional distance in meters (0 to 100,000), and is required for points and lines. Each part is buffered with PostGIS geography, so the distance is accurate at any latitude, and the buffered parts are merged. Set it with the map's built-in Buffer control in Map Tools (any unit; it is converted to meters and applied to every shape). The map previews the buffer, but the backend result is authoritative. The buffered area must stay within the limits below.- The area may have at most 10,000 vertices and be at most 180° of longitude wide; areas crossing the antimeridian aren't supported. Overlapping polygons are merged.
- Nodes of draft resource models can't be used; publish the model first.
- Deleting the node or the resource model breaks the rule. It then matches nothing, and an error is logged each time it's evaluated.
Indexes for rules
Rules are evaluated with SQL whenever permissions are checked, so a large database may need an index for them. The plugin shows the SQL for a saved rule under Index SQL, and InclusionRule.get_index_sql_for_rule() returns it. Run it against the Arches database with psql, outside a transaction (CREATE INDEX CONCURRENTLY can't run in one).
- Resource has Lifecycle State: one index on
resource_instances (graphid, resource_instance_lifecycle_state_id), shared by every such rule. - Resource is in Resource Set: none; the set membership table is already indexed.
- Resource has Node Value: a partial GIN index on the node's value in
tiles, one per node. Rules on the same node share it. - Resource is in Area: a partial GiST index on
geojson_geometries.geomfor the node, one per node. Rules on the same node share it.
Custom rule classes can return their own SQL from a get_index_sql(cls, inclusion_rule) classmethod; the default returns None.
Adding custom rules to your project
You can write your own rule classes in your Arches project; they don't have to live in this package. The examples below use a project called my_project.
How rule classes are found
When a rule is evaluated, its modulename and classname are looked up with Arches' get_class_from_modulename. It searches these packages, in order, and uses the first match:
<app>.rulesand<app>.pkg.extensions.rulesfor every installed app whoseAppConfigsetsis_arches_application = True, inINSTALLED_APPSorder;- any packages listed in the
RULE_LOCATIONSsetting.
Arches projects set is_arches_application = True in their AppConfig, so a rule in my_project/rules/ is found without any settings changes.
1. Write the rule class
Create an empty my_project/rules/__init__.py, then add a module for your rule, for example my_project/rules/my_rule.py:
from arches_abac_permissions.models import InclusionRule
class MyRule(InclusionRule):
"""Describe what the rule matches and the shape of its definition."""
@classmethod
def get_search_rule_url(cls, inclusion_rule):
# Return a search URL equivalent to the rule, or False if there is none.
return False
@classmethod
def get_matching_resources(cls, inclusion_rule):
# Return a ResourceInstance queryset of every resource the rule
# matches. Used to filter querysets, e.g. arches-search results. The
# rule's settings are in inclusion_rule.definition.
...
@classmethod
def matches_resource(cls, inclusion_rule, resource):
# Return True if `resource` matches the rule. Used for
# single-resource checks; usually
# cls.get_matching_resources(inclusion_rule).filter(pk=resource.pk).exists()
...
@classmethod
def validate_definition(cls, inclusion_rule):
# Raise ValidationError if inclusion_rule.definition is invalid. It is
# called when the rule is saved in the admin, so mistakes are caught
# before the rule is used. Optional; the default accepts anything.
...
class Meta:
proxy = True
app_label = "my_project"
- Rule classes are proxy models of
InclusionRule, so they share its table and add no columns. - Set
app_labelto your project's app label, or leave it out. Don't copyapp_label = "arches_abac_permissions"from the built-in rules: if you do,makemigrationswill try to write your rule's migration into this package. - Give the module a name the built-in rules don't use (not
lifecycle_state_rule,resource_set_rule,tile_node_value_rule,spatial_rule,search_ruleorqueryset_rule). Lookup uses the first match inINSTALLED_APPSorder, so a duplicate name could load the wrong class.
See arches_abac_permissions/rules/lifecycle_state_rule.py for a complete example.
2. Register the rule when Django starts
Import the module in your project's AppConfig.ready() so Django registers the proxy model at startup. Without this, makemigrations and content types won't know about the model until a rule using it is evaluated.
from django.apps import AppConfig
class MyProjectConfig(AppConfig):
name = "my_project"
is_arches_application = True
def ready(self):
# Register proxy rule models so they are known to the app registry.
from my_project.rules import my_rule # noqa
3. Create the migration
python manage.py makemigrations my_project
python manage.py migrate
The migration only records the proxy model and creates no table.
4. Use the rule
Create an inclusion rule in the admin as described in Creating a lifecycle state rule, entering your own module and class:
| Field | Value |
|---|---|
| Modulename | my_rule.py |
| Classname | MyRule |
| Definition | whatever JSON your rule class expects |
Running tests
python manage.py test tests --settings="tests.test_settings"
Metadata
Release files for arches-abac-permissions 0.1.0a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| arches_abac_permissions-0.1.0a1.tar.gz | 325.0 kB | Without provenance | Details for arches_abac_permissions-0.1.0a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| arches_abac_permissions-0.1.0a1-py3-none-any.whl | Python 3 | none | any | Details for arches_abac_permissions-0.1.0a1-py3-none-any.whl |
Total release size: 470.9 kB
Release files / arches_abac_permissions-0.1.0a1.tar.gz
| Download URL | arches_abac_permissions-0.1.0a1.tar.gz |
|---|---|
| Size | 325.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2e0f998f889c2f1371e73daa0a166f1913fb49b76465c529e20fbfd5ebfd4548
|
|
BLAKE2b-256 checksum How to use checksums |
70e3ff0ec155de9cb3281918fb2aeeb00a39a518c106723a7529fc2c2af67834
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.2
|
Release files / arches_abac_permissions-0.1.0a1-py3-none-any.whl
| Download URL | arches_abac_permissions-0.1.0a1-py3-none-any.whl |
|---|---|
| Size | 145.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3d8fd144be82b00b80101cd5b655329d52ce4ad125b29cca336caa918865e32a
|
|
BLAKE2b-256 checksum How to use checksums |
b030ab720b8a3f619dc6b8b96552893ff47558d2cfd72fc62261aaa7836bddf8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.2
|
Security for arches-abac-permissions 0.1.0a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.