Skip to end of metadata
Go to start of metadata

This page describes how to get the TIER Shibboleth IdP container running on a standalone system.

1. Getting Started

  • In this training, you’ll build a docker image on your assigned/claimed VM and run it in on your VM.
  • Docker is already installed on your VM(s).  If you are interested in how this simple step is done, see here for details: https://docs.docker.com/install/linux/docker-ce/centos/
  • You login to your VM using a username of shibboleth with a password of shibboleth (Windows: administrator/CheckWithMe!#!)
  • You may be able to use your laptop as a build machine! (note: in that case, you can only run it on your laptop since the docker repo referenced elsewhere in the training materials is only available to machines inside the training environment)

2. Get Needed Files

  • create and enter a new working directory for this course
    • mkdir ~/shib-train
    • cd ~/shib-train
  • download the needed files (in the form of a zipfile, retaining only needed parts of it):
    • curl -s -L -o shib_files.zip https://github.internet2.edu/docker/shib-idp/archive/3.4.0_181002.zip
    • unzip shib_files.zip
    • cd shib-idp-3.4.0_181002/
    • rm -rf bin container_files tests *file common.bash README.md test-compose/README.md
    • mv test-compose/* ..
    • cd ..
    • rm -rf shib-idp-3.4.0_181002/
    • rm -f shib_files.zip
  • This leaves you with 3 child directories in your current directory (plus 4 other files)
    • idp
      • This is the directory that we'll work in for learning about the IdP.
    • sp
      • This is the directory that we'll work in for learning about the SP.
    • data
      • This directory contains a test LDAP container with a good number of test users.  See this file for the users/data that populates this LDAP.

3. Build your initial config

  • The best bet for this class is to do everything under 'sudo' by creating a root shell (either 'sudo -i' or 'sudo /bin/bash')
  • Ensure we're in the right directory for our IdP container's config files:

    cd ~/shib-train/idp/container_files
  • Use the TIER ConfigBuilder microservice to download and build your initial config.  To do this, run this command (run this from the same new working directory created above):

    docker run -it -v $PWD:/output -e "BUILD_ENV=LINUX" tier/shibbidp_configbuilder_container
  • Info you’ll need for this service:
    • FQDN of your IdP (make something up, keeping in mind that your FQDN must be unique and include at least 3 parts. Example: bobsidp.myuniversity.edu)
    • Attribute scope value for your IdP (typically your main domain name from previous step, e.g. myuniversity.edu)
    • LDAP info - use the following 4 values verbatim (the password is just "password"):
      • LDAP URL ( ldap://data:389 )
      • LDAP Base DN ( ou=People,dc=internet2,dc=edu )
      • LDAP service account DN for the IdP ( cn=admin,dc=internet2,dc=edu )
      • Password for the above LDAP service account ( password )
    • Use of "secrets" (yes/no)    (answer 'No' unless you want to use secrets, in which case you must use also use a swarm deployment for this class - see here for the optional module on this topic).
  • Your config files will be added to the current directory in the following new child directory structures:
    • config
    • credentials
    • wwwroot
  • The ConfigBuilder service will also generate your Dockerfile and related dependent files in the current directory.
    • For this course, you can delete this Dockerfile as we'll just use the default one in the parent directory
      • rm -f Dockerfile
  • See the note at the bottom of this page for a full list of changes made to the default config by this service.


4. Make any needed config changes before building your image

  • Refer to the Configuration Section.  And, of course, you can always make changes later and rebuild your image (see section below entitled 'Making Configuration Changes')...

If you're just starting the training, it's safe to continue to the next step without making any changes, just to ensure its working. The default configuration will give you a working IdP, which you will need to change/customize and rebuild later as needed, so be sure to come back to this step!

  • At a minimum, you'll need to complete these additional configuration tasks:
    • Provide your new IdP's metadata to the classroom "federation"
    • Configure the classroom "federation" metadata as a trusted source of metadata
    • Configure your IdP to release information to the classroom test SP

  • Optionally, you can also configure:
    • Multi-factor authentication
    • Custom NameIDs


5. BUILD your image, RUN your container (using docker-compose)

The command below must be run from the working directory where the Dockerfile is located. It will use files from the various sub-directories created by the ConfigBuilder service.  This will take a few minutes.  Coffee anyone? 

cd ~/shib-train/idp/
./compose.sh


6. Monitoring

Check if the IdP is actually running and healthy

  • look at the output of 'docker ps' and look for status of 'healthy' (when initially starting the container, it will take about 3 minutes for status to change from "health: starting" to "healthy")
  • curl -k https://127.0.0.1/idp/status   (the status page, by default, is restricted to only 127.0.0.1 and will trigger 'access denied' from off-machine unless you modify your config to allow it)
    • You can run it from inside the container like this:
      • docker exec -i $(docker ps | grep _idp | cut -f 1 -d ' ')  curl -k https://127.0.0.1/idp/status

As we saw, 'docker ps' shows the actual container(s) running on a host. It is also useful to see the health status of the containers.

  • docker ps    (note the container ID)

To get a shell in one of your containers:

  • docker exec -it <containerID> bash

To see the IdP's logs:

  • docker logs <containerID>
  • docker-compose logs idp


Docker Swarm-related

List all services that are active in the swarm

  • docker service ls

List all nodes participating in the swarm

  • docker node ls

Show all details of the new service

  • docker service inspect shib-idp

Shows which nodes in the swarm are running each service

  • docker service ps shib-idp


7. Making configuration changes

  • Ensure that your are in the base 'idp' directory:
    • cd ~/shib-train/idp/
  • Update the appropriate config file(s) originally setup by the ConfigBuilder service. Most Shib-IdP config is in ‘container_files/config/shib-idp/conf’.
  • Next, stop and remove the old/running container(s):
    • ./decompose.sh
  • Finally, rebuild and re-run your containers using the latest/current config files:
    • ./compose.sh


8. Troubleshooting

  • View logs
    • docker logs <container ID>
    • docker-compose logs idp
  • Attach to a running container
    • docker exec -it <containerID> /bin/bash
      • IdP files are in /opt/shibboleth-idp/

9. Other useful docker commands

When docker fills up your hard drive:

  • docker system prune  (and optional '-fa' switch which clears everything)

Remove all secrets:

docker secret ls -q | while read -r line; do docker secret rm "$line"; done 


Remove all images:

docker image ls -q | while read line ; do docker rmi -f $line ; done

-or- docker rmi -f $(docker images -a -q)


Remove all containers:

docker container ls -a -q | while read line ; do docker rm $line ; done 


Remove all volumes:

docker volume rm $(docker volume ls -q)


                                                   If your container shows up as 'Healthy', then you are ready to proceed to Configuration >>


  • No labels

2 Comments

  1. The commands above are the same on Windows PowerShell/Docker, except for differences in command and line continuation.  Here's a Windows example:

     

    docker build --rm -t my/shibb-idp-tier --build-arg TOMCFG=${PWD}\config\tomcat `
    --build-arg TOMLOG=${PWD}\logs\tomcat `
    --build-arg TOMCERT=${PWD}\credentials\tomcat `
    --build-arg TOMWWWROOT=${PWD}\wwwroot `
    --build-arg SHBCFG=${PWD}\config\shib-idp\conf `
    --build-arg SHBCREDS=${PWD}\credentials\shib-idp `
    --build-arg SHBVIEWS=${PWD}\config\shib-idp\views `
    --build-arg SHBEDWAPP=${PWD}\config\shib-idp\edit-webapp `
    --build-arg SHBMSGS=${PWD}\config\shib-idp\messages `
    --build-arg SHBMD=${PWD}\config\shib-idp\metadata `
    --build-arg SHBLOG=${PWD}\logs\shib-idp .

     

  2. Changes made to the default IdP configuration by the ConfigBuilder service.

    • Generates new signing and encryption keys/certs.
    • Generates new sealer key with randomly-generated password and configures that password in idp.properties
    • Consumes InCommon's metadata aggregate and verifies the signature on that aggregate in metadata-providers.xml.
    • Releases the default set of attributes to InCommon SPs and all international R&S SPs in attribute-filter.xml
    • Configures ldap URL, baseDN, service acct/pwd (supplied by you) in ldap.properties
    • Configures entityID, scope, and sealer key password in idp.properties
    • Per your consent, uncomments the relevant sections in your local Dockerfile for installing Java in your image
    • Makes a needed change to your local Dockerfile for a burned-in configuration
    • Removes all "secret" config files into a separate folder named 'SECRETS'.