Shibboleth: Installation and Deployment

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

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. 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. 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. 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. Installation: Origin SiteLDAP • 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. 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. Deployment: Origin SitePKI 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: <Location "/shibboleth/AA"> SSLVerifyClient optional SSLOptions +ExportCertData </Location> • The allowable client CAs are specified: SSLCACertificateFile /usr/local/shib/etc/ca-bundle.crt

9. Deployment: Origin SitePKI 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. Deployment: Origin SiteClub 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. Installation: Target SiteSHIRE (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. Installation: Target SiteSHIRE/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. Deployment: Target SitePKI 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. Deployment: Target SitePKI 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. Deployment: Target SiteResource 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.