Using TAP Shibboleth IdP Upstream Container

TL;DR

To get started with a new Trusted Access Platform Shibboleth IdP, here’s the quick path to get up and running (modify as desired):

  • Create a workspace:
  • mkdir newidp
  • cd newidp
  • Build a set of initial configuration files:
  • docker run -it -v $PWD:/output -e "BUILD_ENV=LINUX" tier/shibbidp_configbuilder_container
  • Answer a few questions about your IdP’s naming and your LDAP environment…
  • Build your container image:
  • docker build --no-cache -t my/shib-idp .
  • Launch a new container with your IdP:
  • docker run -d -p 443:443 my/shib-idp
  • If all went well, ‘docker ps’ should report “(healthy)” within a few minutes

****************************************************************************************************

More Info...

To use the TAP Shibboleth IdP container available on docker hub, just build your own container based from the upstream TAP container.  This is done by setting the correct “FROM” line in your Dockerfile like this:

FROM i2incommon/shib-idp:latest

However, to effectively deploy an IdP, you must supply a number of configuration files to the IdP.  This is done by changing the files inside the container that are seen by the IdP at run-time.  You can do this in 3 ways (primarily):

  1. COPY or ADD your specific config files into your IdP container’s local Dockerfile.  (the “burned-in” config)   This is the recommended approach.
  2. You can also mount the relevant directories containing your specific config files (external to your container) to the appropriate directories inside the container at run-time.  (the “mounted” config)  This creates run-time dependencies on your docker hosts in order for those files to always be available on any node where the IdP might be running.
  3. With recent versions of docker, you can use docker “secrets” to overlay the appropriate config files inside the container (also at run-time).  (this is a hybrid, burned-in approach with secrets)

For new deployments, you can get started with a curated TAP configuration by using the TAP Config Builder (do this from a new/blank directory - it will write the files you need, including a starting local Dockerfile, into the current directory):

        docker run -it -v $PWD:/output -e "BUILD_ENV=LINUX" tier/shibbidp_configbuilder_container

Inside the container, the Shibboleth IdP is at the default location: /opt/shibboleth-idp/ and Apache Tomcat is installed at /usr/local/tomcat.

At a minimum, the files inside the container that you should replace/overlay are:

In /opt/shibboleth-idp/conf/

  • idp.properties
  • ldap.properties
  • attribute-resolver.xml
  • attribute-filter.xml
  • relying-party.xml
  • metadata-providers.xml

In /opt/shibboleth-idp/credentials/

  • idp-signing.key
  • idp-signing.crt
  • idp-encryption.key
  • idp-encryption.crt
  • Sealer.key
  • The container will automatically rotate the sealer key daily
  • Add a property ‘idp.sealer._sync_hosts’ of space-delimited hostnames to your idp.properties to copy the new sealer key to other IdP nodes
  • sealer.kver

In /usr/local/tomcat/conf/

  • server.xml

Examples

For #1 above (in your Dockerfile):

ARG TOMCFG=config/tomcat

ARG TOMCERT=credentials/tomcat

ARG TOMWWWROOT=wwwroot

ARG SHBCFG=config/shib-idp/conf

ARG SHBCREDS=credentials/shib-idp

ARG SHBVIEWS=config/shib-idp/views

ARG SHBEDWAPP=config/shib-idp/edit-webapp

ARG SHBMSGS=config/shib-idp/messages

ARG SHBMD=config/shib-idp/metadata

ADD ${TOMCFG} /usr/local/tomcat/conf

ADD ${TOMCERT} /opt/certs

ADD ${TOMWWWROOT} /usr/local/tomcat/webapps/ROOT

ADD ${SHBCFG} /opt/shibboleth-idp/conf

ADD ${SHBCREDS} /opt/shibboleth-idp/credentials

ADD ${SHBVIEWS} /opt/shibboleth-idp/views

ADD ${SHBEDWAPP} /opt/shibboleth-idp/edit-webapp

ADD ${SHBMSGS} /opt/shibboleth-idp/messages

ADD ${SHBMD} /opt/shibboleth-idp/metadata

For #2 above (at run-time):

   docker run -d --name shib-idp -p 443:443 \

                      -v ${PWD}/config/tomcat:/usr/local/tomcat/conf \

                -v ${PWD}/wwwroot:/usr/local/tomcat/webapps/ROOT \

                -v ${PWD}/credentials/tomcat:/opt/certs \

                -v ${PWD}/config/shib-idp/conf:/opt/shibboleth-idp/conf \

                -v ${PWD}/credentials/shib-idp:/opt/shibboleth-idp/credentials \

                -v ${PWD}/config/shib-idp/views:/opt/shibboleth-idp/views \

                -v ${PWD}/config/shib-idp/edit-webapp:/opt/shibboleth-idp/edit-webapp \

                -v ${PWD}/config/shib-idp/messages:/opt/shibboleth-idp/messages \

                -v ${PWD}/config/shib-idp/metadata:/opt/shibboleth-idp/metadata \

                       my/shibb-idp-tier

For #3 above (snippet from a docker-compose file):

  secrets:
   - source: idp.properties
     target: shibidp_idp.properties

Sample Dockerfile for a “burned-in config” deployment:

FROM i2incommon/shib-idp:3.4.6_20191001       #(dev: i2incommon/shib-idp:latest)

COPY my-shib-config/conf /opt/shibboleth-idp/conf

COPY my-shib-config/credentials /opt/shibboleth-idp/credentials

COPY my-tomcat-config/conf /usr/local/tomcat/conf

# the Tomcat server.xml should point at the below file location inside the container

COPY my-tomcat-config/credentials/keystore.jks /some/path/inside/container/

Then, build your new IdP container like this:

  docker build --no-cache --rm -t my/tier-shibb-idp .

Run it like this:

  docker run -d -p 443:443 my/tier-shibb-idp

And test it like this:

  1. docker ps
  1. Look for the health status:

   STATUS

   Up 5 minutes (healthy)

  1. curl -k https://127.0.0.1/idp/status
  1. Look for the IdP’s status page

           ### Identity Provider Information

   idp_version: 3.4.6