The following instructions are meant to get you going as quickly as possible. If you want a better understanding of what's going on, go to the next sections of this document.
In summary, the folders containing configuration files which matter are:
/opt/shrine/tomcat ← Tomcat home
/etc/shibboleth ← Shibboleth configuration files
/etc/httpd/** ← Apache configuration files
/var/www/html ← Apache static content as set in, for instance, /etc/httpd/conf/httpd.conf
Configuration files based on samples in Git
Sample configuration files can be found in the Git repository (https://open.catalyst.harvard.edu/stash/scm/shrine/shrine.git, "sso-phase1.1" branch) in the shrine-setup module, specifically at shrine-setup/src/main/resources/sso:
- sso/apache/sp.conf-sample
- sso/apache/sp-metadata.xml-sample
- sso/shibboleth/attribute-map.xml-sample
- sso/shibboleth/shibboleth2.xml-sample
- sso/tomcat/server.xml-sample
Copy these files to the Location on SP indicated in the table below.
Then search for the marker: 'ADJUST_FOR_YOUR_SITE' in each of these files for indications of what / where you need to edit.
Public Key Encryption and Signing
| key pair | /etc/shibboleth/sp-key.pem /etc/shibboleth/sp-cert.pem | Create a key pair; include the content of the certificate (sp-cert.pem) in sp-metadata.xml (see below), and the paths of the key and certificate as xml attributes of the <CredentialResolver> element of shibboleth2.xml (see below) (what if the private key is password protected?) |
| idp-metadata.xml | /etc/shibboleth/idp-metadata.xml | A copy of your IdP's metadata. You'll need to ask the admin(s) of your idP for a copy of it. |
Configuration files based on samples in the Git repository
| Location in Git Repo (under shrine-setup/src/main/resources) | Location on SP | Notes |
|---|---|---|
| sso/apache/sp-metadata.xml-sample | /var/www/html/sp-metadata.xml – as long as your Apache configuration sets DocumentRoot to /var/www/html (for instance in /etc/httpd/conf/httpd.conf) | To be shared dynamically with your site's IdP (i.e. make it available at a given URL and share that URL with your IdP's maintainers/admins); or omit from the SP's web server, and instead email it to / share it securely with the IdP admins whenever it changes (if it does) In either case, populate the entityID, public key certificate, and consumer service location with yours |
| sso/shibboleth/shibboleth2.xml-sample | /etc/shibboleth/shibboleth2.xml | Specifies many aspects of your SP. You need to populate the <ApplicationDefaults> element's entityID and the <SSO> element's entityID xml attribute. Note that we do not make use of the REMOTE_USER xml attribute in our implementation. Instead the remote user is specified in the attribute-map.xml. The <CredentialResolver> element specifies the private+public key to use for encryption and signing while communicating with the iDP. If you put the keys in the location specified above, there is no need to modify this element. (private key should be in a "safe" location and password protected. see what iTeam/Simon does) The <AttributeExtractor> element specifies the location of the file that specifies which attribute(s) returned by the iDP must be made available to the the Tomcat's java code as Servlet Request attributes. |
| sso/shibboleth/attribute-map.xml-sample | /etc/shibboleth/attribute-map.xml | The file name and path of this file is specified in the <AttributeExtractor> element's path xml attribute in shibboleth2.xml. This file specifies the SAML content that your SP turns into "attributes". In our implementation it specifies that the "ecommonsid" SAML attribute returned by the iDP upon successful login will be made available to the java code running on Tomcat as the Servlet Request attribute "remoteUser". |
| sso/apache/sp.conf-sample | /etc/httpd/conf.d/sp.conf | Tells Apache to require Shibboleth login for Shrine Urls (/shrine-api/*), and to proxy all the relevant HTTP requests to the Shrine application using the AJP protocol. Tomcat should open port 8009 only to localhost, and should reside on the same host as Apache. |
| sso/tomcat/server.xml-sample | /opt/shrine/tomcat/conf/server.xml | Merge it with the existing server.xml. Sets up the receiving end of AJP over NIO2 connection with Apache. |
sso/shrine/shrine.conf-sample or sso/shrine/override.conf-sample | /opt/shrine/tomcat/lib/shrine.conf /opt/shrine/tomcat/lib/override.conf | Set configuration option for using "sso" for log in. Specify the logout URL. Specify Shrine's session timeout in ms. You should use either shrineMerge into existing shrine.conf or override.conf. |
Overview
Content Tools