Versions Compared

Version Old Version 18 New Version 19
Changes made by

Howard Gilbert

Howard Gilbert

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Background

To test Shibboleth in a non-production configuration, you need to know a bit more about the checks that are performed on a SAML message. Almost all the important testing can be performed on Shibboleth running on your desktop, but to do the testing you have to know how to avoid tripping over one of the preliminary checks that will generate an error message before you get to the part you want to test.

The usual SAML definitions:

  • The applications you use Shibboleth to login to (Box, Eliapps mail, IPTV) are called Service Providers (SP) and are also called Relying Parties (RP). We will use the term SP here.
  • Shibboleth and each SP has a globally unique ID string called an EntityID. To make it globally unique, it is often a Web URL. The EntityID of production Shibboleth at Yale is "https://auth.yale.edu/idp/shibboleth", but the EntityID of Google Apps is just "google.com".
  • Shibboleth at Yale and each SP exchange a file called Metadata. A Metadata file contains the EntityID, an encoded Certificate that can be used to validate digital signatures, and a URL. The Shibboleth "SSO" URL is where the SP redirects the Browser to login to Shibboleth, and the SP "ACS" URL is the network address to which Shibboleth tells the Browser to send the SAML "Response" message so the user can login.
  • The SAML Response message from Shibboleth to the SP also contains Attributes of the user (like firstname, lastname, email address, etc.) that Shibboleth is configured to send to that particular SP.

In testing, the SP's don't change. They are still out there on the network with the same Metadata, EntityID, and "ACS" URL. Typically they are configured to redirect the Browser to production Shibboleth, and they will always only accept a message sent by the real production Shibboleth. They will not login anyone if they get a SAML Response from Shibboleth running on your desktop, and usually not from DEV or TEST Shibboleth either. However, you can always generate the SAML Response, capture it with the SAML Tracer plugin on Firefox, and then inspect it for correctness. That will do 99% of the testing even though you could not actually login because the digital signature generated by the test machine was not valid for production.

The problem occurs when you do not get to generating the SAML Response because something in the configuration triggers an error at the beginning of processing. To avoid those errors, you need to know a bit more about SAML with extra emphasis on the checks that Shibboleth, the SP, and the network make at each step. For example, in some cases Shibboleth will generate an error if it thinks it is running on a Tomcat that is not using SSL. Most of the time it doesn't care, but in one case it does make the check. So either you have to configure Tomcat to use SSL, or else you have to configure it to tell Shibboleth the request came in over SSL even when it didn't.

To get Shibboleth to generate a SAML Response with a login request to an SP, you have to provide Shibboleth with the EntityID of the SP. For example, in either of two different ways you tell Shibboleth to process a request for "google.com", and Shibboleth generates the SAML Response and tries to send it to the ACS URL to log you into your Eliapps mailbox. In order for this to work:

  • The EntityID of the Service Provider has to be matched in one of the Metadata files configured to Shibboleth
  • The Metadata file has to provide an AssertionConsumerService (ACS) URL to which the Response can be sent.

...

Audience

If you are an application owner testing a new version of Shibboleth before it goes into production, or if you are testing a new application that has not yet been configured to the production Shibboleth server, then you want to look at the instructions for configuring a desktop system to use Pre-Production Shibboleth. See Testing Your Application before a Shibboleth Change.

This document provides instructions for a Shibboleth developer who needs to test a Sandbox Shibboleth running on his desktop under Tomcat, or to test new VMs in the machine room for a future release of Shibboleth that has not yet even replaced the DEV or TEST environments.

Background

Generally speaking, you can test proposed changed to Shibboleth using https://auth-dev.yale.edu/idp and https://auth-dev.yale.edu/idp, then do final testing on the Pre-Production machine by changing your "hosts" file.

However, a Shibboleth developer does 90% of the testing using a Sandbox Shibboleth running on the local desktop computer.

When you are making a major Version upgrade, as we did moving from Shibboleth 2 to Shibboleth 3, then it is necessary to create an entirely new set of VMs in the machine room, with new Install jobs. A certain amount of testing has to be done with these VMs to make sure that the Installation process is working before you can even change the F5 front end to point to them in DEV or TEST. During this period, the only way to access the new VMs is to use an SSH tunnel that exposes the Tomcat running on the VM as if it were a local port on your desktop computer.

