Skip to content

Object-Based Permissions

NetBox v2.9 introduced a new object-based permissions framework, which replaces 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.

A permission in NetBox represents a relationship shared by several components:

  • Object type(s) - One or more types of object in NetBox
  • User(s)/Group(s) - One or more users or groups of users
  • Action(s) - The action(s) that can be performed on an object
  • 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

In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. 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.

Note

Internally, all actions granted by a permission (both built-in and custom) are stored as strings in an array field named actions.

Constraints

Constraints are expressed as a JSON object or list representing a Django query filter. 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 attributes defined within a single JSON object are applied with a logical AND. For example, suppose you assign a permission for the site model with the following constraints.

{
  "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, define multiple objects within a list. For example, if you want to constrain the permission to VLANs with an ID between 100 and 199 or a status of "reserved," do the following:

[
  {
    "vid__gte": 100,
    "vid__lt": 200
  },
  {
    "status": "reserved"
  }
]

Additionally, where multiple permissions have been assigned for an object type, their collective constraints will be merged using a logical "OR" operation.

User Token

This feature was introduced in NetBox v3.3

When defining a permission constraint, administrators may use the special token $user to reference the current user at the time of evaluation. This can be helpful to restrict users to editing only their own journal entries, for example. Such a constraint might be defined as:

{
  "created_by": "$user"
}

The $user token can be used only as a constraint value, or as an item within a list of values. It cannot be modified or extended to reference specific user attributes.

Example Constraint Definitions

Constraints Description
{"status": "active"} Status is active
{"status__in": ["planned", "reserved"]} Status is active OR reserved
{"status": "active", "role": "testing"} Status is active AND role is testing
{"name__startswith": "Foo"} Name starts with "Foo" (case-sensitive)
{"name__iendswith": "bar"} Name ends with "bar" (case-insensitive)
{"vid__gte": 100, "vid__lt": 200} VLAN ID is greater than or equal to 100 AND less than 200
[{"vid__lt": 200}, {"status": "reserved"}] VLAN ID is less than 200 OR status is reserved

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:

[
    {"site__name__in":  ["NYC1", "NYC2"]},
    {"status":  "offline", "tenant__isnull":  true}
]

This 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:

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 rolled back, leaving the database in its original state prior to the change, and the user is informed of the violation.