1. Shibboleth: Installation and Deployment Scott Cantor (cantor.2@osu.edu) July 29, 2002 Scott Cantor (cantor.2@osu.edu) July 29, 2002

2. 2 Installation: Packaging Alpha 1 and 2 are binary distributions. Source was made public in late July: http://middleware.internet2.edu/opensaml/cvs.html Alpha 2.5 will probably be binary with source. Beta 1 should support “./configure; make; make install” for autoconf platforms and Visual Studio on Windows. Even with better packaging, manual installation of servlets and Apache modules will be needed.

3. 3 Installation: General Solaris 2.x and Linux Current Development Versions: Apache 1.3.26 mod_ssl 2.8.10 OpenSSL 0.9.6 Sun JDK 1.3.1 Jakarta Tomcat 3.3.1 Deploy Guide: http://middleware.internet2.edu/shibboleth/docs/DeployGuide-alpha2.txt

4. 4 Installation: General Both origins and targets need: SSL-enabled Apache server, equipped with a certificate signed by a club-approved CA Jakarta Tomcat servlet engine with AJP 1.3 connector (mod_jk) All the servlets are packaged together in a single deployment archive (shibboleth.war) that can be copied into tomcat/webapps, auto-expanded, and configured

5. 5 Installation: Origin Site Install additional supporting components: User handles can be stored in-memory or in MySQL User attributes can be accessed in LDAP or a restricted set (EPPN and affiliation=member) can be “echoed” by the AA Back-end interfaces will be refined over time to simplify pluggable implementations, and use standard Java APIs like JNDI and JDBC when possible.

6. 6 Installation: Origin Site LDAP To use the LDAP support in the AA, provide web.xml with an LDAP URL and an attribute to match against usernames (e.g. uid). Any vanilla LDAP server will do, but users should be in the eduPerson object class, so that EPPN, affiliation, and entitlements can be found. Current strategy is to populate LDAP with these attributes in advance. Future AA will be more flexible, support relational queries, etc.

7. 7 Deployment: Origin Site Choose a name for your site, probably your best known top-level domain. This name will be part of your club application and is configured into the HS and AA servlets (web.xml). Special Note: Alpha-2 targets will reject attributes like EPPN if the “scope” doesn’t match the site name. This will be more flexible later.

8. 8 Deployment: Origin Site PKI Requirements The web server’s SSL certificate will protect both the HS and AA servlets. The AA servlet path is configured to support client certificate authentication: SSLVerifyClient optional SSLOptions +ExportCertData The allowable client CAs are specified: SSLCACertificateFile /usr/local/shib/etc/ca-bundle.crt

9. 9 Deployment: Origin Site PKI Requirements The HS servlet must digitally sign its messages using a key and certificate valid for digital signature creation, signed by a club-approved CA. Alpha-2 uses a Java keystore, which allows self- generation of a key and certificate request with the keytool command (see deploy guide). The hostname of your HS is the first field in the certificate request. Using the SSL server key is possible, but requires some custom Java code to import/export a private key.

10. 10 Deployment: Origin Site Club Application Target sites are given a “registry” of trusted origin sites to protect them from rogue users. Once names are chosen, provide the following in an e-mail (address in deploy guide): Site Name Complete Handle Service servlet URL The HS hostname (went into the certificate CN) Aliases/shorthand for your institution (used by WAYF)

11. 11 Installation: Target Site SHIRE (Java) Target “session-establishment” is installed by mounting the SHIRE servlet into Apache. The servlet will pass session details on to Apache using files in a /tmp folder (the beta will integrate the design and remove the servlet). The servlet will load the origin site registry at startup, either from Internet2 or a local file, and can optionally verify the registry signature.

12. 12 Installation: Target Site SHIRE/SHAR/RM (mod_*) Target “enforcement” is installed by loading mod_shib and mod_eduPerson into Apache (see deploy guide for command details). Mutual configuration between httpd.conf and web.xml links the implementation. mod_shib should coexist with most existing modules and configurations.

13. 13 Deployment: Target Site PKI Requirements The web server’s SSL certificate protects both the SHIRE servlet, and optionally the content. The SHIRE verifies authentication assertions by comparing information to the club registry, and by verifying the signing certificate against the roots.jks keystore of trusted CAs.

14. 14 Deployment: Target Site PKI Requirements The SHAR (in mod_shib) needs an SSL client certificate signed by a club-approved CA to authenticate to AAs. The SSL server certificate may double as a client certificate, unless a key usage extension limits its use. mod_ssl (correctly) rejects such certificates. Some commercial CAs include such a restriction (Thawte), and some don’t (Verisign). The SHAR uses a list of trusted CAs to validate an AA’s server certificate.

15. 15 Deployment: Target Site Resource Manager mod_shib currently provides flexible.htaccess processing. Attributes can be mapped to Require rules and to HTTP headers, including REMOTE_USER. Existing basic-auth sites (i.e. WebCT) can be “hijacked” to use Shibboleth.