Metadata-Version: 2.1
Name: edc-auth
Version: 0.3.20
Summary: Authentication for clinicedc/edc projects.
Home-page: https://github.com/clinicedc/edc-auth
Author: Erik van Widenfelt
Author-email: ew2789@gmail.com
License: GPL license, see LICENSE
Keywords: django auth edc
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.0
Classifier: Framework :: Django :: 3.1
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.8
Requires-Dist: mempass

|pypi| |actions| |codecov| |downloads|

edc-auth
--------

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);
* ``PHARMACY``:
* ``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
+++++++++++

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 `auths.py` 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,

.. code-block:: python

    # auths.py
    from edc_auth.default_role_names import CLINICIAN_ROLE, STATISTICIAN_ROLE
    from edc_auth.site_auths import site_auths

    from edc_protocol_violation.auth_objects import (
        PROTOCOL_VIOLATION,
        PROTOCOL_VIOLATION_VIEW,
        protocol_violation_codenames,
        protocol_violation_view_codenames,
    )

    # 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
    site_auths.update_role(PROTOCOL_VIOLATION_VIEW, name=STATISTICIAN_ROLE)


As a convention, we define group names, lists of codenames and custom functions `auth_objects.py`.

In the above example, the `auth_objects.py` looks like this:

.. code-block:: python

    # auth_objects.py

    # declare group names
    PROTOCOL_VIOLATION = "PROTOCOL_VIOLATION"
    PROTOCOL_VIOLATION_VIEW = "PROTOCOL_VIOLATION_VIEW"
    # add/change/delete/view codenames
    protocol_violation_codenames = (
        "edc_protocol_violation.add_protocoldeviationviolation",
        "edc_protocol_violation.change_protocoldeviationviolation",
        "edc_protocol_violation.delete_protocoldeviationviolation",
        "edc_protocol_violation.view_protocoldeviationviolation",
    )
    # view only codename
    protocol_violation_view_codenames = (
        "edc_protocol_violation.view_protocoldeviationviolation",
    )


AuthUpdater
+++++++++++
The `AuthUpdater` class runs in a post_migrate signal declared in `apps.py`. 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.



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:

.. code-block:: bash

    username
    first_name
    last_name
    job_title
    email
    alternate_email
    mobile
    sites: a comma-separated list of sites
    groups: a comma-separated list of groups


Then import the users from your application commandline

.. code-block:: bash

    python manage.py import_users --csvfile=/Users/erikvw/meta_users.csv --notify-to-test-email=ew2789@gmail --resource-name=meta.clinicedc.org --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.

.. code-block:: sql

	CREATE TABLE edc_auth_userprofile LIKE edc_base_userprofile;

	INSERT edc_auth_userprofile SELECT * FROM edc_base_userprofile;


.. code-block:: bash

	python manage.py migrate edc_auth --fake

You can now run the ``edc_base`` migration safely.

.. |pypi| image:: https://img.shields.io/pypi/v/edc-auth.svg
    :target: https://pypi.python.org/pypi/edc-auth

.. |actions| image:: https://github.com/clinicedc/edc-auth/workflows/build/badge.svg?branch=develop
  :target: https://github.com/clinicedc/edc-auth/actions?query=workflow:build

.. |codecov| image:: https://codecov.io/gh/clinicedc/edc-auth/branch/develop/graph/badge.svg
  :target: https://codecov.io/gh/clinicedc/edc-auth

.. |downloads| image:: https://pepy.tech/badge/edc-auth
   :target: https://pepy.tech/project/edc-auth



