...
- The EntityID (an arbitrary but unique identifying string) has to be matched in one of the Metadata files.
- The Metadata file has to provide the correct URL to which Shibboleth sends the SAML Response message. This is called the AssertionConsumerService or ACS URL.
- The Digital Signature generated by Shibboleth has to be validated by the Public Key or Certificate configured for Yale in the Service Provider application and the EntityID name that Shibboleth uses to identify itself also has to match. In practice, this means that a Service Provider configure with PROD Shib has to get a message from a server configured with the private key credentials and EntityID of PROD Shib, while a SP that expects a message from TEST needs a message signed with the TEST key and sent with the TEST EntityID.
- The message will contain the EntityID and ACS URL of the Service Provider. SAML messages have an implied "eyes only" rule, so these two strings have to exactly match the EntityID and ACS URL that the Service Provider expects. Since these two values came from a Metadata file the SP sent us, this check is usually never a problem.
- The message does not contain any information about the network address or server name of the Shibboleth server. So it is not important that Shibboleth run on any particular machine.
- The SAML Response must contain any attributes that the Service Provider has told us are required. Generally speaking, across any change to Shibboleth the value of each attribute should not change. If the user changes their name or email address, then Shibboleth will start sending the new attributes, but the attributes should not change if Shibboleth switches to a new database or we put in a new version of Shibboleth.
- Each SAML message contains a Subject. In most cases the Subject is ignored, but there are a few special cases that also turn out to be really important cases (Google for EliApps, Service-Now) where the Subject is the only field and it is special and must have the same value each time.
In day to day testing, we are typically responding to a request from some The most common Shibboleth testing occurs when we have a new Service Provider to supply support. They will provide us with Metadata and a list of attributes . Usually they are routine attributes we are already sending to someone else. So testing just means that we generate a SAML Response for this Service Provider and then you can read the XML and verify that the requested attributes are included. This is why Shibboleth testing is usually not a problem, and you can typically do it on DEV or TEST or on the Sandbox on your desktopthey need us to supply.
If the attributes are already defined for someone else, all we need to do is to add the Metadata and to add or modify an entry in the attribute-filter.xml to release the attributes to this EntityID. Generally we can set this up in Sandbox or DEV testing, use the IdP Initiated Login URL with this EntityID, and then capture the Response. Correct behavior can be determined by an inspection of the Response. Then the code can move to PREPROD and a real login to the application becomes possible.
Occasionally someone asks for something new, or for a new version of something we are already generating. The Law School asks, "send us the list of groups in the Law School OU that contain this user as a member." We may have previously generated a list of all group membership, but now we need to filter it for just Law School groups and that is new. So now you create the new attribute, release it to this partner, and again manually check the generated SAML message to see if the right values were generated.
...
In order for the SAML Request to work, it has to pass a shorter list of checks:
- The EntityID in the Reqeust Request has to match the EntityID configured for the Shibboleth servier in a property of the Install project.to this Shibboleth server through the "idp.entityid" property on the Jenkins Install. Because SPs are almost always configured to talk only to PROD, that means the Shibboleth has to be installed with "idp.entityID= https://auth.yale.edu/idp/shibboleth"
- The Service Provider will send the message to the URL it has configured for Yale. Unfortunately, this will almost always be a production URL ("https://auth.yale.edu/idp/...") and so the tester has to trap this on their desktop and reroute it to the test or preprod Shibboleth server (more on that below).
- The Digital Signature generated by the Service Provider has to be validated by the Public Key or Certificate configured in the Shibboleth Metadata that defines that Service Provider.
- The message will contain the EntityID and ACS URL of the Yale IdP. As before, SAML messages have an implied "eyes only" rule, so these two strings have to exactly match the EntityID and ACS URL that the test Shibboleth Server expects. That means that the test Shibboleth has to have the EntityID of Production Shibboleth and we have to fake it out so it thinks it is running through https on the "auth.yale.edu" machine.
So the problem is to trap a Request that the Service Provider is trying to send to Production Shibboleth and send it instead to the test machine. The good news is that this message has to go through the Browser on the tester's own desktop, so it is fairly easy to modify Firefox, or the HTTP routing, or the network address resolution to send all requests for "https://auth.yale.edu" temporarily to another machine.
The hard part is to set up the test machine so that it really thinks that is is "auth.yale.edu". This turns out to be a fairly simple networking trick because modern campus (or corporate) networks are always broken up into security zones protected by firewalls and special network appliances.
- This will be done by the SP and requires nothing on our end.
- In addition to the EntityID, a Request contains the SSO URL for Shibboleth configured to the SP in Yale's Metadata (typically "https://auth.yale.edu/idp/profile/SAML2/POST/SSO" or "https://auth.yale.edu/idp/profile/SAML2/Redirect/SSO"). This has to exactly match a URL that Shibboleth constructs from its environment using a utility class that gets some of its information for the Host header and some from the HTTPServeletRequest object passed by Tomcat.
So the Browser, test computer on which the Browser is running, the network path between the Browser and the test VM, and the Tomcat environment on the VM all have to do two things:
- They have to intercept a request for auth.yale.edu and send it to the test VM, but
- They have to set the Host header in the request and the HTTPServletRequest object up so that the URL Shibboleth constructs using the utility class begins with :https://auth.yale.edu/idp". More explicitly, the URL constructed cannot start with "http:" (Tomcat does not believe the request comes over SSL) and there cannot be a port number (so no port number in the Host header or added by Tomcat).
One set of problems has to be solved to send the request to the test VM in the first place. No ordinary computer inside or outside Yale can communicate with the VM that runs the Shibboleth IdP. Instead, a network address like "https://auth.yale.edu/idp" is defined to a special network front end device. At Yale this is the "F5" that stands in front of all network services. The host name "auth.yale.edu" resolves to a network address that is on the F5 device. The Certificate that proves that the server is "auth.yale.edu" is installed on the F5, not the Shibboleth server VM. So Shibboleth (and pretty much every other network function) cannot generally expect to find from the computer on which it runs the host name that everyone else in the world uses to get to it. For the Shibboleth code to even know about "auth.yale.edu", then either it has to have this name configured as one of its properties provided by its Install Project, or else it has to get the name from the control blocks that Tomcat provides with each incoming request.
...