Content Comparison

...

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

Shibboleth has many built in ways to authenticate users must authenticate (logon) a user. Normally it will present a login page, the user will enter a userid and password, and Shibboleth will authenticate the user to some backend service (Kerberos, LDAP, ...), but we . We want it to use our standard Yale CAS SSO solution through CAS.

In Shib Shibboleth 2 we used an external authentication with the standard 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 in the resources/updateArtifact/webapps/WEB-INF/lib directory of the Install project even through the jar files are not "source". 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 thing you can get the 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:

# 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

To 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 whyJava Client. We defined Java Servlet Filters in the web.xml file that ran before the user got to the Shibboleth application. These filters redirected the user to CAS, then validated the Service Ticket, and stored the userid by wrapping the HTTPServletRequest object with a proxy that returned the Netid when the application (Shibboleth) called the request.getRemoteUser() method. Shibboleth was then configured to use its own RemoteUser authentication module, which assumes the user has been authenticated by the Container (Tomcat, JBoss), although in this case it is a Servlet Filter that did the job.

In Shibboleth 3 we remote the Java CAS Client Filters from web.xml. Unicon adds a new Authentication module to Shibboleth. In addition to Kerberos, LDAP, RemoteUser, and so on there is now a Shibcas option. So CAS authentication is now driven from inside Shibboleth instead of from a Filter that runs before Shib. This allows a tighter integration between SAML options and CAS options.

Do not confuse this with the ability of Shibboleth to use CAS protocol and perform the CAS function to other applications. That is a whole different set of modules and configuration options that we do not use at Yale.

At this time, the configuration files that Unicon distributes through Github were downloaded and placed in the Install Project under Source Control. This includes the jar files containing the Unicon code, which we have not modified. It could be argued that jar files belong in the Artifact in Artifactory rather than being in the Install Project because they are code and not source. This is a legitimate point, but for now the Artifact is vanilla shibboleth.net distributed content, there is no Jenkins Build job, so extra jars are at least for now copied during the Install phase.

Any CAS Client has to be given two parameters:

• "https://secure.its.yale.edu/cas" - You need to tell the client how to get to the CAS Server. The rest of the URL (/login, /serviceValidate, etc.) is part of the CAS protocol and the client can add those pieces itself.
• "https://auth.yale.edu/idp" - You need to tell the client what URL to use as the service= so CAS can redirect the browser back to Shibboleth.

You might think that Shibboleth knows its own URL, but that is not true in general if Shibboleth is behind an F5 front end. The "auth.yale.edu" is the DNS name of a Virtual IP address on the F5, and the F5 forwards anything that comes in for "https://auth.yale.edu/idp" to some "vm-xxxx-01.web.yale.internal" Virtual Machine. The problem is that Shibboleth running on the VM can only query its host for the local hostname, and that will be the internal VM name that may not even be accessible to the browser. The service has to go through the F5, and Shibboleth can only discover the F5 name if you configure it.

Unfortunately, there may be some confusion over port numbers. This would not be a problem if the CAS Shibboleth Integration took the port number it puts in the service= string from the configuration. However, Unicon only configures the server name part and calls a routine to add the port number and context name (/idp) on the end of the configured host name. The routine gets this information from the HTTPServletRequest object, which in turn gets them from the Tomcat container.

This becomes a problem because the port number (or its absence for 80 and 443) used by the F5 VIP may not be the port number used by Tomcat on the virtual machine. In fact, since the F5 holds the certificate and terminates the SSL connection from the browser, and because there is nothing super sensitive in the SAML Response, the connection between the F5 and the VM may be ordinary unencrypted HTTP, so the VM port number may be the Tomcat default of 8080. This can result in a service=https://auth.yale.edu:8080/idp/... which means the F5 has to be configured to accept SSL for auth.yale.edu on both 443 and 8080 (or it may be the default to accept all ports, since I do not know how this ever worked before unless the F5 is ignoring the port number in its processing). If the "tomcat" user on the VM were privileged to bind to port 443, it could be possible to put a self-signed certificate into Tomcat (since the F5 does not validate the Certificates it gets from a machine room computer), and run SSL and the same port number between the F5 and the VM that is used between the Browser and the F5.

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:

# The CAS Server and the service= hostnames
cas.server.url=https://secure.its.yale.edu
cas.target.url=https://auth.yale.edu

These are Yale parameters. They are plugged into the shibboleth-idp/conf/idp.properties file to generate derived parameters (shibcas.casServerUrlPrefix and shibcas.serverName) that are used by the Unicon integration code.

On a Sandbox when using IdP Initiated Shibboleth login (https://localhost:8080/idp/profile/SAML2/Unsolicited/SSO?providerId=entityID) then you can set the cas.target.user to localhost as well. However, to process a request for an SP initiated login you need to be running a proxy on your desktop. See Testing Shibboleth - Test Cases for more information.

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. The private key is very, very sensitive because possession of this file would allow someone to impersonate any Yale user. The private key is not part of the Artifact or the Install Project. It is never stored on Artifactory or Source Control. Protection of this key file belongs to Operations.

...