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 anotherFrom week to week we add new Metadata files and configure the release of attributes to new applications. Occasionally we defined new Attributes or get the same Attribute from a new database. That is the routine maintenance and it is documented in a different page. It is probably a good idea to read the Shibboleth Configuration page first before reading this page because it is more important, and because I assume you understand a little about Spring Bean configuration already.
What is left are all the other Shibboleth configuration files where I have made one change here and one change there for Yale specific reasons and the only time anyone will be interested in these files is if we upgrade to a new release of Shibboleth or if Yale requirements change. That other less important stuff is documented here.
The configuration rules and syntax of all the files are defined in the Shibboleth Wiki pages. However, so the purpose of this document is to either while the Shibboleth documentation will tell you what was done, this page will 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 configurationit and what we expect.
If you upgrade a Shibboleth 2 to a Shibboleth 3 the install process turns on several compatibility switches and then Shibboleth 3 reads and uses the old format configuration files. We did not choose that option. The Shibboleth 3 configuration options have improvements, and it made sense to migrate the files to the new syntax manually to get all the new features.
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-authn3This 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 filesShibboleth has many built in ways to authenticate users (Kerberos, LDAP, ...), but we want it to use our standard Yale SSO solution through CAS. In Shib 2 we used the CAS Client that passes the Netid in the RemoteUser field of the request, and then we select the "RemoteUser" authentication option for Shib. The Unicon code implements the Shibboleth authentication interface and behaves like the other Shibboleth authentication options, but then it redirects the browser to CAS and handles the ticket on return. Potentially this provides additional features, like turning the SAML version of renew=true into the actual CAS renew=true parameter, which you do not get when you use a generic CAS Client that operates as a Servlet Filter unaware of Shibboleth.
Do not get confused with the internal Shibboleth implementation of the CAS protocol. Shibboleth will replace CAS, but we at Yale do not use that option. At this time the CAS protocol support has not been removed from Shibboleth and might even be functional. If it is there we don't use it and it doesn't hurt anything.
Although the link above takes you to a Github location where you could download the Unicon source, we simply download the JAR and Shibboleth configuration files. We do not recompile the source, although you are free to do so.
There are two ways you can manage the integration using Yale project management rules. You could put the Unicon 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 in the resources/updateArtifact/webapps/WEB-INF/lib directory 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. This is simpler. If we made any significant changes to the Artifact and generate a Build job, then we would move the JAR files.
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 thing you can 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).service= string from the Hostname. The problem is that Yale has an F5 front end that owns the "auth.yale.edu" DNS name which is the public name used to access Shibboleth and has to be the value in the service= string, while Hostname on the Shibboleth VM is going to return "vm-shibprd-01.yale.internal" which is not the right value.
The two CAS parameters are different for DEV, TEST, and PROD because there are three CAS servers that might be configured (secure, secure-dev, and auth-dev). In the install-XXX.properties file you will find:
| Code Block | ||
|---|---|---|
| ||
# 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 notTo understand these parameters you need to understand that the names are from the Browser's point of view, not from the point of view of either the CAS VM or the Shib VM. These URLs will be sent to the Browser with an HTTP Redirect and then the Browser will find CAS or Shib itself. In a Sandbox where you are running Shib and maybe CAS on your own desktop under Tomcat, you may be using http instead of https (because it is simpler for testing purposes) and you may be running on port 8080 instead of the standard 80 or 443. More importantly, you can configure your /etc/hosts or \windows\system32\drivers\etc\hosts file to define the hostname as the local machine. Even when using DEV or TEST, you may run an SSH tunnel to the VM, and therefore access the Shib server as if it were localhost:8080.
The cas.server.url parameter is the URL of the CAS server, and the cas.target.url is the Shibboleth server. In DEV they happen to be the same DNS name because it just happens that CAS is https://auth-dev.yale.edu/cas and DEV Shib is https://auth-dev.yale.edu/idp (although they are on different VMs behind the same F5 VIP).
The cas.server.url may need a port number, but you don't add port number to the cas.target.url. I don't know why.
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.
...