1# Permissions
2
3NetBox v2.9 introduced a new object-based permissions framework, which replace's Django's built-in permissions model. Object-based permissions enable an administrator to grant users or groups the ability to perform an action on arbitrary subsets of objects in NetBox, rather than all objects of a certain type. 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.
4
5{!models/users/objectpermission.md!}
6
7### Example Constraint Definitions
8
9| Constraints | Description |
10| ----------- | ----------- |
11| `{"status": "active"}` | Status is active |
12| `{"status__in": ["planned", "reserved"]}` | Status is active **OR** reserved |
13| `{"status": "active", "role": "testing"}` | Status is active **AND** role is testing |
14| `{"name__startswith": "Foo"}` | Name starts with "Foo" (case-sensitive) |
15| `{"name__iendswith": "bar"}` | Name ends with "bar" (case-insensitive) |
16| `{"vid__gte": 100, "vid__lt": 200}` | VLAN ID is greater than or equal to 100 **AND** less than 200 |
17| `[{"vid__lt": 200}, {"status": "reserved"}]` | VLAN ID is less than 200 **OR** status is reserved |
18
19## Permissions Enforcement
20
21### Viewing Objects
22
23Object-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.
24
25If 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:
26
27```json
28[
29    {"site__name__in":  ["NYC1", "NYC2"]},
30    {"status":  "offline", "tenant__isnull":  true}
31]
32```
33
34This grants the user access to view any device that is assigned to a site named NYC1 or NYC2, **or** which has a status of "offline" and has no tenant assigned. These constraints are equivalent to the following ORM query:
35
36```no-highlight
37Site.objects.filter(
38    Q(site__name__in=['NYC1', 'NYC2']),
39    Q(status='active', tenant__isnull=True)
40)
41```
42
43### Creating and Modifying Objects
44
45The 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 rolled back, leaving the database in its original state prior to the change, and the user is informed of the violation.
46