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".
These two addresses are the only computers in the world that have both the "https"//" Certificate/Key for the name "auth.yale.edu" and also the Certificate/Key to digitally sign messages in a way that other applications will trust that the message came from the Yale Shibboleth server.
Testing
It is generally a good idea to make two copies of the "hosts" file to two subdirectories, which I will call "saved" and "test" . Edit "test\hosts" to add the one line with "128.36.64.90 auth.yale.edu". To copy "test\hosts" to "C:\windows\system32\drivers\etc" (or to copy test/hosts to "/etc") you need administrative (or root) privileges. On Windows, simply copy and paste or drag and drop the file from test\hosts to C:\windows\system32\drivers\etc. First you will be asked if you want to replace the old file. Then you will be asked to approve the use of administrative privilege to change a system directory.
To test your application you
- Copy the test "hosts" file to the "etc" directory.
- login to your application using the browser. If it works, the test is successful.
- Copy the original saved file to the "etc" directory.
What happens if you do not restore the original copy of the file? 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 leave the test configuration, and then a few days later you use some application that was configured years ago to use a obscure alias of CAS as "https://auth.yale.edu/cas" then that CAS URL will not be found. So generally it is a good idea to run one quick test and put things back to normal.
Security
The hosts file has been in every system that uses the Internet. On Windows it goes back at least as far as the mid 1990's. What we are doing here was once very common.
Them malware came along, and today a lot of malware programs try, among other things, to change the hosts file. So this file is somewhat more carefully protected, and it is certainly regarded as evil for some program to try and change it behind your back. If you go to edit the file, and you did not make any intentional changes, and it is full of non-comment lines, then you may have been hacked.
So today we regard it as unfortunate that this test cannot be performed easily without changing the hosts file. Twenty years ago such a change would have been routine, but now because of the common association with malware, we try to leave the hosts file alone when possible.
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.
However, changing the hosts file is easy to do and trivial to understand.