Authentication & Security

In order to enable authentication, add the auth paramer to your .ini file:

auth = true

Nefertari currently uses the default Pyramid “auth ticket” cookie mechanism.

Custom User Model

When authentication is enabled, Nefertari uses its own User model. This model has 4 fields by default: username, email, password and groups (list field with values ‘admin’ and ‘user’). However, this model can be extanded.

from nefertari import engine as eng
from nefertari.authentication.models import AuthUserMixin
from nefertari.engine import BaseDocument

class User(AuthUserMixin, BaseDocument):
    __tablename__ = 'users'

    first_name = eng.StringField(max_length=50, default='')
    last_name = eng.StringField(max_length=50, default='')

Visible Fields in Views

You can control which fields to display by defining the following properties on your models:

Lists fields to be displayed to authenticated users.
Lists fields to be displayed to all users including unauthenticated users.
Lists fields to be hidden but remain editable (as long as user has permission), e.g. password.


This section describes permissions used by nefertari, their relation to view methods and HTTP methods. These permissions should be used when defining ACLs.

To make things easier to grasp, let’s imagine we have an application that defines a view which handles all possible requests under /products route. We are going to use this example to make permissions description more obvious.

Following lists nefertari permissions along with HTTP methods and view methods they correspond to:

  • Collection GET (GET /products). View method index
  • Item GET (GET /products/1) View method show
  • Collection HEAD (HEAD /products). View method index
  • Item HEAD (HEAD /products/1). View method show
  • Collection POST (POST /products). View method create
  • Collection PATCH (PATCH /products). View method update_many
  • Collection PUT (PUT /products). View method update_many
  • Item PATCH (PATCH /products/1). View method update
  • Item PUT (PUT /products/1) View method replace
  • Collection DELETE (DELETE /products). View method delete_many
  • Item DELETE (DELETE /products/1). View method delete
  • Collection OPTIONS (OPTIONS /products). View method collection_options
  • Item OPTIONS (OPTIONS /products/1). View method item_options


For authorizing access to specific resources, Nefertari uses standard Pyramid access control lists. See the documentation on Pyramid ACLs to understand how to extend and customize them.

  • An item will inherit its collection’s permissions if the item’s permissions are not specified in an ACL class
  • If you create an ACL class for your document that does something like give the document.owner edit permissions, then you can’t rely on this setting to be respected during collection operation. in other words, only if you walk up to the item via a URL will this permission setting be applied.
class nefertari.acl.AuthenticatedReadACL(request, name='', parent=None)

Authenticated users ACL base class

Gives read access to all Authenticated users. Gives delete, create, update access to admin only.

class nefertari.acl.AuthenticationACL(request, name='', parent=None)

Special ACL factory to be used with authentication views (login, logout, register, etc.)

Allows create, view and option methods to everyone.

class nefertari.acl.CollectionACL(request, name='', parent=None)

Collection resource.

You must specify the item_model. It should be a nefertari.engine document class. It is the model class for collection items.

Define a __acl__ attribute on this class to define the container’s permissions, and default child permissions. Inherits its acl from the root, if no acl is set.

Override the item_acl method if you wish to provide custom acls for collection items.

Override the item_db_id method if you wish to transform the collection item db id, e.g. to support a self item on a user collection.

class nefertari.acl.Contained(request, name='', parent=None)

Contained base class resource

Can inherit its acl from its parent.

class nefertari.acl.GuestACL(request, name='', parent=None)

Guest level ACL base class

Gives read permissions to everyone.


Helper function that can be used in db_key to support self as a collection key.

Advanced ACLs

For more advanced ACLs, you can look into using nefertari-guards in you project. This package stores ACLs at the object level, making it easier to build multi-tenant applications using a single data store.


To enable CORS headers, set the following lines in your .ini file:

cors.enable = true
cors.allow_origins = http://localhost
cors.allow_credentials = true