If you are the owner or administrator of an application that uses Yale Shibboleth for user logins, and a Shibboleth change or update is scheduled, you can test your application after the Shibboleth changes have been moved to Pre-Production and before the Shibboleth change moves to final Production. This document explains how to do it.
The process is fairly simple, but it involves making a temporary administrative change to a laptop or desktop computer under your control. You add one line to a system file, test, and then restore the original version of the file. It doesn't matter what computer you use, so if you don't like doing this on your important machine, find something that boots up at all and run the test there.
What about TEST?
There is a TEST version of Shibboleth on the network at "https://auth-test.yale.edu/idp". If you have a TEST version of your application, you can configure it to use TEST Shibboleth and then your problem is solved. Just login through the TEST environment.
However, in 99% of real world cases most people have only the one production version of their application, and they cannot easily switch it back a forth between "auth.yale.edu" and "auth-test.yale.edu". Fortunately, you do not need to change the application and you do not need to change the network. You just need to change one browser on one desktop computer.
Its all About the Browser
All applications that use Shibboleth know the URL of the Shibboleth server. However, they do not communicate directly over the network to Shibboleth. Instead, they send the URL of the Shibboleth server to the client Browser and tell the Browser to talk to Shibboleth and get a message addressed to the application containing information about the current logged in user. The Browser talks to the application, to Shibboleth, to CAS, and back to the application again. So while the application may know the name "auth.yale.edu" and Shibboleth may know the URL of the application, it is the Browser on the client desktop that translates that name into a network address of a particular computer that runs Shibboleth.
When a Browser goes to any "https://" URL, the server at the other end has to have a Certificate and key that proves that it is the server with the name the Browser expected to talk to. The Certificate and key of Yale servers are protected by ITS, but we can install the same files on two different network addresses as long as we control both of them and they do the same thing.
When Shibboleth is done, it generates a message specifically targeted to a particular application, and it digitally "signs" the message with a second Certificate and key that proves the message comes from "Production Shibboleth at Yale University". Again, these files are controlled by ITS and we can install them on a second machine.
The "auth.yale.edu" name is publicly associated with servers that are carefully controlled and change only after the changes are thoroughly tested. It may take weeks for a change to go all the way to Production, so to make testing possible there is a Pre-Production server that we can change in a matter of minutes that contains the same code, configuration, and Certificate/key files as Production. That server runs what we will be putting into production as soon as it is fully tested.
The Pre-Production server has its own name, but unfortunately the way that Shibboleth works, having a server with a different name is not useful. The application knows the URL for "auth.yale.edu" and tells the Browser to go to that name and no other.
So the problem is to reroute requests on the client desktop computer where the Browser is running, so that when any URL references "auth.yale.edu" the request goes to the Pre-Production Shibboleth and not to the regular Production machine.
Names and Addresses (the Hosts file)
Users reference servers by their name, but the actual communication uses a numeric "IP Address". A "Name Server" translates a name like "auth.yale.edu" to a particular IP address, and then the data is sent to that address. It is generally regarded as a bad practice to use IP addresses directly, because ITS staff reserves the right to move stuff around on campus and that may change the address. The name doesn't change.
Today (and this may change in the future) the IP address of Production Shibboleth is "130.132.35.36". You can verify this on your computer by using the command "nslookup auth.yale.edu" on Windows, Mac, or Linux computers.
Today (and this may change more quickly than the production address) the Pre-Production Shibboleth address is 128.36.64.90, and for this machine even the name may change. So the only place you will find this address is in this document. So before you do any testing, check back here to make sure the address has not changed.
There is a "hosts" file on every computer since the beginning of the Internet. On windows it is "c:\Windows\system32\drivers\etc\hosts" and on Mac and Linux systems it is /etc/hosts. Every line in that file that begins with "#" is a comment. On Windows the default supplied file is all comments, and in Mac/Linux the default file contains one or two lines. Each line has an IP address and one or more names that are associated with that address. This file is searched first for every network name any of your applications talk to. Once you change the file, the new contents take effect immediately.
So the testing trick is to add one line to the hosts file on the client desktop temporarily. The line reads:
128.36.64.90 auth.yale.edu
Then whenever a program (the Browser) looks for the name "auth.yale.edu" it goes to address "128.36.64.90" (the address of the pre-production VM for Shibboleth) instead of "130.132.35.36".
You cannot meaningfully point this name to any other address. For one thing, the server responding to this address has the Yale Certificate and private key for that host name, so the only two addresses you can point your browser to with "https://auth.yale.edu" and connect without a big nasty security message from the browser are 128.36.64.90 and 130.132.35.36 because the network accepts that both these addresses have the "auth.yale.edu" name. As a second check, both servers run the same configuration of production Shibboleth and both generate digital signatures using identical copies of a second protected secret digital key file. Without the signature, no application will believe the message comes from Shibboleth. So this technique can only be used to switch a computer temporarily from the "production" Shibboleth server to the "pre-production" version of the server.
To test your application you
- save the old hosts file
- make this one line change to the "hosts" file
- login to your application using the browser. If it works, the test is sucessful.
- restore the original copy of the file.
Security
A number of malware programs try to modify the hosts file. They want to trap all your Browser requests and send them to some bad server somewhere. So this file is moderately protected. In Windows, for example, you need to be an administrator to change the file and you have to give an administrative OK. Generally you cannot edit the file directly. Make a copy of it to another directory. Then create a second copy with the one line change. If you drag and drop the modified file to the original directory, you will be asked if you want to replace the old file and then be asked for administrative approval of the change. You repeat this sequence to replace the temporary modified copy with the saved original file.
What happens if you do not restore the original copy of the file? The pre-production version of Shibboleth is protected by the same security as production Shibboleth. It is just changed more easily and quickly. Unfortunately, there are a few other applications that you can access that appear to be on the "auth.yale.edu" server, but only Shibboleth (that is "https://auth.yale.edu/idp") is supported by the test machine at 128.36.64.90. So if you forget, and a few days later you accidentially try to access "https://auth.yale.edu/somethingelse" then that will fail. So generally it is a good idea to run one quick test and put things back to normal.
Is There Another Way to Do This?
All Browsers have an Advanced section of their Options where under Network you can configure a Proxy Server. A Proxy Server will be created that points the "auth.yale.edu" name to the pre-production address. This does essentially the same thing, but uses only a temporary change to the Browser configuration instead of a change to the operating system.