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

Compare with Current View Page History

« Previous Version 15 Next »

Release notes for version 1.0

This release is a First Look at a Docker containerized version of a Shibboleth IdP environment.  Please do not attempt use this in production.  Also, please do not expect to be able to access many of the configuration options that you normally need to change on a production IdP at this point in time.  This version is focused on the Docker containers and the VM to run them.  Future versions will include more of what is actually needed to use this environment in production.

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 .ovm 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-Shib-IdP-20160501.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. Start the virtual machine.
  5. Login to the VM:
    1. LoginId: shibboleth
    2. password: shibboleth
  6. Note the IP address or FQDN of your VM.  You will need this information later.
    1. The standard Linux command: ip addr is available.
  7. Edit the file: docker-compose.yml
    1. The simplest next step is to replace the two MY_DOMAN_OR_IP locations with the IP address of your virtual machine
    2. Save the file.
  8. Build and start the environment
    1. docker-compose up -d
    2. Wait for the process to complete and delay an additional 30 to 60 seconds for Shibboleth to start.
  9. Run: docker ps to verify that the system has started.
  10. 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.
  11. 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
  12. 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
  13. 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