Merge pull request #4705 from netbox-community/554-object-permissions

Closes #554: Implement object-based permissions

docs/administration/permissions.md

@@ -0,0 +1,43 @@
+# Permissions
+
+NetBox v2.9 introduced a new object-based permissions framework, which replace's Django's built-in permission model. Object-based permissions allow for the assignment of permissions to an arbitrary subset of objects of a certain type, rather than only by type of object. For example, it is possible to grant a user permission to view only sites within a particular region, or to modify only VLANs with a numeric ID within a certain range.
+
+{!docs/models/users/objectpermission.md!}
+
+### Example Constraint Definitions
+
+| Query Filter | Permission Constraints |
+| ------------ | --------------------- |
+| `filter(status='active')` | `{"status": "active"}` |
+| `filter(status='active', role='testing')` | `{"status": "active", "role": "testing"}` |
+| `filter(status__in=['planned', 'reserved'])` | `{"status__in": ["planned", "reserved"]}` |
+| `filter(name__startswith('Foo')` | `{"name__startswith": "Foo"}` |
+| `filter(vid__gte=100, vid__lt=200)` | `{"vid__gte": 100, "vid__lt": 200}` |
+
+## Permissions Enforcement
+
+### Viewing Objects
+
+Object-based permissions work by filtering the database query generated by a user's request to restrict the set of objects returned. When a request is received, NetBox first determines whether the user is authenticated and has been granted to perform the requested action. For example, if the requested URL is `/dcim/devices/`, NetBox will check for the `dcim.view_device` permission. If the user has not been assigned this permission (either directly or via a group assignment), NetBox will return a 403 (forbidden) HTTP response.
+
+If the permission has been granted, NetBox will compile any specified constraints for the model and action. For example, suppose two permissions have been assigned to the user granting view access to the device model, with the following constraints:
+
+```json
+[
+    {"site__name__in":  ["NYC1", "NYC2"]},
+    {"status":  "offline", "tenant__isnull":  true}
+]
+```
+
+This grants the user access to view any device that is in NYC1 or NYC2, **or** which has a status of "offline" and has no tenant assigned. These constraints will result in the following ORM query:
+
+```no-highlight
+Site.objects.filter(
+    Q(site__name__in=['NYC1', 'NYC2']),
+    Q(status='active', tenant__isnull=True)
+)
+```
+
+### Creating and Modifying Objects
+
+The same sort of logic is in play when a user attempts to create or modify an object in NetBox, with a twist. Once validation has completed, NetBox starts an atomic database transaction to facilitate the change, and the object is created or saved normally. Next, still within the transaction, NetBox issues a second query to retrieve the newly created/updated object, filtering the restricted queryset with the object's primary key. If this query fails to return the object, NetBox knows that the new revision does not match the constraints imposed by the permission. The transaction is then aborted, and the database is left in its original state.

docs/configuration/optional-settings.md

@@ -384,7 +384,7 @@ NetBox can be configured to support remote user authentication by inferring user
 
 ## REMOTE_AUTH_BACKEND
 
