Generally the Developer has little control over the setup of the Server and Network. Operations configures all of the network devices, the operating system, and even the Tomcat server. However, configuration problems can cause test failures, and the only way to fix these issues is to get the configuration fixed. Generally you only have to review this material when there is a major change to the network or server setup.
SAML Messages
The most important part of any Shibboleth login to an application occurs as it generates a "SAML Response" XML message and sends it to the Service Provider. The message contains a large amount of XML boiler plate and a very small amount of important content.
A lot of Shibboleth testing involves checking the SAML Response to make sure it has the right data for the Subject and for each supplied Attribute. This is determined by the configuration files for Shibboleth. It must find the EntityID of the Service Provider in a configured Metadata file, find the necessarily attributes released in the attribute-filter xml file, generate the SAML Response, and send it to the configured "ACS" URL in the Metadata. The Service Provider will accept the message if the EntityID and digital signature of the Shibboleth server match what it has been configured to expect.
However, Shibboleth passes data back to the Browser in response to something the Browser set to it, and the subsequent transmission of the Response from the Browser to the Service Provider is unrelated to the network configuration of the Shibboleth servers. There is almost nothing in this part of the transmission to configure or test.
IdP Initiated Login
An "IdP Initiated" test occurs when you click a URL that points to our Shibboleth server and provides the EntityID of one of our Service Provider partners:
http://localhost:8080/idp/profile/SAML2/Unsolicited/SSO?providerId=nobody.yale.edu
The hostname part ("localhost:8080") could reference a Sandbox test Shibboleth running on Tomcat on your desktop, or it This URL calls a Shibboleth server that could be running under Tomcat on the local desktop or could be a test version of Shibboleth running on a VM in the machine room where you have created an SSH tunnel connecting port 8080 on your desktop to the real Server port on the real Server VM.
At the end, after "providerId=" you add the EntityID of a partner. It is a Yale testing convention that the ID "nobody.yale.edu" is configured to release a very large number of attributes including most of the interesting ones you might want to check. It is the first test to make because is does so much it will point out most errors.
The Shibboleth code that processes an "Unsolicited/SSO" does not do any network validity checking. It doesn't care what the protocol (http or https), hostname, or port number are. However, during the processing it does Redirect the Browser to a different URL on the same Shibboleth server, and it order to do that it needs to figure out what its own URL actually is from the point of view of the Browser.
Shibboleth is running on some VM in the machine room. You could be accessing it through the public production URL ("https://auth.yale.edu/idp") but you could also have set up an SSH tunnel from your local computer port 8080 to the VM port 8080 (the port Tomcat uses). The problem is that Tomcat and Shibboleth cannot tell from the network protocol just how the network traffic is routed between the Browser and the VM. The only hint it has is the HTTP Host Header.
Initially the Browser will have generated a Host header based on the network address in the URL it started with. In these cases, the header will either be "http://localhost:8080" or else "https://auth.yale.edu". The Host header may pass through a number of intermediate devices, and some of them may edit some of the HTTP content, but the meaning of the Host header as "the network address of the server from the point of view of the Browser" should be preserved. Then when Shibboleth needs to Redirect the Browser from one of its URLs to another URL, it can use the Host header as the start of the Redirect URL and know that when the Browser can use it to get back to the same Shibboleth server.
If you submit an IdP Initiated Login to Shibboleth and immediately get a Browser redirect to a completely different URL location, then someone has messed up the Host header between the Browser and Shib.
There is a different Redirect problem when Shibboleth uses CAS to log you in. The convention with CAS is that Shib, like any other CAS client, provides a service= string that contains a URL in the Tomcat server to which CAS can Redirect the Browser after it has added the Service Ticket ID. For some reason, although the Unicon CAS-Shib itegration code has access to the Host header, it only uses that header to set the port number. The rest of the Service URL is constructed from a property that in the Yale Install Project is called "cas.target.url" and is supplied at install time.
The problem is that this property is not dynamic and it is not going to adjust between "localhost:8080" for an SSH tunnel and "auth.yale.edu" through the F5. Since it seems like a very bad practice to configure the VM with properties that will not work in production, if you discover that Shibboleth is Redirecting the Browser to CAS with a Service URL that cannot possibly get back to the Shib VM in the way you are currently accessing that VM, then you have to use one of the Client configuration tools described in the Client Configuration part of this set of documents to rewrite or reroute the Service URL (the Browser Redirector plugin can do it for example).
The IdP Initated Login provides the simplest set of tests. About 95% or more of Service Providers will accept IdP Initiated, and you should do all that testing first. It is also the simplest network setup because you only have to fix the two Redirect problems (Shib to Shib and CAS to Shib) if they happen to occur.
In fact, for initial testing it is not actually necessary for the SAML Response to be delivered to the Service Provider (or for it to be trusted if it does arrive there). If you are running the SAML Tracer in Firefox you can capture the SAML Response and usually determine if the Subject and Attributes are correct just by inspecting it.
However, for final 100% coverage testing, then you should use production credentials to generate a SAML Response the Service Provider will actually accept and log you on. Of course, for that to work the URL has to point to PREPROD Shibboleth, either directly through the F5 or through an SSH tunnel from localhost.
Change the EntityID at the end of the "Unsolicited/SSO" URL and you can verify that the right attributes are sent to any particular Service ProviderThis URL is a Shibboleth feature, not part of the SAML standard. The Shibboleth code that responds to a "/profile/SAML2/Unsolicited/SSO" URL path does not care about the hostname, port, or protocol. It makes no assumptions about how the client connected to the server or what the network looks like.
The only checks are:
- the providerid ("nobody.yale.edu" in this example) must be the EntityID of a Service Provider configured in some Metadata file
- The Metadata file must have a configured default AssertionConsumerService URL
- The hostname in the ACS URL must exist on the network.
Internally Shibboleth builds a dummy SAML Request, then triggers normal SAML processing to generate a Response.
If Consent is configured (and it will be by default in most Sandbox environments) the generated Attributes will be displayed. Then the SAML Response will be sent to the ACS URL.
This will work and will attempt to deliver the Response no matter what operating system you are running on, no matter what hostname, port number, or protocol your Tomcat uses, no matter what EntityID your Shibboleth server is configured to use for itself. In short, there are no network issues for IdP Initated Login.
Of course, the SP will probably discard the Response because it will generally not be digitally signed correctly, and the EntityID that issued it may be unrecognized by the SP, but that is for later testing.
However, there is one network configuration problem you do need to solve. The Unicon CAS Shibboleth integration provides a parameter used to define the Service string sent to CAS, which is also the URL to which CAS redirects back its response. This string need only be meaningful to the Client Browser and does not have to have any actual meaning to CAS itself. So a Service value of "http://localhost:8080" is perfectly acceptable.
The network problem is that the Unicon CAS Shibboleth integration determines the port number from the actual request, but it gets the host name from a configured property in the Yale Install Project named "cas.target.url".
If you are using your desktop Sandbox and run Shibboleth in a local Tomcat, then when you Install on your desktop provide an install.properties file that defines:
cas.target.url=http://localhost
Then if your IdP Initiated login also uses "http://localhost:8080/idp/..." then the two agree and you have no problem.
However, if you are SSH tunneled to a VM in the machine room, you need to do some research about what value of cas.target.url was supplied when that Shibboleth instance was Installed. Even if it appears to your Browser to be at localhost:8080, if that VM was installed with cas.target.url set to "auth-test.yale.edu", then when it redirects to CAS it will set the Service string to "auth-test.yale.edu" and CAS will try to send the service ticket back to that server. Even if they are the same machine, CAS will not recognize that the browser that is connected through the SSH tunnel is the same Browser that just sent it a Service Ticket through the public network path. You will get a message from Spring Webflow that the conversation id was not recognized.
So the general rule is that the cas.target.url and the IdP initiated "Unsolicited" URL host names and protocols have to match.
SP Initiated
The IdP Initiated test was simplified because the code that handles the "Unsolicited/SSO" URL does not do any checks on the network address. Technically, the "Unsolicited/SSO" is a Shibboleth programming convention and not part of the SAML standard, so checks are not required.
...