You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 17 Next »

Release notes for Release 2 Version 4.0

This release is the production test version  of a Docker containerized version of a Shibboleth IdP environment.  Unlike the previous test release, this version enables full access to the Shibboleth configuration environment and, once testing is complete, will be suitable for production use.  The virtual machine contains the tooling needed to build and manage Docker images with your campus configuration, run a pair of Docker Shibboleth images behind a load balancer, make configuration changes, and safely place new versions into production.

This documentation will be enhanced over the next couple of days.  Versions of the VM will be made available for environmets other than Virtual Box in the future.

A few words on VirtualBox

  • If you are not familiar with VirtualBox, you can read the documentation and download the software from Oracle's web site.
  • Once VirtualBox is installed and running, you import the .ova distribution image using the File / Import Appliance function.
  • The default network connection for the Shibboleth IdP packaged Virtual Machine is NAT. This will work well for the case of logging in and examing the VM and containers. To connect to services hosted by the VM from the outside and more easily interconnect with the TIER Testbed, you'll likely want to switch the network to bridged mode. Bridge Mode will provide the VM its own IP address from your network's DHCP server. Remember, if you are on a public network, the VM will be exposed to the world and we publish the password on this web site.  Note that Virtual Box bridge mode can not work with many wireless network adapters since the don't support promiscuous mode.  A wired network connection is generally better for use with Bridge Mode. Note that is possible to complete a test in NAT mode, but involves the inclusion of port numbers into the process.  This works e.g. https://127.0.0.1:8443 but remember that only one person can use a URL at a time in the tested. 
  • When you complete the process below, you will see a set of attributes supplied by your test Shibboleth IdP displayed by the testbed's Shibboleth SP.

Initial Testing Process

A quick test of the environment includes the following steps:

  1. Download the TIER-ShibIdP-R2-V4.ova file (or the most recent version) from the distribution site.
  2. Import the image into virtual box.
  3. Potentially change the network setting from NAT to Bridged - see above comments on VirtualBox.
  4. Potentially change the VM time synchronization setting from UTC to local.  Leave at UTC for use with MacOS and change to Local Time for Windows testing.
  5. Start the virtual machine.
  6. Login to the VM:
    1. LoginId: shibboleth
    2. password: shibboleth
  7. Note the IP address or FQDN of your VM.  You will need this information later.
    1. The standard Linux command: ip addr is available.
  8. cd work
  9. ./setup.sh
  10. ./build.sh
  11. Run: docker ps to verify that the system has started.
  12. Wait for a couple of minutes to give Shibboleth time to start.
  13. Obtain the metadata certificate
    1. Chrome formats the display better than Safari
    2. Browse to https://MY_DOMAIN_OR_IP/idp/shibboleth
    3. The second certificate in the displayed metadata is the one that you need.
  14. In a separate browser
    1. Browse to: https:// testbed.tier.internet2.edu
    2. select the option to Manage testbed metadata
    3. Login via your campus InCommon credentials
    4. Enter your MY_DOMAIN_OR_IP in the first box
    5. Copy and past the certificate from Step 10c above into the second box and press the submit button.
    6. Wait for 10 minutes
  15. While you are waiting, if you have not already created a tested identity, please create one now.
    1. https://testbed.tier.internet2.edu/secure/
    2. Select: Create a new person record
  16. After 10+ minutes have elapsed
    1. browse to https://sp.testbed.tier.internet2.edu
    2. Test your identity provider.

If you made a mistake somewhere

You most likely do not need to restart with a whole new VM.  Try the following commands first:

  • docker stop shib-idp
  • docker rm -f $(docker ps -a -q)
  • docker rmi -f $(docker images -q)
  • docker-compose up -d

The VM Environment

  1. Virtual Box Console Window
    The console window provided by Virtual box is not over friendly.  The VM accepts SSH on port 22 when the VirtualBox network adapter is configured for a Bridged Adapter and on port 2222 when the VirtualBox network adapter is configured for NAT.   You will find that a SSH connection with a decent terminal emulator is much easier to use.
  2. User Shibboleth does have sudo capability.
  3. User Shibboleth Home Directory
    The shibboleth user's home directory contains the build process and access to the limited configuration that is presently available.  The config directory tree enables you to provide a Kerberos keytab file, an ldap.properties file, and an attribute-reslver.xml configuration file. 
  4. Using Campus Authentication and Attributes
    The default configuration for the Identity Provider leverages the TIER Testbed for quick testing.  Sufficient configuration capability does exist in this release to use a campus LDAP and/or Kerberos for testing.
    1. Kerberos
      1. Provide your own keytab file and specify the proper KRB_FQDN value in docker-compose.yml
      2. You can disable Kerberos and enable LDAP authentication by leaving the value for KRB_FQDN= blank
    2. LDAP
      1. Provide an appropriate ldap.properties file
      2. For LDAP authentication, also be sure to blank the value for KRB_FQDN= in docker-compose.yml
  5. Debugging Problems
    This distribution is not set up well for accessing logs and viewing the running configuration.  See the section on useful docker commands next steps. It is also possible to mount the logs back on the VM but this and many other configuration for usability items are not in place at this time.

Some Useful Docker Commands

While the normal idea is that you should never need to look inside a container, this First Look release does not expose everything needed to debug issues.  These commands may be helpful.

  1. docker ps
    Shows the names and status of any running containers.
  2. docker exec
    Run  a command inside a running docker container.  You will find  docker exec -i -t shib-idp bash a handy command for debugging Shibboleth issues.  This command will open a root shell inside the container and map the output back to your VM session.  Inside the container you will find the familiar /opt/shibboleth-idp tree, including access to the configuration and logs. 
  3. docker start
    To start the IdP after rebooting the VM, run docker start shib-idp
  4. docker stop
    To stop the IdP, run docker stop shib-idp
  5. docker cp
    Used to copy files in to or out of a running container.  The syntax is similar to scp.  For example, to copy a logfile to the VM, run the command
    docker cp shib-idp:/opt/shibboleth-idp/logs/idp-process.log .


 

 

 

 

  • No labels