...
Only one program can use port 8080 on your computer at a time. When you test Shibboleth on your local Sandbox, it also uses 8080. Using the same local port number for both the Sandbox and the SSH tunnel will generate an error message if you accidentally run both at the same time. SSH will generate error messages that it cannot create the tunnel if you have forgotten to shut down the Sandbox Tomcat, and Tomcat will generate error messages that it cannot bind to the port if you forget forget to shut down SSH before starting the Sandbox. This is a feature, because you really don't want to spend hours trying to figure out what is wrong only to discover that you are debugging the wrong Shibboleth server.
Browser Point of View
We have already explained that all communication between Shibboleth and the application goes through the Browser. That means that the Browser has to find the Shibboleth server, and it has to find the Application. What is not clear is that some parts of Shibboleth have to be configured from the "Browser" point of view.
Suppose Shibboleth is running on a VM named vm-something-01.its.yale.internal. That name, and the local IP address, are restricted to the machine room. The F5 knows how to get to that hostname, but ordinary desktop computers cannot reach it.
The F5 creates a public virtual hostname with an IP address everyone can use. It is the F5 that has the name "auth.yale.edu" or "auth-test.yale.edu". So in normal processing, all traffic to Shibboleth goes through the F5.
The missing piece here is that nothing configured to Linux or Tomcat on the "vm-something-01" host computer will tell it what name the F5 happens to be presenting to the world. There is no way for the machine to know that everyone else in the world thinks it is "auth-test.yale.edu" unless you configure that name using the install-TEST.properties file in the Jenkins Install. If you look at that file, you might be misled because the first couple of lines read:
idp.entityID= https://auth-test.yale.edu/idp/shibboleth
idp.metadata.file=auth-test.yale.edu-metadata.xml
Yes these lines include the "auth-test.yale.edu" name, but neither of them is configured to anything Shibboleth regards as a URL or network address. The "entityID" is just a string that happens by Yale convention to also be a URL, but it could have been anything. the second the name of a file on disk that happens to start with the public hostname. There is only one property that is actually a network address of the server VM:
cas.target.url=https://auth-test.yale.edu
This is the Yale property that is used to set a parameter of the Unicon CAS-Shibboleth integration that in turn sets the Service string sent to CAS. CAS will Redirect the Browser to the URL in this string, so it must be a URL that the Browser can use to get back to the same Shibboleth VM ending up at the same Tomcat port that received the request that started the CAS login.
It may seem strange that all the Applications in the world have been given a Metadata file that contains URLs that contain public URLs for Shibboleth, but Shibboleth itself has no way to find its own public URL in any configuration parameter. The reason why it can get along without that information is that Shibboleth never does anything except in response to a network request, and when any request comes in over the network it contains an HTTP Host header. A Host header may be originally generated by the Browser, and it may be modified by the F5 on its way to the VM. The Host header contains the protocol, server DNS name, and the port (from the point of view of the Client who sent it). So the Browser generates a header of the form
Host: https://auth.yale.eduThis can flow through the F5 and arrive at the VM and be passed on to Tomcat and to Shibboleth. It tells Shibboleth a subset of the URL that the Browser started with before the F5 changed the protocol, and the VM name, and the port number, to send the request through possibly more intermediaries before it gets to Shibboleth. Sometimes Shibboleth needs to Redirect the Browser to another URL on its own server. It can use the Host header to send back the right network address, so the Browser will come back to Shibboleth again through the same path.
You need to be aware of the "cas.target.url" property and the way that the Host header is used, because during testing the Browser may start with a request to "https://auth.yale.edu" but you may trap it and send it to a special IP address or even a different host name. Neither of these is necessarily a problem, but if as a result you change the Host header then certain specific Shibboleth functions may break.
Typically if you get to the right Shibboleth test server in the first place, then all the Redirects will go back to the right machine. A configuration/test problem typically shows up if you try to change ports or protocol (http or https). So if the original URL was "https://auth.yale.edu/idp" and you try to test against "http://localhost:8080/idp" then problems with configuration or Host header mapping will show up when your Browser generates an error page and the address bar shows "https://auth.yale.edu:8080/idp" or "http://localhost:8080:8080/idp".
Configure Redirector
Redirector runs inside your Browser. Every time the Browser is about to go to a network URL, Redirector inspects it. If the destination URL matches a pattern, Redirector replaces the string with a different string. This is essentially the same as the Find and Replace function of every Text editor. You can match text with either a Wildcard or Regular Expression. Wildcard is simpler and is perfectly adequate for Shibboleth testing.
...