User Authentication in DUFT Server

User Authentication in DUFT Server#

DUFT Server supports user authentication. Through user authentication, certain features are only available to authenticated users, with optionally a specific permission.

SUMMARY: You must configure a data store, and create initial fixtures through Django. A convenience management command, python manage.py first_run is available.

When to use User Authentication#

User authentication is useful for the following scenarios:

  • Deploing DUFT Server as a standalone server in a health facility, whereby multiple users will be accessing DUFT Server through, for example, a comuter or tablet (i.e. without the app)

  • Deploying DUFT Server as a standalone site, i.e. a reporting dashboard on a public website

Considerations for User Authentication#

When enabling UA, DUFT Server needs a database to store user credentials. DUFT Server can automatically create the required tables and initial data, but you must configure DUFT Server by telling it where this database is (you must create the database yourself, but not the tables, except in SQLite where the database can be created automatically). A logical option can be the Analaysis database, or a separate database on the same database server. Note that if the user database gets destroyed, all user accounts will be destroyed as well, so it is advisable to use a database that can be persisted (i.e. it should not be destroyed by data tasks).

Permissions in UA#

UA supports several permissions, which can be assigned to users. They are as follows:

Implemented Permissions:

  • run_data_task — Needed in order to run any data task

  • query_data — Needed to query data

  • change_settings — Needed to change settings, including updating parameters for data connections

  • upload_files — Needed to upload files, for example, to a central DUFT Server.

Future Permissions:

  • export_data — Needed to export data, not currently enforced

  • view_dashboard — Needed to view any dashboard, not currently enforced

At the moment, DUFT installations cannot add custom permissions yet, but this is something to be considered in a future version, allowing 3DL dashboards to provide role-based security.

How to enable UA#

To enable, UA, you must follow the following steps.

1. Enable the feature flag#

By default, UA is turned off. It must be enable through the following feature flag: FEATURE_USER_AUTHENTICATION=True Features flags are set via environment variables (or, optionally, through .env in the VS Code workspace, but this is only for developers) in which the Python/Django environment runs

2. Create a data store#

You must configure a data store for UA. This data store needs to adhere to standard Django database configuration settings, but it must be set through the config.json file in the config/user directory. For example:

{
    "dataConnectionParameters": {
        "ANA": {
            "server": "127.0.0.1",
            "username": "user",
            "password": "mysecretword",
            "port": "5432",
            "database": "analysis",
            "sqlite3file": "wakanda.sqlite",
            "type": "sqlite3"
        }
    },
    ...
    "djangoDatabases": {
        "default": {
            "ENGINE": "django.db.backends.sqlite3",
            "NAME": "%BASE_DIR%/db.sqlite3"
        }        
    }
}

This will configure UA to use a db.sqilite3 SQLite database file in the django server folder.

NOTE Do not use SQLite for any production environments ever, even for demonstration purposes. SQLite is not process safe, and should not ever be used for anything else than development.

3. Create database fixtures#

DUFT Server needs to create tables and other fixtures in the database. It also needs to create a super user. By default, the super user will be admin and password --------. This can be changed after.

To create the fixtures:

  1. Change to the DUFT Server directory, i.e. the directory containing manage.py

  2. Run python manage.py first_run OR python manage.py first_run -createsampleusers if you want to create a few sample users

If you have not configured the database correctly, you will get an error. first_run does the following:

  • Create tables (apply Python migrations)

  • Create custom permissions (through api/singals.py) needed by the API

  • Create roles, as follows:

    • “Data Manager”: run_data_task, change_settings

    • “Dashboard User”: query_data, view_dashboard

    • “Advanced Dashboard User”: query_data, view_dashboard, export_data

  • Create a super user admin with the password --------

  • Optionally: Create data_manager, dashboard_user, and advanced_dashboard_user as sample users in their respective roles, all with the password --------

NOTE first_run.py is safe to be repeated, it can be executed many times, and it will not overwrite existing information. In addition, it should be executed each time there is a new version of DUFT Server.

How to use UA from a Front End#

Once enabled, select APIs will begin to enforce permissions. At the moment, no APIs do this yet. However, the login API is already fully functional. The API currently only supports logging in, and is token based. The API is available to test through Swagger.

  1. Go to http://127.0.0.1:8000/swagger/ (or the port/server where DUFT Server is running)

  2. Look for the token api, create a token by entering the user name and password (admin/--------)

  3. Capture (copy) the token returned

  4. For any API calls requiring authentication, add the token as follows: Bearer <token> — this can be tested using the /token/test API

  5. The test API also returns the permissions available to the end user, which may be helful in determining whether a user has a specific permission, and to hide certain UI elements.

Specific Permissions#

Running Queries#

Running queries requires the query_data permission. When UA is enabled, and a user does not have this permisssion, a 401 will be returned.

This applies to the following APIs:

  • api/v2/run-query

Executing Data Tasks#

Executing any data task, or querying the system for available data tasks requires the run_data_task permission. This has been implemented. When UA is enabled, and a user does not have this permisssion, a 401 will be returned.

This applies to the following APIs:

  • api/v2/dte-status

  • api/v2/run-data-task

  • api/v2/data-task/<data_task_id>

Uploading Files#

Uploading Files, such as monthly report datasets requires the upload_files permission.

NOTE This feature cannot be used without user authentication enabled.

This applies to the following APIs:

  • api/v2/upload-file

Using the Config#

Most config APIs require a user only to be authenticated, with no additional permissions needed. This includes retrieveing navigation files, theme files, data task files, and more. However, to update a data connection’s parameters (i.e. the POST), the change_setting permission is required. If a user does not have sufficient permission, a 401 or 403 may be returned.

This applies to the following APIs:

  • api/v2/navigation

  • api/v2/theme

  • api/v2/dashboard/<str:dashboard_name>

  • api/v2/3dldashboard/<str:dashboard_name>

  • api/v2/data-connections

  • api/v2/data-connections/<connection_id>/parameters - GET IsAuthenticated only

  • api/v2/data-connections/<connection_id>/parameters - POST IsAuthenticated and HasChangeSetttingPermission

DUFT Server Implementation Details#

  • DUFT Server uses django.auth for authentication, including the admin backend.

  • Default permissions are created in duft-server/api/signals.py as part of the api-app. The reason for this is that permissions are only enforced within the API views, and not anywhere else.

  • Optional default users are created in duft-server/app/management/commands/first_run.py as part of the python manage.py first_run -createsampleusers command

Contents