OpenConext-biometric

SURFnet step-up biometric IdP

Getting started

System Requirements

• Java 8
• Maven 3

Building and running

This project uses Spring Boot and Maven. To run locally, type:

mvn spring-boot:run -Drun.jvmArguments="-Dspring.profiles.active=dev"

When developing, it's convenient to just execute the applications main-method, which is in Application.

Testing

There are Spring Boot integration tests and when you run the Application with the dev profile then you can test the GUI at http://localhost:8080. The dev profile ensures that you will be logged automatically using the MockSAMLAuthnFilter and the BioMetric API is mocked using the MockBioMetric.

The default behaviour is that 25 polls are made and the status will be completed. Use the browser developers tool to see the SAML message that is posted.

Metadata

The biometric IdP publishes its metadata.

Deployment

We use Ansible for the deployment. See the inline documentation of application.properties for all the environment dependend variables. The Ansible files are located in the ansible folder.

Install Ansible

To install Ansible (version must be >= 2.0) for deployment of the Biometric IdP:

brew install python
pip install --upgrade setuptools
pip install --upgrade pip
brew linkapps
brew install ansible
pip install python-keyczar==0.71c

This playbook uses a custom vault, defined in filter_plugins/custom_plugins.py in order to encrypt data.

Retrieve the surfconext-ansible-keystore from a colleague and put it on an encrypted disk partition, to keep it safe even in case of laptop-loss. Here's how to create an encrypted folder on your Mac.

This is how the keystore is created (you don't have to do this because it already exists for this project). See this blogpost for example.

keyczart create --location=$ENCRYPTED_VOLUME_HOME/surfconext-ansible-keystore --purpose=crypt

keyczart addkey --location=$ENCRYPTED_VOLUME_HOME/surfconext-ansible-keystore --status=primary

Create the symlink so that our playbook can find the AES key on your encrypted volume:

ln -s $ENCRYPTED_VOLUME_HOME/surfconext-ansible-keystore ~/.surfconext-ansible-keystore

Structure

The main playbook is biometric.yml. Its inventories are kept in the ansible folder (e.g. test).

How to deploy

You can use the standard ansible-playbook command with optional tags to limit the deployment time.

ansible-playbook -i test -K biometric.yml --tags "biometric" -u centos

Replace the -i variable with the environment where you want to deploy to and change centos to your username on the environment.

Private signing keys and public certificates

The OpenSaml library needs a private DSA key to sign the SAML request and the public certificates from the Strong Authentication Service Provider (SA SP). The public certificate of the SA SP can be copied from the metadata.

The private / public key for the Biometric IdP can be generated:

openssl req -subj '/O=Organization, CN=biometric/' -newkey rsa:2048 -new -x509 -days 3652 -nodes -out biometric.crt -keyout biometric.pem

The Java KeyStore expects a pkcs8 DER format for RSA private keys so we have to re-format that key:

openssl pkcs8 -nocrypt  -in biometric.pem -topk8 -out biometric.der

Remove the whitespace, heading and footer from the biometric.crt and biometric.der:

cat biometric.der |head -n -1 |tail -n +2 | tr -d '\n'; echo
cat biometric.crt |head -n -1 |tail -n +2 | tr -d '\n'; echo

Above commands work on linux distributions. On mac you can issue the same command with ghead after you install coreutils:

brew install coreutils

cat biometric.der |ghead -n -1 |tail -n +2 | tr -d '\n'; echo
cat biometric.crt |ghead -n -1 |tail -n +2 | tr -d '\n'; echo

Add the Biometric key pair to the application.properties file:

biometric.private.key=${output from cleaning the der file}
biometric.public.certificate=${output from cleaning the crt file}

Add the SA SP certificate to the application.properties file:

sa.public.certificate=${copy & paste from the metadata}