Skip to main content

Authentication for clinicedc/edc projects.

Project description

pypi actions codecov downloads


Authentication and permissions for the Edc

Default Groups

The default groups are required for the normal operation of an EDC deployment. The default groups are:

  • ACCOUNT_MANAGER: members may add/change and delete user accounts
  • ADMINISTRATION: members may view the Administration page
  • AUDITOR: members may view all forms but have no add/change permissions.
  • CLINIC: members may add/edit/delete all CRFs, Requisitions, Actions and other required clinic trial data entry forms. They may also view the Requisition page of the Lab section;
  • EVERYONE: members may access the EDC;
  • LAB: members may perform all functions in the Lab section (Edit requisitions, receive, process, pack, manage manifests, etc);
  • PII: members may view all personally identifiable data and edit forms that manage such data (Screening, Consents, Patient registration);
  • PII_VIEW: members may view personally identifiable data but have no add/edit permissions for any of the forms that store such data.


Permissions use Django’s permission framework, therefore, all permissions are linked to some model.

Permissions don’t always naturally link to a model. In such cases, a dummy model is created. For example, with Navigation bars from edc_navbar. Permissions to follow an item on a navigation bar are associated with model edc_navbar.Navbar. A similar approach is used for listboard permissions using edc_dashboard.Dashboard.

Extending permissions with site_auths global

A module can add new or update existing groups and roles and even add custom codenames.

The site_auths global autodiscovers configurations from in the root of your module. The site_auths global gathers but does not validate or change any data in django’s group/permission models or the Edc’s role model.

The site_auths global gathers data: * to ADD new groups, * to update codenames for an existing group, * to add a new role * to update the group list for an existing role * to add to the list of PII models * to specifiy custom functions to run before and after groups and roles have been updated

For example,

from edc_auth.auth_objects import CLINICIAN_ROLE, STATISTICIAN_ROLE
from edc_auth.site_auths import site_auths

from edc_protocol_violation.auth_objects import (

# add a new group specific to models in this module
site_auths.add_group(*protocol_violation_codenames, name=PROTOCOL_VIOLATION)
# add a new group specific to models in this module
site_auths.add_group(*protocol_violation_view_codenames, name=PROTOCOL_VIOLATION_VIEW)
# update the existing role CLINICIAN_ROLE to add the group PROTOCOL_VIOLATION
site_auths.update_role(PROTOCOL_VIOLATION, name=CLINICIAN_ROLE)
# update the existing role STATISTICIAN_ROLE to add the group PROTOCOL_VIOLATION_VIEW

As a convention, we define group names, lists of codenames and custom functions

In the above example, the looks like this:


# declare group names
# add/change/delete/view codenames
protocol_violation_codenames = (
# view only codename
protocol_violation_view_codenames = (


The AuthUpdater class runs in a post_migrate signal declared in The AuthUpdater reads and validates the data gathered by site_auths. Once all validation checks pass, the AuthUpdater updates Django’s group and permission models as well as the Edc’s Role model.

Validation checks include confirming models refered to in codenames exist. This means that the app where models are declared must be in your INSTALLED_APPS.

During tests having all codenames load may not be ideal. See below on some strategies for testing.

Testing SiteAuths, AuthUpdater

An app sets up its own groups and roles using the site_auths global in To test just your apps configuration, you can prevent site_auths from autodiscovering other modules by setting:


You can prevent the AuthUpdater from updating groups and permissions by setting:


You can then override these attributes in your tests

class TestMyTests(TestCase):

Above the site_auths global autodiscover is still disabled but the AuthUpdater is not. In your test setup you can update site_auths manually so that your tests focus on the add/update or groups/roles/codenames/tuples relevant to your app.

You can emulate autodiscover behaviour by explicitly importing auths modules needed for your tests.

For example:

from importlib import import_module

from django.test import TestCase, override_settings
from edc_auth.auth_updater import AuthUpdater

class TestAuths(TestCase):
    def test_load(self):

You can clear the site_auths registry and add back specific items need for your tests.

For example:

# taken from edc-dashboard
class TestMyTests(TestCase):
    def setUpTestData(cls):
        site_auths.add_group("edc_dashboard.view_my_listboard", name=CLINIC)
            codename_tuples=(("edc_dashboard.view_my_listboard", "View my listboard"),),
        AuthUpdater(verbose=False, warn_only=True)
        return super().setUpTestData()

    def test_me(self):

Importing users

You create user accounts by importing a specially formatted CSV file. Once an account is created a “Welcome” email may be sent.

Import users from a CSV file with columns:

sites: a comma-separated list of sites
groups: a comma-separated list of groups

Then import the users from your application commandline

python import_users --csvfile=/Users/erikvw/meta_users.csv --notify-to-test-email=ew2789@gmail --resend-as-new

Legacy notes

Important: If you are upgrading from edc_base.auth:

The userprofile table is now in edc_auth. edc_auth has one migration for this table. Copy the same table from edc_base and fake the edc_auth migration.

CREATE TABLE edc_auth_userprofile LIKE edc_base_userprofile;

INSERT edc_auth_userprofile SELECT * FROM edc_base_userprofile;
python migrate edc_auth --fake

You can now run the edc_base migration safely.

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for edc-auth, version 0.3.32
Filename, size File type Python version Upload date Hashes
Filename, size edc_auth-0.3.32-py2.py3-none-any.whl (79.6 kB) File type Wheel Python version py2.py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page