In both cases, you end up effectively going to "http://localhost:8080/idp", but even if that is the real address of Shibboleth, that doesn't mean that this is the exact URL you are always going to want to use. Sometimes you need to create an alias name for "localhost" (a.k.a. IP address 127.0.0.1). Sometimes you need to hide or translate the port number. There are several tools that can help.

Why isn't it good enough to simply get to Tomcat and the Shibboleth server application? Sometimes there is a problem created by the default HTTP Host header, the fact that the Sandbox uses http instead of https, and the default Tomcat configuration. Sometimes the problem comes from SAML.

SAML Checks

First, the usual SAML definitions of terms we have to use:

  • The applications you use Shibboleth to login to (Box, Eliapps mail, IPTV) are called Service Providers (SP) and are also called Relying Parties (RP). We will use the term SP here.
  • Shibboleth and each SP has a globally unique ID string called an EntityID. To make it globally unique, it is often a Web URL. The EntityID of production Shibboleth at Yale is "https://auth.yale.edu/idp/shibboleth", but the EntityID of Google Apps is just "google.com".
  • Shibboleth at Yale and each SP exchange a file called Metadata. A Metadata file contains the EntityID, an encoded Certificate that can be used to validate digital signatures, and a URL. The Shibboleth "SSO" URL is where the SP redirects the Browser to login to Shibboleth, and the SP "ACS" URL is the network address to which Shibboleth tells the Browser to send the SAML "Response" message so the user can login.
  • The SAML Response message from Shibboleth to the SP also contains Attributes of the user (like firstname, lastname, email address, etc.) that Shibboleth is configured to send to that particular SP.

Box and Google do not know or care that you are testing a new version of Shibboleth on your desktop. They are configured to talk to production (auth.yale.edu) and their Metadata, Certificates, login URL, and other parameters are not going to change. They will not accept a SAML Response generated by your Sandbox, so either you stop your test server from sending the Response or you accept that you will get an error message from the SP saying that the login failed to work. The trick is to configure your Browser to trace and capture the SAML Response your test Shibboleth generated, so even if the SP won't accept it,  you can go back and examine the XML yourself to verify that the Subject and Attributes are correct and should be accepted eventually when you run this configuration on a real Shibboleth server.

So if a problem occurs, it is triggered by an internal Shibboleth check that occurs at the very beginning of processing before Shibboleth even fetches the attributes.

You have to provide Shibboleth with the EntityID of a Service Provider. Then

  • The EntityID of the Service Provider has to be matched in one of the Metadata files configured to Shibboleth
  • The Metadata file has to provide a default AssertionConsumerService (ACS) URL to which the Response can be sent.
  • A lookup for the hostname in the ACS URL must return an address.

For example, suppose you supply the EntityID of "google.com". Shibboleth will search the Metadata files and finds in google-metadata.xml a line:

<EntityDescriptor entityID="google.com"

Having matched the EntityID, it now looks at the ACS statement in that Metadata file:

        <AssertionConsumerService index="1" isDefault="true"
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            Location="https://www.google.com/a/yale.edu/acs"/>
        <AssertionConsumerService index="1" isDefault="false"
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            Location="https://www.google.com/a/gdev.yale.edu/acs"/>
        <AssertionConsumerService index="1" isDefault="false"
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            Location="https://www.google.com/a/gtst.yale.edu/acs"/>

There are three ACS locations that turn out to be for the production, dev, and test instances of Eliapps. The one with isDefault="true" is production, so that will be the URL to which the login message is sent. Shibboleth will verify that there is a machine on the network with name "www.google.com".

Of course, Shibboleth has to also look up the EntityID in the attribute-filter.xml file to know what attributes to send, and it has to find the attribute definitions. Those are all steps where your configuration can make mistakes, and errors will show up when the generated SAML Response message does not contain required data or contains the wrong value.

However, if the EntityID is not found in a Metadata file, or the Metadata file does not have a single or default ACS URL, then the request is incomplete and Shibboleth will not even start to process it.

If you actually want to login to the SP, then you need to be running the request on a Shibboleth that the SP is configured to respect. That will be Production or Pre-Production Shibboleth for most SPs, although during early testing with a new SP, it may be configured to use TEST Shibboleth. Now things are a bit more complicated because there are a long list of checks the SP will make on the SAML Response that you send it:

...