-Default: `'utilities.auth_backends.RemoteUserBackend'`
+Default: `'netbox.authentication.RemoteUserBackend'`
 
 Python path to the custom [Django authentication backend](https://docs.djangoproject.com/en/stable/topics/auth/customizing/) to use for external user authentication, if not using NetBox's built-in backend. (Requires `REMOTE_AUTH_ENABLED`.)
 
@@ -416,9 +416,9 @@ The list of groups to assign a new user account when created using remote authen
 
 ## REMOTE_AUTH_DEFAULT_PERMISSIONS
 
-Default: `[]` (Empty list)
+Default: `{}` (Empty dictionary)
 
-The list of permissions to assign a new user account when created using remote authentication. (Requires `REMOTE_AUTH_ENABLED`.)
+A mapping of permissions to assign a new user account when created using remote authentication. Each key in the dictionary should be set to a dictionary of the attributes to be applied to the permission, or `None` to allow all objects. (Requires `REMOTE_AUTH_ENABLED`.)
 
 ---
 

docs/development/utility-views.md

@@ -4,6 +4,10 @@ Utility views are reusable views that handle common CRUD tasks, such as listing
 
 ## Individual Views
 
+### ObjectView
+
+Retrieve and display a single object.
+
 ### ObjectListView
 
 Generates a paginated table of objects from a given queryset, which may optionally be filtered.

docs/models/users/objectpermission.md

@@ -0,0 +1,36 @@
+# Object Permissions
+
+Assigning a permission in NetBox entails defining a relationship among several components:
+
+* Object type(s) - One or more types of object in NetBox
+* User(s) - One or more users or groups of users
+* Actions - The actions that can be performed (view, add, change, and/or delete)
+* Constraints - An arbitrary filter used to limit the granted action(s) to a specific subset of objects
+
+At a minimum, a permission assignment must specify one object type, one user or group, and one action. The specification of constraints is optional: A permission without any constraints specified will apply to all instances of the selected model(s).
+
+## Actions
+
+There are four core actions that can be permitted for each type of object within NetBox, roughly analogous to the CRUD convention (create, read, update, and delete):
+
+* View - Retrieve an object from the database
+* Add - Create a new object
+* Change - Modify an existing object
+* Delete - Delete an existing object
+
+Some models introduce additional permissions that can be granted to allow other actions. For example, the `napalm_read` permission on the device model allows a user to execute NAPALM queries on a device via NetBox's REST API. These can be specified when granting a permission in the "additional actions" field.
+
+## Constraints
+
+Constraints are defined as a JSON object representing a [Django query filter](https://docs.djangoproject.com/en/stable/ref/models/querysets/#field-lookups). This is the same syntax that you would pass to the QuerySet `filter()` method when performing a query using the Django ORM. As with query filters, double underscores can be used to traverse related objects or invoke lookup expressions. Some example queries and their corresponding definitions are shown below.
+
+All constraints defined on a permission are applied with a logic AND. For example, suppose you assign a permission for the site model with the following constraints.
+
+```json
+{
+  "status": "active",
+  "region__name": "Americas"
+}
+```
+
+The permission will grant access only to sites which have a status of "active" **and** which are assigned to the "Americas" region. To achieve a logical OR with a different set of constraints, simply create another permission assignment for the same model and user/group. 

docs/release-notes/version-2.9.md

@@ -0,0 +1,18 @@
+# NetBox v2.8
+
+## v2.9.0 (FUTURE)
+
+### New Features
+
+#### Object-Based Permissions ([#554](https://github.com/netbox-community/netbox/issues/554))
+
+NetBox v2.9 replaces Django's built-in permissions framework with one that supports object-based assignment of permissions using arbitrary constraints. When granting a user or group to perform a certain action on one or more types of objects, an administrator can optionally specify a set of constraints. The permission will apply only to objects which match the specified constraints. For example, assigning permission to modify devices with the constraint `{"tenant__group__name": "Customers"}` would grant the permission only for devices assigned to a tenant belonging to the "Customers" group.
+
+### Configuration Changes
+
+* `REMOTE_AUTH_DEFAULT_PERMISSIONS` now takes a dictionary rather than a list. This is a mapping of permission names to a dictionary of constraining attributes, or `None`. For example, `['dcim.add_site', 'dcim.change_site']` would become `{'dcim.add_site': None, 'dcim.change_site': None}`.
+
+### Other Changes
+
+* The `secrets.activate_userkey` permission no longer exists. Instead, `secrets.change_userkey` is checked to determine whether a user has the ability to activate a UserKey.
+* The `users.delete_token` permission is no longer enforced. All users are permitted to delete their own API tokens.

mkdocs.yml

@@ -58,6 +58,7 @@ nav:
         - Using Plugins: 'plugins/index.md'
         - Developing Plugins: 'plugins/development.md'
     - Administration:
+        - Permissions: 'administration/permissions.md'
         - Replicating NetBox: 'administration/replicating-netbox.md'
         - NetBox Shell: 'administration/netbox-shell.md'
     - API:

netbox/circuits/models.py

@@ -8,6 +8,7 @@
 from dcim.models import CableTermination
 from extras.models import CustomFieldModel, ObjectChange, TaggedItem
 from extras.utils import extras_features
+from utilities.querysets import RestrictedQuerySet
 from utilities.models import ChangeLoggedModel
 from utilities.utils import serialize_object
 from .choices import *
@@ -66,9 +67,10 @@ class Provider(ChangeLoggedModel, CustomFieldModel):
         content_type_field='obj_type',
         object_id_field='obj_id'
     )
-
     tags = TaggableManager(through=TaggedItem)
 
+    objects = RestrictedQuerySet.as_manager()
+
     csv_headers = [
         'name', 'slug', 'asn', 'account', 'portal_url', 'noc_contact', 'admin_contact', 'comments',
     ]
@@ -115,6 +117,8 @@ class CircuitType(ChangeLoggedModel):
         blank=True,
     )
 
