Content Comparison

...

...

If you do an IdP Initiated login to an SP that doesn't allow them, it will reject the SAML Response and you won't actually login. However, the digital signature was also probably invalid (not from production) and there may be a lot of other defects, and you probably were not planning to go all the way to a successful login at this stage anyway. You can still capture and check the Response for content.

It is not possible to test SP Initiated Login

...

Some Service Providers present a login page for users. The user has to press a big button to "Login with a Netid" or "Login from Yale", or maybe they have to select "Yale University" from a long pulldown list of schools. Then the SP sends the Browser to "https://auth.yale.edu/idp/...".

This is only important if you are really going to login to the application for final testing. Before that, use the IdP Initiated format to generate a SAML Response and manually check its content to verify that Shibboleth seems to be generating the right Subject and Attributes. So you only use SP Initiated Login for final testing after that preliminary test has completed.

You will, of course, need a list of the login pages for the applications you want to test. Go to "yale.service-now.com", "yale.box.com", "mail.bulldogs.yale.edu", or the "www.yale.edu/iptv" to get started.

There are two ways an application can send its Request to Shibboleth:

(SAML Browser POST Protocol) writes a Form to the screen containing a pre-loaded text box containing the SAML Request, then uses JavaScript to Submit the data to https://auth.yale.edu/idp/profile/SAML2/POST/SSO
(SAML Browser Redirect Protocol) redirects the Browser to "https://auth.yale.edu/idp/profile/SAML2/Redirect/SSO?SAMLRequest=" followed by the character encoded SAML Request

So, the first thing that happens in a SP Initiated login is your Browser generates a POST or GET operation to "https://auth.yale.edu/idp..." and unless you trap this URL and send it to a different location then this operation will go to the Production Shibboleth server.

If you do trap the request and send it to a test Shibboleth server, then you have a second set of problems. Shibboleth implements a set of SAML standard checks to make sure that messages have been delivered to the right server. So generally the test Shibboleth has to actually believe that it is running on a machine named "auth.yale.edu" and that it is running https on the default port.

Network Routing

In all cases, communication to Shibboleth goes through your Browser.

The user clicks on a link sending the Browser to the Shibboleth IdP Initiated URL
The Application sends a Redirect to the Browser, and the Browser does a GET to the Shibboleth URL
The Application writes a form and JavaScript on the Browser submits the form to Shibboleth URL.

So, if you are testing "https://auth.yale.edu" then the only thing you need to do is to convince Firefox running on your computer that "auth.yale.edu" is some specific network location. It can be 127.0.0.1 ("localhost") or 130.132.35.35. The question, then, is how to get your Firefox to translate that name to an IP address of your choosing.

The trivial solution is that in the IdP Initiated login you type the IP address or real hostname of the test Shibboleth server in the URL because you control it.
Another simple solution is to change your /etc/hosts or \windows\system32\drivers\etc\hosts file to map "auth.yale.edu" to some IP address you choose. Just remember to change it back when you are done testing.
You can install a Browser plugin ("Redirector") that matches URL patterns and then rewrites them. It can match "https://auth.yale.edu/idp/*" (note the wildcard at the end) and replace it with "http://localhost:8080/idp/$1" (where $1 is a variable that inserts the rest of the original URL after the matched string).
You can reroute the URL outside the Browser using a Proxy. Charles Web Debugging Proxy is easy to use and setup, while nginx is widely used and very powerful, but requires more reading because there is so much it can do.

Adding an entry in the hosts table is simple, but all it changes is the IP address.

Redirector can be configured to change both the host name and the protocol (replacing "https" with "http") and the port number. This adds a lot of flexibility to the testing, but the URL you generate gets sent on to Shibboleth and that can cause trouble later on where Shibboleth is trying to compare its own network URL with the URL in the Request the application sent, and because Redirect changed one but not the other they do not match. That will be discussed next.

The Proxy is the most complicated configuration, but Proxies exist everywhere and so Shibboleth and Tomcat expect them to be there and have configuration parameters to take care of the problem. In production at Yale there is always the F5 proxy between the Browse and production Shibboleth, so you can certainly get away with adding a proxy between your Browser and a test Shibboleth.

Preparation

Get Firefox. You can can certainly use other Browsers in production, but Firefox is needed to test.

Firefox Add-Ons

SAML messages are typically BIN64 encoded and appear to be the contents of a Text Box in a form or else part of the query string. You can line up a set of tools to trace, cut, paste, decode, and format the XML, or you can install the Firefox SAML Trace add on, which does all of this work for you.

A lot of debugging can be done by using Shibboleth on your desktop (Sandbox) and setting a URL starting with http://localhost:8080/idp/..." in the Browser address bar. However, final testing may require access to the actual application using a normal login sequence. This may require the use of the PREPROD Shibboleth VM, because it has credentials (the signing key) identical to production Shibboleth and can produce a Response that the application will accept. PREPROD may have a public URL address through the F5, or it may have an internal URL that can be accessed from a desktop, or it may require that you SSH login to the host and tunnel port 8080 to your desktop. However that works, you need the Redirector Firefox plugin which watches for a particular URL pattern "https://auth.yale.edu/idp/*" and then substitutes a replacement for the original URL "http://localhost:8080/idp/$1" where $1 is replaced by the rest of the original URL (after the matched prefix).

If you click the Firefox Menu icon (three horizontal lines in the upper right corner of the toolbar) then Add-On is an option (which looks like a puzzle piece). Click it.

Go to the Add-Ons, Search for a new Add-On with the word "SAML". Install the SAML Tracer. Look for "Redirector" and install the Redirector Add On (it has a logo of a capital R ending in an arrow).

