Content Comparison

...

The configuration rules and syntax are defined in the Shibboleth Wiki pages, so the purpose of this document is to either explain why Yale did what it did or to provide useful pointers to Yale Developers when they have to solve problems. The configuration will be described file by file.

Although Shibboleth 3 has certain options to use unmodified old Shibboleth 2 configuration files, we have reorganized our configuration files to use all Shibboleth 3 configuration.

The CAS Integration

Starting with Shibboleth 3, Yale uses the CAS-Shibboleth integration written by Unicon. This is mostly documented in the Unicon project at https://github.com/Unicon/shib-cas-authn3

...

# The CAS Server and the service= we pass to it.
cas.server.url=https://auth-dev.yale.edu
cas.target.url=https://auth-dev.yale.edu
###### TEMPORARY VALUE USEDused WHILEfor ONLYSANDBOX ACCESSor TOSSH DEVTUNNEL ISto SSH TUNNNELShib
#cas.target.url=http://localhost

...

The cas.server.url is the URL to access CAS stopping at port number. If CAS is running on the desktop under Tomcat, the value might be "http://localhost:8080". The Unicon code will add /cas and then will add the /login or /serviceValidate suffix and query string parameters.

The cas.target.url is the hostname of the server that Shibboleth is running on, but this parameter does not include the port number. So If both CAS and Shib are running in a Sandbox on Tomcat, the cas.server.url includes this part of the URL up to but not including the /cas part. The Unicon code will add the /cas/login and /cas/validate parts as it needs themthe 8080, but the cas.target.url does not.

Credentials

The shibboleth-idp/credentials directory of the running Shib server contains files for the private key used to digitally sign SAML messages and the Certificate that contains the public key that partners use to validate the signature. In the Shibboleth/SAML world, certificates like this are always self-signed and are simply containers for the public key. They are distributed through Metadata and there is no trust chain or Certificate Authority involved.

There are three separate pairs of files, one in each environment (DEV, TEST, and PROD). Typically a given partner only trusts one environment, and if the partner installs the PROD certificate and entityID for the PROD Yale IdP, then it will expect SAML digitally signed with the PROD private key file, which is in the shibboleth-idp/credentials subdirectory of the PROD VM.

Shibboleth as distributed generates three pairs of keys (signing, encryption, and backchannel). However, Yale encrypts no Attribute assertions and in the very unlikely case that we did we would just reuse the signing key. So for now we carry forward the Shibboleth 2 "credentials" files and populate this directory with only an "idp.key" and an "idp.crt" file. These are the same files from Shibboleth 2, since any change in the keys would require reconfiguring all our partners and our InCommon data.

The name of the files to use for signing and encryption are specified in the conf/idp.properties file. We changed this configuration file from the original distribution (with separate signing and encryption keys) to use just the one pair of keys and, therefore, pair of files.

InCommon itself provides us with a credential that we can use to validate the digital signature on their Metadata file. The "incommon.pem" file is public and is checked into Source Control and is added by the Install Project.

Shibboleth 3 adds a new key and pair of files that are used to encrypt the Cookie used to provide Client-side storage of session data. This is held in the sealer.jks and sealer.kver files. Periodically a chron job generates a new key pair which is added to the "sealer" files, because when a new key is generated the old key remains valid until session timeout guarantees there is no valid data still sealed with the old key.

Generic

The Yale Install Project stores parameters in the install.properties file (created from the Jenkins Install job parameters), plus the install-ALL.properties and the install-XXX.properties (where XXX is DEV, TEST, or PROD). These properties are loaded into the Maven environment and then the Ant environment of the Install Project and are available during the execution of the Install job. Any configuration file stored in Source Control as part of the resources/updateArtifactSubstituteVariables subdirectory of the Install Project can contain ${property.name} placeholders that will be replaced by the value of a corresponding property at Install time.

However, at Shibboleth startup the Spring Framework has its own variable substitution logic. Spring replaces %{property.name} placeholders in its XML files with the corresponding values from the conf/idp.properties file (and other *.properties files in the conf subdirectory). When we want to use the Spring mechanism, we add a line at the end of resources/updateArtifactSubstituteVariables/conf/idp.properties in the Install Project with generic format:

property.name=${property.name}

This takes the value of the property named "property.name" in the Install Project (that is from install.properties, install-ALL.properties, and install-XXX.properties) and puts that value in this line after the "=". So if the Install Project value is "yale.edu" then when it is substituted here the line written to conf/idp.properties becomes

property.name=yale.edu

Then the same value will be assigned to the same property.name during Spring initialization and will substitute in all the Spring XML where there is a %{property.name} expression.

DataSources

In Shibboleth 2 a Datasource (a database connection pool configuration specifying the database url, jdbc class name, userid, and password) could be configured in a DataConnector element of the attribute-resolver.xml or it could be supplied by the container (the Web Server which is to say Tomcat or JBoss). There was, however, a scary comment in the Wiki that if you use Oracle as your database (which we did) then the Shibboleth provided DataConnector implementation did not work well and they recommended using a container datasource. So that is what we did.

When we migrated to Shibboleth 3 we have initially maintained this convention. Therefore, datasources are configured in the context.xml file that is copied (with variable substitution) to the /apps/tomcat/current/conf/catalina/localhost/idp.xml file by the Install Project.

However, because Shibboleth 3 is not fully a Spring Framework project, there is an alternative. The datasource can be configured as a Spring Bean. Spring has serious industrial strength support for DataSources that is as good or better than JBoss or Tomcat. Moving the datasources to a Spring Bean configuration is planned for a future (but relatively soon) release.

Logging

Logging in Shibboleth 3 is controlled by the conf/logback.xml file. Initially it is treated as a normal configuration file. However, we may want to create a special Jenkins Install runtype to change the logging levels to get more information from a running server, provided that the logging levels can change dynamically.

Services

The conf/services.xml file configures the services and subsystems. In particular, it configures the names and locations of the XML files that configure the other parts of Shibboleth.

It is important enough that Yale removed the commented out sections that are used by services we do not enable so the file is clean.

Yale made on aesthetic change. Normally there is one attribute-resolver.xml file containing both DataConnectors (queries) and AttributeDefinitons. We broke the file into two separate tiles because the two types of attribute configurations are different and because we can assign a different xmlns default to the different types of XML elements if they are in separate files.

Spring <bean> elements creating Yale configured Spring Bean objects have to go somewhere. The two obvious places to put them are global.xml and services.xml. We put them at the end of the services.xml file.