Shibboleth SP docker image

A Shibboleth configuration running apache httpd and shibd in a container, featuring:

Image is based on centos7
The (optional) express configuration uses a single YAML file to setup a shibboleth SP.
The container is executed with reduced kernel capabilities after completing the setup.

Prepare the repository

git clone https://github.com/identinetics/d-shibsp.git
cd d-shibsp
git submodule update --init

Build the docker image

cp dc.yaml.default docker-compose.yaml
cp dc-setup.yaml.default dc-setup.yaml  # provides default capabilties during setup
export MANIFEST_SCOPE='local'
export PROJ_HOME='.'
./dcshell/build

Initialize the container’s persistent volumes

First, start the container with a shell and without restrcihted capabilties. For this copy docker-compose.yaml to dc-setup.yaml and remove the cap_drop key. This will initialize the docker volumes without starting the services.

docker-compose -f dc-setup.yaml run --rm shibsp bash

Now the container is initialized, but does not have a complete httpd and shibboleth configuration.

Basic configuration

Standard configuration

Using /etc/httpd/*.orig and etc/shibboleth/shibboleth2.xml.dist follow a standard config procdeure. There are several good guides for a general Shibboleth SP available, such as on shibboleth.net or switch.ch.

Express configuration

As an alternative this repository includes an express configuration for the SP. By editing express_setup.yaml the basic httpd+shibd configuration can be controlled from a single place. The setup can be run only once after creating persistent docker volumes. Manual editing afterwards is possible. To prepare the express setup, make an edited copy of /opt/install/config/express_setup.yaml in /opt/etc/. This is a persistent volume and can be used to repeat the express configuration. Then run:

export PYTHONWARNINGS="ignore" # ignore YAMlload issue
/opt/install/scripts/express_setup.sh -a -c express_setup.yaml

Keys and metadata can be generated again with options -k, -K and -s.

Shibboleth SP further configuration

Check/modify the config files in /etc/shibboleth according to the documentation, in particular:

register /etc/shibboleth/export/sp_metadata.xml at the federation resource registry
copy the metadata signing key to /etc/shibboleth/metadata_crt.pem
attribute-map.xml and attribute-policy.xml (e.g. if Profile is set to 'default')

Start the container in operational mode

docker-compose [-p <zone>] [-f config] up -d           # start container in daemon mode

To avoid "Found orphan containers" warnings from docker-compose a project/op-zone (such as qa, pr) may be specified. It as no practical effect except suppressing the warning message.

Duplicating/migrating an existing configuration

An existing configuration might be duplicated on the same or migrated to another node.

copy conf.sh (or confXX.sh to confYY.sh on the same node)
edit conf.sh and set the IMGID and PROJSHORT
dscripts/build.sh (this will also create the docker volumes)
the default path for the volumes is $DOCKER_VOLUME_ROOT/$CONTAINERNAME, here in short VOLROOT
copy the contents of the docker volumes from the existing instance
edit VOLROOT/.etc_httpd_conf/httpd.conf and correct the user
set servername, docroot and logfile path in VOLROOT/.etc_httpd_conf.d/vhost.conf
Adapt shibboleth2.xml, attribute-map.xml and attribute-policy.xml in VOLROOT.etc_shibboleth/

create a new sp key and metadata:

`docker-compose -f dc-setup.yaml run --rm shibsp bash  # start container in interactive mode`
`cd /etc/shibboleth; ./keygen.sh -f`
`chown shibd-user sp-*`
`metagen.sh`

edit metadata and submit it to the metadata feed
copy the metadata signing key to VOLROOT.etc_shibboleth/metadata_crt.pem (as defined in shibboleth2.xml)
edit static contents in VOLROOT.var_www
Besides the SP configuration the load balancer, TLS-certificate and DNS-name need to be configured

Testing and Debugging HTTPS Proxy configurations

The proxy must send x-forwarded headers: HTTP_X_FORWARDED_HOST sp.example.org HTTP_X_FORWARDED_PROTO https HTTP_X_FORWARDED_PORT 443 (optional) HTTP_X_FORWARDED_FOR <client-IP> (optional)

The vhost, when configured with "ServerName https://sp.example.org:443", will create the correct environment for mod_shib:

REQUEST_SCHEME https SERVER_NAME sp.example.org SERVER_PORT 443

Check if the request is directed to the vHost, e.g. by checking the access log.

Sample request to test without proxy:

curl -v -H 'HTTP_X_FORWARDED_HOST: www.example.org' -H 'HTTP_X_FORWARDED_PROTO: 443' http://localhost:8080/test.php

Logging

The default configuration comprises following logfile locations and the respective config files:

Output location	Configuration
/var/log/httpd/error.log	/etc/httpd/conf/httpd.conf
/var/log/httpd/vhost_access.log	/etc/httpd/conf/httpd.conf
/var/log/httpd/error.log	/etc/httpd/conf/httpd.conf
/var/log/shibboleth-www/native.log	/etc/shibboleth/native.logger
/var/log/shibboleth-www/native_warn.log	/etc/shibboleth/native.logger
/var/log/shibboleth/shibd.log	/etc/shibboleth/shibd.logger
/var/log/shibboleth/shibd_warn.log	/etc/shibboleth/shibd.logger
/var/log/shibboleth/signature.log	/etc/shibboleth/shibd.logger
/var/log/shibboleth/transaction.log	/etc/shibboleth/shibd.logger

Note: Not all files are being used in the default configuration.

By default, shibboleth rotates log files, but apache does not. To have a consistent logfile rotation you may want to use the logrotate utility for both shibd and httpd.

To disable log rotatation in shibd change each log4j.appender in native.logger and shibd.logger from RollingFileAppender to FileAppender, like this (6 log files):

#log4j.appender.shibd_log=org.apache.log4j.RollingFileAppender #log4j.appender.shibd_log.maxFileSize=10000000 #log4j.appender.shibd_log.maxBackupIndex=10 log4j.appender.shibd_log=org.apache.log4j.FileAppender log4j.appender.shibd_log.fileName=/var/log/shibboleth/shibd.log

Logrotation is executed with /opt/bin/logrotate.sh. It needs to be started from some cron-like service on the docker host, such as:

docker.compose [-f config] exec <service> /opt/bin/rotate_logs.sh [-v] # <service> is 'shibsp' by default

Logrotation may be customized by editing /opt/etc/logrotate/logrotate.conf

identinetics / d-shibsp