django-realme: a Django app for integrating the RealMe authentication service

This is a Django package and a small example Django application to show how to use the RealMe authentication service with your Django project. All instructions are based on Ubuntu 16.04 LTS.

Install prerequisites

• libxmlsec1-dev
• pkg-config

Stages and Environments

The RealMe authentication service is divided into three separate environments, split up by function: development, testing, and production. These are:

• Stage 1: Message Test Site (MTS)
• Stage 2: Integration Test Environment (ITE)
• Stage 3: Production Environment (PRD)

Bundles

For each environment above, RealMe will provide a Bundle zip file:

• Integration Bundle MTS V2.1.zip
• Integration Bundle ITE V2.0.zip
• Integration Bundle Production V2.0.zip

Each Bundle contains the keys, certificates and configuration for integrating with the RealMe service. For MTS, it contains a pre-built sample key and certificate, so you can use them directly for development. For ITE and PRD, you have to create your own key and certificate.

In this app, we require you to put all the bundles into a directory, and put your key and certificate into each bundle. You may need to split them into mulitiple environments. For example, in endoflife, we split ITE into ITE-uat and ITE-testing, each with its own key and certificate files. The directory layout is as follows:

    bundles
    ├── MTS
    ├── ITE-uat
    ├── ITE-testing
    └── PRD

Create key and cert for ITE and PRD

To generate certificates for ITE and PRD, you will need to go through a checklist with the Department of Internal affairs. Part of this is using OpenSSL to generate a private key and CSR:

STAGE=ite  # or prod
DOMAIN=$STAGE.sa.saml.sig.mysite.mydomain.nz;
PK_FILE="$DOMAIN.private.key"
CSR_FILE="$DOMAIN.csr"
GPG_FILE="$PK_FILE.gpg"
openssl req -new -nodes -newkey rsa:2048 -keyout $PK_FILE -out $CSR_FILE \
    -subj "/C=NZ/O=Department of Internal Affairs/OU=Births, Deaths and Marriages/CN=$DOMAIN";

Then send the CSR to DIA for approval, and they will hopefully furnish you with a certificate.

More documentation about this process and the specification may be available here: https://see.govt.nz/realme/realme/Library/Forms/Library.aspx

Django settings

• Add realme and django.contrib.sessions to INSTALLED_APPS
• Add realme.backends.SamlBackend to AUTHENTICATION_BACKENDS
• Make sure django.contrib.sessions.middleware.SessionMiddleware is in MIDDLEWARE
• Set BUNDLES_ROOT to your bundles directory
• Set BUNDLE_NAME to one of FAKE, MTS, ITE, PRD as appropriate
• Adjust BUNDLES with settings to override realme.bundles.BUNDLES_DEFAULT

Refer to the supplied example/example/settings.py for examples.

The site_url in BUNDLES is optional, you can also set it with a global SITE_URL setting.

While loading the bundle configuration, the code will load realme.bundles.BUNDLES_DEFAULT first, and merge settings from settings.BUNDLES.

URLs

Set up the URLs as follows:

    from django.conf.urls import url, include
    urlpatterns = [
        ...
        url(r'^realme/', include('realme.urls', namespace='realme')),
        ...
    ]

Then you can use the RealMe URLs in templates:

    {% url 'realme:login' %}
    {% url 'realme:logout' %}
    {% url 'realme:acs' %}
    ...

For login, it defaults to low strength, but you can specify with:

    {% url 'realme:login' %}?strength=low
    {% url 'realme:login' %}?strength=moderate

Metadata

We provide two ways to generate metadata:

1. login to the site as admin and save the /realme/metadata URL as an XML file.
2. run the render_metadata Django management command.

For the MTS RealMe service, you can upload an XML file containing this metadata to the MTS site:

1. Navigate to https://mts.realme.govt.nz/logon-mts/metadataupdate
2. Select your XML file and click the "Upload" button.
3. In the next screen, click the "Import" button.

For ITE and PRD, you need access to https://see.govt.nz/realme/realme to upload the metadata. Once that is done you can notify the DIA team, and wait for them to apply it.

Seamless logon

This app has code for seamless logon but at this stage it is not fully verified.