Configuration

Configure the Application for Development or Production

Finally, create a file dissemin/settings/__init__.py with this content:

# Development settings
from .dev import *
# Production settings.
from .prod import *
# Pick only one.

For most of the settings we refer to the Django documentation.

Logs

Dissemin comes with a predefined log system. You can change the settings in dissemin/settings/common.py and change the default log level for production and development in the corresponding files. When using Dissemin from the shell with ./manage shell you can set the log level for console output as environment variable with:

export DISSEMIN_LOGLEVEL='YOUR_LOG_LEVEL'

When using in production make sure that apache collects all your log message. Alternatively you can send them to a separate file by changing log settings.

Sentry

Dissemin uses Sentry to monitor severe errors. To enable Sentry, set the SENTRY_DSN.

ORCID

You can either use production ORCID or its sandbox. The main difference is the registration process.

You are not forced to configure ORCID to work on Dissemin, just create a super user and use it!

Production

On your ORCID account got to Developer Tools and register an API key. As a redirection URL you give the URL to your installation.

Set ORCID_BASE_DOMAIN to orcid.org in the Dissemin settings.

On the admin surface got to Social Authentication, set the provider to orcid.org and enter the required data.

Now you can authenticate with ORCID.

Sandbox

Create an account on Sandbox ORCID.

Go to Developer Tools, verify your mail using Mailinator <mailinator.com>. You must not choose a different provider.

Set up a redirection URI to be localhost:8080 (supposed to be where your Dissemin instance server is running).

Now proceed as in Production, but with sandbox.orcid.org.

Shibboleth

Shibboleth is a SAML based authentication mechanism and widely used in academic research. CAPSH has joined the UK federation in order to provide a login with eduGAIN. The main documentation is available at the UK federation.

Our entityID is https://sp.dissem.in/shibboleth and we will use this in the subsequent. This guide assumes that production and sandbox are running on the same machine and use the same entityID. In case of a separation, another entityID for sandbox should be required and some settings change.

Installation

Shibboleth requires mod_shibboleth and a daemon. Packages are available for RedHat and openSUSE. For Ubuntu and Debian based system, please follow the guide from SWITCHaai.

The certs and keys for signing and encryption might be missing. This can be self signed certificates. To generate them, run:

openssl req -config config-cert.conf -new -x509 -nodes -keyout sp-encrypt-key.pem -out sp-encrypt-cert.pem
openssl req -config config-cert.conf -new -x509 -nodes -keyout sp-signing-key.pem -out sp-signing-cert.pem

where the config file looks like:

[ req ]
default_bits = 4096
default_days = 1095 # 3 years
distinguished_name = req_distinguished_name
prompt = no
x509_extensions = req_ext

[ req_distinguished_name ]
C = FR
O = CAPSH
CN = dissem.in
emailAddress = team@dissem.in

[req_ext ]
subjectAltName = @alt_names

[ alt_names ]
DNS.1 = dissem.in
DNS.2 = sandbox.dissem.in
DNS.3 = https://sp.dissem.in/shibboleth # entityID production

Warning

When the certificate expires and we have to renew it, we have to tell the UK federation! For a short period of time we have to provide both certificates, so that the IdPs can update to the new one and the transition is seamless.

Note

In theory, we can use the same certificate as for the https server, but this is disadvantageous with Let’s Encrypt since with every new certificate, we would need to change our shibboleth metadata, requiring to contact the UK federation.

Then you can follow the UK federation guide.

Apache

In order to make Shibboleth available on the virtual host, add:

<Location /Shibboleth.sso>
    setHandler shib
</Location>

This way Shibboleth gets precedence over WSGI for /Shibboleth.sso. In theory, you could use any other alias, but this is somewhat of a standard.

Note

With this setup it is currently not possible to overwrite the discoveryURL, albeit this is stated in ContentSettings. The reason is some stale code, which is going to be fixed in SP v 3.1.0, see here.

The effect is, that calling Shibboleth.sso/Login on the sandbox redirects to the discovery service of production. This is a very rare scenario!

shibboleth2.xml

This is the central configuration file for Shibboleth where the magic happens. After a change of the configuration, touch the file, to tell the shibboleth deamon to reload. This does not disturb the service. Depending on the changes, the metadata for our entityId change. In this case, we need to inform the UK federation about our new metadata. This should no happen too often.

You can find our (sample) shibboleth2.xml als well as our attribute-map.xml in our GitHub repository. Check the folder provisioning.

Troubleshooting

Systemd timeout

Under certain circumstances shibd does take along time to start. This is due to the fact that we process the whole eduGAIN IdP metadata. The crucial time killer is the validation of signatures.

Usually this is only an issue when starting shibd for the first time, since cached IdPs won’t be validated again.

There are three ways to solve this:

  1. Increase timeout on systemd for shibd
  2. Stop shibd and initialize it manually
  3. Turn off validation.

Of course, 3. is not an option!

The standard approach to solve this is usually to use MDQ, where IdPs will be checked in case of need. This system is not (yet) suitable for a DiscoveryService since it needs to know all IdPs.