django-vkey

django app to add hkey auth to vpal webservices.

sample_project using django-vkey

To have a simple django sample_project to be behind hkey do the following:

1 install django_vkey pkg

django_vkey depends no python3-saml. This is mentioned in python3-saml docs: due to versioning sync problems it's best to install some dependencies from source (namely lxml and xmlsec). These libs also require underlying os packages to be present.

# in ubuntu 24.04 we did something like:
$> apt-get install libxml2-dev lxxmlsec1-dev libxmlsec1-openssl

# using venv
$> source venv/saml/bin/activate
(saml)$> pip install --no-binary lxml,xmlsec git+https://github.com/HarvardX/django-vkey.git@main

2 add to sample_project/settings.py

# add django_vkey to INSTALLED_APPS
INSTALLED_APPS = [
    ...
    'django_vkey',
]

# django_vkey configs
# for python3_saml config, see example at saml/settings.json and saml/advanced_settings.json
SAML_FOLDER = BASE_DIR / "saml"

# if you want to have first/last name for the user, these have to come as attributes
# first name
SAML_FNAME_ATTR = "urn:oid:2.5.4.42"
# last name
SAML_LNAME_ATTR = "urn:oid:2.5.4.4"

3 include saml urls

Assuming the django project has a main landing page from where the user can access the rest of the web pages in this django project webservice. All pages protected via hkey require login with @login_required decorator, and urls.py look like below (check sample_project/sample_project/urls.py).

For urls "index/" and "saml/", when the user is authorized, at the end of the saml auth workflow, the user is redirected to the sample_project landing page. From there, since the user is authenticated and logged in, they can access other views.

from django.urls import path

import django_vkey.views as vkey_views
import .views as sample_views

urlpatterns = [
    path(
        "index/",
        vkey_views.hkey_index,

        # sample_project landing page
        {"service_view": sample_views.landing},

        name="index",
    ),
    path(
        "saml/metadata/",

        # vkey provided sp metadata endpoint
        vkey_views.metadata,

        name="saml_metadata",
    ),
    path(
        "saml/",

        # vkey provided sp saml acs endpoint
        vkey_views.saml,

        # sample_project landing page
        {"service_view": sample_views.landing},

        name="saml",
    ),
]