During normal maintenance, the only configuration you change is to add new Relying Parties with Metadata and Attribute-Filter rules (and perhaps new Attributes). That is documented elsewhere. This page is to describe other Shibboleth configuration changes that Yale has made. Chances are you would only see these changes if you compare Yale configuration files checked into the Install Project with unmodified Shibboleth configuration files from the distribution zip, and that will only happen when you are upgrading from one release of Shibboleth to another.
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
This has nothing to do with the Shibboleth internal support for replacing CAS with their own implementation of the CAS protocol. It is also different from the older verison of the Unicon code for Shibboleth 2. The documentation is in a Git Hub repository where you might be tempted to download the source, but generally you do not need to recompile anything. Simply follow the links in the documentation to download the JAR files.
There are two ways you can manage the integration using Yale project management rules. You could put the jar files into the Shibboleth artifact, which would probably be the right thing to do since they are code and not configuration text files. Currently, however, we use the second option and check them into Source Control as part of the Install project even through the jar files are not "source". We may move them to the artifact later on, but for now putting all the Yale configuration dependencies in one spot seems simpler.
Any CAS integration has to provide two parameters. You need the URL of CAS itself, and you need a URL or host name for the service string you send to CAS. You might think that the code could get the second parameter from "hostname", but most of our servers have more than one host name and it is impossible for Unicon when it writes the code to guess which name is the right one to use. These two parameters are in the install-XXX.properties files (where XXX is DEV, TEST, or PROD).
# 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 used for SANDBOX or SSH TUNNEL to Shib #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 the 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.