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.
This document is not expected to be used by ordinary users. It has a slightly higher level of technical content, but everything is explained and it requires no special background. You must be an administrator of your own desktop test computer.
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.
...
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 that does all the actual communication.
So the only thing you need to change is the Browser on the client desktop that translates that name into a network address of a particular computer that runs Shibboleth., although to make this particular change it is best to change a system file on the computer on which the Browser is running.
But is it Shibboleth?
When a Browser goes to any "https://" URL, the server at the other end has to have a Certificate and key Key that proves that it is the server computer 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 Key that proves the message comes from "Production Shibboleth at Yale University" and has not been altered since it was generated. Again, these files the Certificate/Key files in Shibboleth itself 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 All applications will trust 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 Shibboleth to be real Yale Shibboleth. The signature even says that it comes from the computer named "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, which is true from the point of view that this name is shared by both Pre-Production and Production. The two machines have different network addresses.
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 Every computer when it connects to a network is automatically configured to talk to a "name server" (belonging to Yale or to your Internet Service Provider) that translates names to addresses. It is possible, but is regarded as a really dumb thing to do, to use IP addresses directly for your browsing and other network activity. ITS staff reserves the right to move stuff servers around on campus and that may change the network address. The name doesn't Only the server name is expected not to change.
Today (and this although it 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, so if you are about to test again after a long time has passed, check back here to make sure the address has not changedfor the current address. Because both Pre-Production and Production Shibboleth have the same name, and because the name servers point to Production, we can only keep track of the Pre-Production address by writing it down.
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 non-comment line has starts with an IP address and then has 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 before your system goes to the name servers. Once you change the file, the new contents take effect immediately.
...
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, so using any other address here will not work.
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.
...
- Copy the test "hosts" file to the "etc" directory. To make sure it is working, issue the command "ping auth.login yale.edu" and verify that the address being used is 128.36.64.90.
- Login to your application using the browser. If it works, the test is successful.
- Copy the original saved file to the "etc" directory.
There is no direct
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.
...
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 When we have the time, we will set up a Proxy Server and then you can test Shibboleth using a change to the Browser configuration instead of a change to the operating system.However, changing hosts file. Doing this is actually a bit more complicated, but because of the bad association of hosts file changes and malware, some people today may feel better about this change.
We have not yet set up the proxy.
Changing the hosts file is simple and easy to do and trivial to understand.