Now SAML Trace appears in the same menu, and Redirector installs an icon on the toolbar itself.

SAML Tracer requires no configuration. When you turn it on it traces Web activity in a new Window and will highlight, decode, and display the XML in a SAML Request or Response on demand. You turn it off by closing the Trace Window.

VM Access

If you run Shibboleth under Tomcat on your Sandbox desktop, then it is http://localhost:8080/idp. No setup is required.

If you run Shibboleth on the DEV/TEST/PREPROD VMs in the machine room and they have a public URL through the F5, then you can use that URL.

If they are new VMs not defined to the F5, then the firewall will not allow access from your desktop directly to the VM. First, you need to use the standard Cisco AnyConnect client to establish a VPN session to an area of the network from which SSH traffic is permitted to the VMs. You need to be put in an AD Group to use this type of VPN, and you have to download the Profile files for these special VPN targets. Get help from another developer if this is not set up on your machine or for your Netid. Access to the VPN requires MultiFactor Authentication even though your desktop is on campus.

When the VPN is enabled, you may have access to http port 80 and https port 443 using the native VM hostname (vm-something-01.its.yale.internal). That may be good enough for testing.

In other cases, you may need use an SSH tunnel for ports 8080 or 8443, but it is almost impossible to test or debug anything without SSH access to VMs and log files anyway. SSH requires that Operations create a login for your Netid on the VM and installed your SSH public key. In addition to the terminal session on the VM, the SSH client can be configured to "tunnel" one or more port number from your desktop computer to the VM. In the general case, tunnel ports 8080, 8443, and 443 to the same port numbers on the VM.

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

This 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"in this kind of preliminary testing configuration. Use IdP Initiated login to verify that the right attributes are being generated, and hold off SP Initiated testing until you get your code to Pre-Production.

Network Routing

When you are using IdP Initiated login, the only network routing problem is to make sure that the URL you use to send a request to the Shibboleth server matches the URL configured in the Shibboleth server for the CAS Service.

The CAS configuration is the "cas.target.url" parameter. When you run Shibboleth in the desktop Sandbox, it is convenient to set this property in the install.properties file you edit in your Install Project. However, if you are building new DEV and TEST server VMs in the machine room, this parameter will have been set by the install-DEV.properties or install-TEST.properties file.

So on the server you want to test, you might have:

Sandbox - cas.target.url=http://localhost:8080
TEST - cas.target.url=https://auth-test.yale.edu

What you need to do is to figure out how to run the test from your client machine using the same URL for the IdP Initiated login that was configured as the cas.target.url. In the Sandbox, all you have to do is use "http://localhost:8080" in both cases and you are done.

If you have a TEST configured VM that you are accessing through an SSH tunnel from your machine to the VM in the machine room, you have a problem. The tunnel makes the machine look like it is "localhost:8080" but the cas.target.url claims that it is https://auth-test.yale.edu.

So this document explains several tricks you can use to fix that.

Preparation

Get Firefox. You can can certainly use other Browsers in production, but Firefox is needed to test.

Firefox Add-Ons

SAML messages are typically BIN64 encoded and appear to be the contents of a Text Box in a form or else part of the query string. You can learn to manually locate and decode these strings, but the SAML Trace addon to Firefox does all the work for you.

If you click the Firefox Menu icon (three horizontal lines in the upper right corner of the toolbar) then Add-On is an option (which looks like a puzzle piece). Click it.

Go to the Add-Ons, Search for a new Add-On with the word "SAML". Install the SAML Tracer. Look for "Redirector" and install the Redirector Add On (it has a logo of a capital R ending in an arrow).

Now SAML Trace appears in the same menu, and Redirector installs an icon on the toolbar itself.

SAML Tracer requires no configuration. When you turn it on it traces Web activity in a new Window and will highlight, decode, and display the XML in a SAML Request or Response on demand. You turn it off by closing the Trace Window.

VM Access

If you run Shibboleth under Tomcat on your Sandbox desktop, then it is http://localhost:8080/idp. No setup is required.

If you run Shibboleth on the DEV/TEST/PREPROD VMs in the machine room and they have a public URL through the F5, then you can use that URL.

If they are new VMs not defined to the F5, then the firewall will not allow access from your desktop directly to the VM. First, you need to use the standard Cisco AnyConnect client to establish a VPN session to an area of the network from which SSH traffic is permitted to the VMs. You need to be put in an AD Group to use this type of VPN, and you have to download the Profile files for these special VPN targets. Get help from another developer if this is not set up on your machine or for your Netid. Access to the VPN requires MultiFactor Authentication even though your desktop is on campus.

When the VPN is enabled, you may have access to http port 80 and https port 443 using the native VM hostname (vm-something-01.its.yale.internal). That may be good enough for testing.

In other cases, you may need use an SSH tunnel for ports 8080 or 8443, but it is almost impossible to test or debug anything without SSH access to VMs and log files anyway. SSH requires that Operations create a login for your Netid on the VM and installed your SSH public key. In addition to the terminal session on the VM, the SSH client can be configured to "tunnel" one or more port number from your desktop computer to the VM. In the general case, tunnel ports 8080, 8443, and 443 to the same port numbers on the VM.

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.

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.

...

Version	Old Version 19	New Version Current
Changes made by	Howard Gilbert	Howard Gilbert
Saved on	Apr 15, 2016	Apr 15, 2016

Versions Compared

Key

Network Routing

Preparation

Firefox Add-Ons

VM Access

Browser Point of View

Network Routing

Preparation

Firefox Add-Ons

VM Access

Configure Redirector