+    objects = RestrictedQuerySet.as_manager()
+
     csv_headers = ['name', 'slug', 'description']
 
     class Meta:
@@ -300,6 +304,8 @@ class CircuitTermination(CableTermination):
         blank=True
     )
 
+    objects = RestrictedQuerySet.as_manager()
+
     class Meta:
         ordering = ['circuit', 'term_side']
         unique_together = ['circuit', 'term_side']

netbox/circuits/querysets.py

@@ -1,7 +1,9 @@
-from django.db.models import OuterRef, QuerySet, Subquery
+from django.db.models import OuterRef, Subquery
 
+from utilities.querysets import RestrictedQuerySet
 
-class CircuitQuerySet(QuerySet):
+
+class CircuitQuerySet(RestrictedQuerySet):
 
     def annotate_sites(self):
         """

netbox/circuits/urls.py

@@ -10,7 +10,7 @@
 
     # Providers
     path('providers/', views.ProviderListView.as_view(), name='provider_list'),
-    path('providers/add/', views.ProviderCreateView.as_view(), name='provider_add'),
+    path('providers/add/', views.ProviderEditView.as_view(), name='provider_add'),
     path('providers/import/', views.ProviderBulkImportView.as_view(), name='provider_import'),
     path('providers/edit/', views.ProviderBulkEditView.as_view(), name='provider_bulk_edit'),
     path('providers/delete/', views.ProviderBulkDeleteView.as_view(), name='provider_bulk_delete'),
@@ -21,27 +21,26 @@
 
     # Circuit types
     path('circuit-types/', views.CircuitTypeListView.as_view(), name='circuittype_list'),
-    path('circuit-types/add/', views.CircuitTypeCreateView.as_view(), name='circuittype_add'),
+    path('circuit-types/add/', views.CircuitTypeEditView.as_view(), name='circuittype_add'),
     path('circuit-types/import/', views.CircuitTypeBulkImportView.as_view(), name='circuittype_import'),
     path('circuit-types/delete/', views.CircuitTypeBulkDeleteView.as_view(), name='circuittype_bulk_delete'),
     path('circuit-types/<slug:slug>/edit/', views.CircuitTypeEditView.as_view(), name='circuittype_edit'),
     path('circuit-types/<slug:slug>/changelog/', ObjectChangeLogView.as_view(), name='circuittype_changelog', kwargs={'model': CircuitType}),
 
     # Circuits
     path('circuits/', views.CircuitListView.as_view(), name='circuit_list'),
-    path('circuits/add/', views.CircuitCreateView.as_view(), name='circuit_add'),
+    path('circuits/add/', views.CircuitEditView.as_view(), name='circuit_add'),
     path('circuits/import/', views.CircuitBulkImportView.as_view(), name='circuit_import'),
     path('circuits/edit/', views.CircuitBulkEditView.as_view(), name='circuit_bulk_edit'),
     path('circuits/delete/', views.CircuitBulkDeleteView.as_view(), name='circuit_bulk_delete'),
     path('circuits/<int:pk>/', views.CircuitView.as_view(), name='circuit'),
     path('circuits/<int:pk>/edit/', views.CircuitEditView.as_view(), name='circuit_edit'),
     path('circuits/<int:pk>/delete/', views.CircuitDeleteView.as_view(), name='circuit_delete'),
     path('circuits/<int:pk>/changelog/', ObjectChangeLogView.as_view(), name='circuit_changelog', kwargs={'model': Circuit}),
-    path('circuits/<int:pk>/terminations/swap/', views.circuit_terminations_swap, name='circuit_terminations_swap'),
+    path('circuits/<int:pk>/terminations/swap/', views.CircuitSwapTerminations.as_view(), name='circuit_terminations_swap'),
 
     # Circuit terminations
-
-    path('circuits/<int:circuit>/terminations/add/', views.CircuitTerminationCreateView.as_view(), name='circuittermination_add'),
+    path('circuits/<int:circuit>/terminations/add/', views.CircuitTerminationEditView.as_view(), name='circuittermination_add'),
     path('circuit-terminations/<int:pk>/edit/', views.CircuitTerminationEditView.as_view(), name='circuittermination_edit'),
     path('circuit-terminations/<int:pk>/delete/', views.CircuitTerminationDeleteView.as_view(), name='circuittermination_delete'),
     path('circuit-terminations/<int:termination_a_id>/connect/<str:termination_b_type>/', CableCreateView.as_view(), name='circuittermination_connect', kwargs={'termination_a_type': CircuitTermination}),