...
In order for Shibboleth to generate and for the Service Provider to accept the SAML Response, it has to pass a long list of checks:
- The EntityID of the Service Provider has to be matched in one of the Metadata files configure to Shibboleth
- The Metadata file has to provide an AssertionConsumerService (ACS) URL to which the Response can be sent.
- 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.
The most common Shibboleth testing occurs when we have a new Service Provider to support. They will provide us with Metadata and a list of attributes they 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 possibleOne of the Yale Shibboleth IdPs (TEST, or PROD) will have been configured to the Service Provider. In order for the SAML Response sent by Shibboleth to be accepted:
- The EntityID of the IdP (auth-test or auth) that sent the Response has to match the EntityID configured in the SP.
- The Digital Signature or the Response has to validate using the Public Certificate that the SP has configured for the Yale IdP.
- The SP EntityID and AssertionConsumerService URL in the Response XML have to match what the Service Provider believes to be its own EntityID and URL.
- A change of Shibboleth should not change the values of the Subject and of any Attribute. The user can change his name or email address, but if the old Shibboleth sent the Netid as Subject, then the new Shibboleth should not sent netid@yale.edu because that might make the SP think this is a different person. This is not important if the netid is sent as an attribute and the Subject is just a "transient" hash value.
Generally speaking, this means that an SP configured to work with TEST Shibboleth can only work with TEST, though in 99% of the cases we have an SP that is configured to only work with PROD, in which case you have to test with PREPROD.
Having said that, the version of Shib you use only matters if you are going to go all the way and try to login. A lot of testing can be done by just eyeballing the generated Attributes. If you are supposed to send firstname, lastname, email, and eduPersonPrincipalName, and if DEV or Sandbox Shibboleth generate a SAML Response with firstname, lastname, email, and EPPN in the XML, then you are pretty safe to say the case passes preliminary testing.
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 group names were generated.
Attributes have a formal unique name, a friendlyName (short nickname), and a single value or occasionally a list of values. A simple example (removing all the XML boilerplate) would be:
...
Different partners can ask for the same attribute with different names. So "John" can be a FirstName, First_Name, givenName, and so on. So you have to generate both the right name and the right value for each item.You need to check that you are providing the right value, but also that you are giving it the right name.
Before we had a PreProd
When a new Service Provider appears, it is convenient to initially ask them to configure the EntityID and Public Key Certificate of ourTEST Shibboleth. Then we can verify the attribute list, attribute names, and values and verify a login to the application. When it is all working, then we promote the changes to Production Shibboleth and ask the Service Provider to change EntityID and Certificate configuration to point to PROD. After a few days, we lose our contacts with the person at Yale coordinating the installation and the contact at the Service Provider who is making any changes.
...