Metadata and Attributes described Elsewhere
From 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.
...
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-authn3
...
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.There are three separate pairs of files, one in each 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.
The Certificate, however, is just a convenient format to distribute a public key. It is self-signed and is never issued by a real CA. The only information it contains is the Public Key. If there was some other widely supported file format for distributing public keys, we might never use Certificates for the purpose. It goes without saying that this has nothing to do with the SSL certificate of the server, and it is not and cannot in general be validated with a Trust chain.
As a result, it does not matter what Crypto digest algorithm is specified in the Certificate. The only thing that matters is the 2048 bit RSA key. No matter what the certificate says, Shibboleth will choose SHA1 or SHA256 for its digital signature based on the other Shibboleth security configuration files. There is a default digest algorithm and then there can be exceptions based on the Metadata or explict configuration based on EntityID. Therefore, this key and certificate only need to be replaced if 2048 bit RSA becomes vulnerable.
I believe that Shibboleth 2 defaulted to SHA1, and I know that Shibboleth 3 defaults to SHA256. The exact syntax for configuring exceptions is not clearly documented in the Wiki, so we hope either that it is not needed or that partners that do need it give us correctly configured Metadata.
Each Yale 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 ) has its own private key (and public key certificate, and Metadata file, and EntityID). InCommon and most partners only configure the PROD information and therefore only trust SAML generated by PROD. When the Shibboleth VMs change, then the idp.key and idp.crt files have to be copied from the old DEV to the new DEV, from the old TEST to the new TEST, and from the old PROD to the new PROD.
SAML provides for separate keys for encrypting Assertions and for signing Assertions. Shibboleth as distributed by shibboleth.net generates three sets of files: (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 databackchannel). The backchannel appears to be for Web Service requests. In theory it might be important to separate things, but for now in the "real world" Yale encrypts no Attributes at the SAML level. The vendor should supply an https: AssertionConsumerService URL and then the entire SAML Response will be encrypted by the transport layer. Therefore, we use only two files (idp.key and idp.crt) and configure them for use in both signing and encryption (that we don't use).
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.
...
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 Spring Bean Parameters
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 only during the execution of the Install job itself. As a result, 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 as the Ant script in the Install Project copies configuration files into the /apps/shibboleth-idp directory. This produces configuration files that have literal numbers and strings as values.
...
When in doubt, look at the files after running Install in a Sandbox and compare them to the Install project to see which change and which remain the same.
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.
...
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.
...
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. The current use is to create "predicates" that return true or false based on whether the application the user is logging into is in a list of EntityIDs.
Relying Party
In Shibboleth 2 the relying-party.xml file also included MetadataProviders. In Shib 3 there is a separate file for metadata-providers.
...
- We may want to turn off Anonymous Relying Parties. We need to confirm that Metadata has been generated for every party we currently support in production. Scanning Shib 3 logs will give us a chance to look for any remaining legitimate Anonymous RPs and configure them properly. Currently we turn Consent on for Anonymous.
Metadata Providers
The metadata-providers.xml file contains almost exactly the same content as Shibboleth 2. The only change is that Refresh periods have to be expressed as "PT5M" (which means check every 5 minutes) where as in Shibboleth 2 the same thing could be expressed as an integer number of milliseconds.
Although we have not changed the configuration, the defaults appear to have changed. Shib 2 did not check local disk Metadata files unless an explicit refresh time was configured. Shib 3 appears to check the timestamp on files for changes every 5 minutes by default. It does not seem necessary to change this.
Access Control (to Status Page)
Currently the only form of Access Control is by IP address. We modified the conf/access-control.xml file to allow IP address ranges to be inserted from a property file value
...
then a subnet in the DevOps area of ITS and a subnet in the SPS_DC VPN are able to display the status page. This will be expanded on request.
Logo and Footer
In a few messages we replace a dummy logo with a Yale ITS logo. The image is in webapp/images/YaleITS.png and it is used because of some lines in messages/error-messages.properties:
...