...
The first thing the Application sees is a Form POST from your Browser to the ACS URL containing the SAML Response as data. This Response will have been generated and digitally signed by the Shibboleth you sent the IdP Initiated URL to in the first place. It could be auth, auth-test, auth-dev, or localhost:8080 in the Sandbox. If the Application has not been configured to trust the Shibboleth that generated the message, it will generate an error message and fail to log you The Application does not see the IP address or host name of the computer on which Shibboleth ran. The Response will contain the EntityId that was given to Shibboleth by the "idp.entityID= https://auth.yale.edu/idp/shibboleth", which is the first line in the install-XXX.properties file in the Jenkins Install project, but that is just a character string that does not need to have any physical relationship to the actual computer hostname. The EntityId will be used by the Application to find a configured Certificate to validate the digital signature on the Request.
Unless this computer has the actual credentials of PROD Shibboleth (which means that it is either PROD or PREPROD) then it cannot generate a legitimate signature. It will use whatever key it has, but the Application will find the signature faulty and will return an error page and not log the user on. However, if you have been tracing the HTTP messages in the Browser, you will have captured the SAML message sent to the application. You can display it and verify that the Attributes and Subject are correct for that particular Application, and that is 99% most of the testing you typically need to do.
SP Initiated Login
The user can start by going to the application. A Browser that starts with "yale.service-now.com", "yale.box.com", "mail.bulldogs.yale.edu", or the Comcast IPTV URL will in some cases get immediately sent to Shibboleth and in some cases will push a button or select Yale University from a dropdown list before being Redirected back to Shib.
Some applications that support SP Initiated also support IdP Initiated. You can test all the attributes and subject and the basic login using IdP Initiated, but when something changes that might affect it, you also have to be sure that when the Application sends a Request to Shibboleth then that Request is accepted.
There are two ways an application can send its Request to Shibboleth:
...
This means that you can certainly start with http://localhost:8080/idp/profile/SAML2/Unsolicited/SSO?providerId=nobody.yale.edu and run the test entirely on your Sandbox Tomcat on your desktop computer. The only trick is to make sure that all of the properties in the install.properties file are consistent with some Shibboleth (auth, auth-dev, auth-test, ...) except for the one property "cas.target.url=http://localhost" that is a real network address and has to send the Browser back to the same computer and same Shibboleth.
SP Initiated Login
The user can start by going to the application. A Browser that starts with "yale.service-now.com", "yale.box.com", "mail.bulldogs.yale.edu", or the Comcast IPTV URL will in some cases get immediately sent to Shibboleth and in some cases will push a button or select Yale University from a dropdown list before being Redirected back to Shib.
Some applications that support SP Initiated also support IdP Initiated. You can test all the attributes and subject and the basic login using IdP Initiated, but when something changes that might affect it, you also have to be sure that when the Application sends a Request to Shibboleth then that Request is accepted.
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 Procol) redirects the Brower to "https://auth.yale.edu/idp/profile/SAML2/Redirect/SSO?SAMLRequest=" followed by the character encoded SAML Request
The Browser (and therefore your computer) is always in the middle
So the three options are:
- The user click on a link sending the Browser to the Shibboleth 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 Submits it to Shibboleth URL.
Shibboleth always uses the Browser POST Protocol to send the Response back to the Application (it writes a Form to the screen containing a pre-loaded text box containing the SAML Request, then uses JavaScript to Submit the data to the AssertionConsumerService URL configured for that EntityId in the Metadata).
So both Shibboleth and the Application talk only to the Browser and the Browser forwards data between them. Therefore, the network address of the Application and the Shibboleth server are always determined by the Browser and the environment of the desktop system on which the Browser is located. There are many mechanisms you can use privately on your computer (or on a VM running on your computer if you don't want to mess up your real OS):
...
- /Redirect/SSO?SAMLRequest=" followed by the character encoded SAML Request
SP Initiated is slightly more complicated because the Application will have been configured with a specific Shibboleth URL which is almost always "https://auth.yale.edu/idp". It will have placed this URL in the Request XML, and it will have Redirected the Browser to that URL. So now you have two problems.
- You have to trap the "https://auth.yale.edu/idp" in the Browser and send it to the test instance of Shibboleth you are using.
- You have to convince Shibboleth that is really is the machine "auth.yale.edu" and that the request was received over "https" protocol.
There are many ways to accomplish these two things in testing. They should all be listed because there are a few things you can do on any machine and get 99% of your testing done, but the final end-to-end test of everything requires a PREPROD VM in the machine room and support from Operations.
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.
The four options have been listed in increasing order of complexity, but they do not include the minute by minute difficulty during testing of turning the test environment on and off. Because changing the hosts table is usually inconvenient and provides limited function, we typically do not use that approach but include it here for completeness.
...
- 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.
...