Testing Your Application before a Shibboleth Change

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. 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 that does all the actual communication.

So the only thing you need to do is to configure the Browser on a desktop machine that "auth.yale.edu" is the name of the Pre-Production server instead of the name of the Production server. You do not need to change any of the servers or applications, just the client desktop.

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 that proves that it is the 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 that proves the message comes from "Production Shibboleth at Yale University" and has not been altered since it was generated. Again, 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.

All applications will trust Pre-Production Shibboleth to be real Yale Shibboleth. The signature even says that it comes from the computer named "auth.yale.edu", 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". 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 servers around on campus and that may change the network address. Only the server name is expected not to change.

Today (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 if you are about to test again after a long time has passed, check back here for 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 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.

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, 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.

To test your application you

1. Copy the test "hosts" file to the "etc" directory. To make sure it is working, issue the command "ping auth.yale.edu" and verify that the address being used is 128.36.64.90.
2. Launch a "Private Browser Window" so you have no existing session with CAS, Shib, or your application.
3. Login to your application. If it works, the test is successful.
4. Copy the original saved file to the "etc" directory.

If the login is not successful, then send mail with the URL you used to do the login, the netid you used, and contact information to Howard.Gilbert@yale.edu.

What happens if you do not restore the original copy of the file? It is possible to run for weeks using the Pre-Production version of Shibboleth and everything will work. Unfortunately, there are a few other Yale services that can appear to be running on the same server name. A few applications have obsolete references to CAS as https://auth.yale.edu/cas/login. This isn't an actual version of CAS, but a small program that sends the user to the correct server name. These other minor functions nominally on auth.yale.edu are not simulated by the Pre-Production Shibboleth server address. So if you leave the hosts file pointing to the test address and happen to follow a link to one of these old URLs, then you will get a Not Found error message.

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.

Then 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. 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 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.

We have also set up a Windows VM in the "SpinUp" test environment that always has the modified hosts file. If for some reason you do not want to make the hosts change on your computer, you can request that your Netid be added to the users who can login to that computer, and then you can perform the test through the Remote Desktop session.

Generally speaking, it is not possible to change the hosts file on a normal (non "rooted") Android computer, so you cannot test from a phone or tablet.

Changing the hosts file is simple and easy to understand.