1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
5 <title>Shibboleth Target Deployment Guide</title>
6 <meta http-equiv="Content-Type" content=
7 "text/html; charset=utf-8">
8 <style type="text/css">
12 background-color: #FFFFFF;
30 background-color: #DDDDDD;
31 background-image: none;
35 border-bottom-width: 2px;
36 border-top-width: 2px;
37 border-left-width: 2px;
38 border-right-width: 2px;
42 background-color: #DDDDDD;
43 background-image: none;
49 background-color: #DDDDDD;
50 background-image: none;
59 background-color: #DDDDDD;
60 border: 1px black inset;
61 background-image: none;
69 background-color: #EEEEEE;
70 background-image: none;
72 padding-bottom: 0.5em;
76 border-bottom-width: none;
77 border-top-width: none;
78 border-left-width: 1px;
79 border-right-width: 1px;
86 background-color: #BCBCEE;
87 border: 1px black inset;
88 background-image: none;
96 background-color: #DDDDFF;
97 background-image: none;
99 padding-bottom: 0.5em;
103 border-bottom-width: none;
104 border-top-width: none;
105 border-left-width: 1px;
106 border-right-width: 1px;
113 background-color: #DDDDDD;
114 border: 1px black inset;
115 background-image: none;
124 background-color: #BCBCEE;
125 border: 1px black inset;
126 background-image: none;
132 background-color: #EEEEEE;
137 font-family: monospace;
145 <body link="red" vlink="red" alink="black" bgcolor="white">
147 <h2>Shibboleth Target Deployment Guide</h2>
150 Shibboleth Target Deployment Guide<br>
151 draft-internet2-mace-shibboleth-shib-target-deploy-33.html<br>
152 Nate Klingenstein<br>
154 Comments should be directed to <a href=
155 "mailto:ndk@internet2.edu">ndk@internet2.edu</a>.<br>
157 <h3>This version of the deploy guide is for Shibboleth v1.0. For
158 documentation related to prior versions of Shibboleth, please
159 consult the appropriate branch in the Shibboleth CVS.</h3>
161 <h3>Federations have been abstracted out from the Shibboleth
162 documentation. For further information on using Shibboleth in a
163 federation, refer to the federation guide.</h3>
165 <p>Shibboleth v1.0 is stable and secure enough to deploy in
166 production scenarios. While attempts have been made to include all
167 functionality that would represent a break of interoperability with
168 previous versions in v1.0, be aware that future versions of
169 Shibboleth are likely to be developed and may include further
170 implementation of the architectural document, functional
171 enhancements, and user interface improvements.</p>
173 <h4>Major New Features - 1.0</h4>
174 This new release contains many improvements and enhancements, including:
176 <h5>Federation Support</h5>
179 Federation and trust support has been substantially extended. Federation
180 structures are now defined. The set of metadata collected and managed
181 by each Federation is more fully defined. The configuration values
182 assigned by a Federation are now identified. <br>
185 There is some support for targets to be members of multiple federations;
186 this support will continue to evolve. When a browser user arrives,
187 a target will determine which federation their origin belongs to,
188 and then use the trust fabric associated with that Federation. <br>
191 Better support for flexible and bilateral trust agreements. A key
192 specific to an origin site can be used to vallidate its signature.
197 This version contains a significantly more mature security implementation,
198 and should meet the security requirements of typical sites. <p></p>
205 <li> The Attribute Authority has a powerful new attribute resolver.
206 Simple scenarios (using a string attribute stored in ldap) can be
207 accomplished by merely editing a configuration file. Java classes
208 may still be written for more complex evaluations (eg retrieving information
209 from multiple disparate repositories, and computing the SAML attribute
210 using business rules). This should greatly simplify the process of
211 configuring the AA to support additional general attributes.<br>
217 <li> Significantly more flexibility in configuring targets to ensure
218 robustness. Failover and redundant configurations are now supported.
221 <li>The SHAR may now optionally store its session and attribute
222 cache in a back-end database in addition to the previously available
223 in-memory option. This would allow a site to run an apache server
224 farm, with multiple SHARs, supporting the same set of sessions.
226 <li>Federation supplied files (sites.xml and trust.xml) are now
227 refreshed in a much more robust manner. <br>
232 <li>Attribute acceptance policies have been greatly enhanced, and now
233 supports filtering of attribute values by sites. <br>
235 <li>The SHAR can be configured to request specific attributes from the
239 <h5>Miscellaneous</h5>
241 <li>Origin sites can configure a value to describe the type of authentication
242 mechanism used at the origin site(e.g. password, Kerberos, PKI, etc.).
243 This value is made available on the target side as Shib-Authentication-Method.
246 <li>Various improvements to error handling. Origin sites are now able
247 to supply an "error URL" and contact information to a federation.
248 When a target encounters an error, it can include this information
249 in the error page. <br>
252 <li>Local time string values are now used in log files. <br>
254 <li>Internationalization support has been extended.</li>
257 <p>Before starting, please sign up for all applicable <a href=
258 "http://shibboleth.internet2.edu/shib-misc.html#mailinglist">
259 mailing lists</a>. Announcements pertinent to Shibboleth
260 deployments and developments and resources for deployment
261 assistance can be found here.</p>
263 <p>Please send any questions, concerns, or eventual confusion
265 "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.
266 This should include, but not be limited to, questions about the
267 documentation, undocumented problems, installation or
268 operational issues, and anything else that arises. Please
269 ensure that you have the <a href=
270 "http://shibboleth.internet2.edu/release/shib-download.html">appropriate
271 tarball</a> for your operating system.</p>
278 <h3><a name="TOC"></a>Shibboleth Target -- Table of
285 <h4><a href="#1."><font color="black">Shibboleth
286 Overview</font></a></h4>
289 <li><a href="#1.a."><font color=
290 "black">Origin</font></a></li>
292 <li><a href="#1.b."><font color=
293 "black">Target</font></a></li>
295 <li><a href="#1.c."><font color=
296 "black">WAYF</font></a></li>
298 <li><a href="#1.d."><font color=
299 "black">Federations</font></a></li>
304 <h4><a href="#2."><font color=
305 "black">Planning</font></a></h4>
308 <li><a href="#2.a."><font color=
309 "black">Requirements</font></a></li>
311 <li><a href="#2.b."><font color="black">Join a
312 Federation</font></a></li>
314 <li><a href="#2.c."><font color="black">Security
315 Considerations</font></a></li>
317 <li><a href="#2.d."><font color="black">Server
318 Certs</font></a></li>
320 <li><a href="#2.e."><font color="black">Attribute Release
321 Policies</font></a></li>
323 <li><a href="#2.f."><font color="black">Designate
324 Contacts</font></a></li>
326 <li><a href="#2.g."><font color="black">Browser
327 Requirements</font></a></li>
329 <li><a href="#2.h."><font color=
330 "black">Clocks</font></a></li>
332 <li><a href="#2.i."><font color="black">Other
333 Considerations</font></a></li>
338 <h4><a href="#3."><font color=
339 "black">Installation</font></a></h4>
342 <li><a href="#3.a."><font color="black">Software
343 Requirements</font></a></li>
345 <li><a href="#3.b."><font color="black">Deploy the
346 Shibboleth Package</font></a></li>
348 <li><a href="#3.c."><font color="black">Configure
349 Apache</font></a></li>
354 <h4><a href="#4."><font color="black">Getting
355 Running</font></a></h4>
358 <li><a href="#4.a."><font color="black">Configuring
359 <span class="fixedwidth">shibboleth.ini</span></font></a></li>
361 <li><a href="#4.b."><font color="black">Dynamic Error
362 Page Generation</font></a></li>
364 <li><a href="#4.c."><font color="black">Key Generation
365 and Certificate Installation</font></a></li>
367 <li><a href="#4.d."><font color="black">Protecting
368 Webpages</font></a></li>
370 <li><a href="#4.e."><font color="black">Designing
371 AAP's</font></a></li>
373 <li><a href="#4.f."><font color="black">Using Attributes
374 in Applications</font></a></li>
376 <li><a href="#4.g."><font color="black"><span
377 class="fixedwidth">siterefresh</span></font></a></li>
382 <h4><a href="#5."><font color=
383 "black">Troubleshooting</font></a></h4>
386 <li><a href="#5.a."><font color="black">Basic
387 Testing</font></a></li>
389 <li><a href="#5.b."><font color="black">Common
390 Problems</font></a></li>
399 <h3><a name="1."></a>1. Shibboleth Overview</h3>
401 <p>Shibboleth is a system designed to exchange attributes
402 across realms for the primary purpose of authorization. It
403 provides a secure framework for one organization to transmit
404 attributes about a web-browsing individual across security
405 domains to another institution. In the primary usage case, when
406 a user attempts to access a resource at a remote domain, the
407 user's own home security domain can send certain information
408 about that user to the target site in a trusted exchange. These
409 attributes can then be used by the resource to help determine
410 whether to grant the user access to the resource. The user may
411 have the ability to decide whether to release specific
412 attributes to certain sites by specifying personal Attribute
413 Release Policies (ARP's), effectively preserving privacy while
414 still granting access based on trusted information.</p>
416 <p>When a user first tries to access a resource protected by
417 Shibboleth, they are redirected to a service which asks the
418 user to specify the organization from which they want to
419 authenticate. If the user has not yet locally authenticated to
420 a WebISO service, the user will then be redirected to their
421 home institution's authentication system. After the user
422 authenticates, the Shibboleth components at the local
423 institution will generate a temporary reference to the user,
424 known as a handle, for the individual and send this to the
425 target site. The target site can then use the handle to ask for
426 attributes about this individual. Based on these attributes,
427 the target can decide whether or not to grant access to the
428 resource. The user may then be allowed to access the requested
431 <p>There are several controls on privacy in Shibboleth, and
432 mechanisms are provided to allow users to determine exactly
433 which information about them is released. A user's actual
434 identity isn't necessary for many access control decisions, so
435 privacy often is needlessly compromised. Instead, the resource
436 often utilizes other attributes such as faculty member or member
437 of a certain class. While these are commonly determined using
438 the identity of the user, Shibboleth provides a way to mutually
439 refer to the same principal without revealing that principal's
440 identity. Because the user is initially known to the target site
441 only by a randomly generated temporary handle, if sufficient,
442 the target site might know no more about the user than that the
443 user is a member of the origin organization. This handle should
444 never be used to decide whether or not to grant access, and is
445 intended only as a temporary reference for requesting
448 <h4><a name="1.a."></a>1.a. Origin</h4>
451 <p>There are four primary components to the origin side in
452 Shibboleth: the Attribute Authority (AA), the Handle Service
453 (HS), the directory service, and the local sign-on system
454 (SSO). The AA and HS are provided with Shibboleth, and an
455 open-source WebISO solution Pubcookie is also supplied; the
456 directory is provided by the origin site. Shibboleth is able
457 to interface with a directory exporting an LDAP interface or a
458 SQL database containing user attributes, and is designed such
459 that programming interfaces to other repositories should be
460 readily implemented. Shibboleth relies on standard web server
461 mechanisms to trigger local authentication. A .htaccess file
462 can be easily used to trigger either the local WebISO system
463 or the web server's own Basic Auth mechanism, which will
464 likely utilize an enterprise authentication system, such as
467 <p>From the origin site's point of view, the first contact
468 will be the redirection of a user to the handle service,
469 which will then consult the SSO system to determine whether
470 the user has already been authenticated. If not, then the
471 browser user will be asked to authenticate, and then sent
472 back to the target URL with a handle bundled in an attribute
473 assertion. Next, a request from the Shibboleth Attribute
474 Requester (SHAR) will arrive at the AA which will include the
475 previously mentioned handle. The AA then consults the ARP's
476 for the directory entry corresponding to the handle, queries
477 the directory for these attributes, and releases to the SHAR
478 all attributes the SHAR is entitled to know about that
482 <h4><a name="1.b."></a>1.b. Target</h4>
485 <p>There are three primary components to the target side in
486 Shibboleth: the Shibboleth Indexical Reference Establisher
487 (SHIRE), the Shibboleth Attribute Requester (SHAR), and the
488 resource manager (RM). An implementation of each of these is
489 included in the standard Shibboleth distribution. These
490 components are intended to run on the same web server.</p>
492 <p>From the target's point of view, a browser will hit the RM
493 with a request for a Shibboleth-protected resource. The RM
494 then allows the SHIRE to step in, which will use the WAYF to
495 acquire the name of a handle service to ask about the user.
496 The handle service (HS) will then reply with a SAML
497 authentication assertion containing a handle, which the SHIRE
498 then hands off to the SHAR. The SHAR uses the handle and the
499 supplied address of the corresponding attribute authority
500 (AA) to request all attributes it is allowed to know about
501 the handle. The SHAR performs some basic validation and
502 analysis based on attribute acceptance policies (AAP's).
503 These attributes are then handed off to the RM, which is
504 responsible for using these attributes to decide whether to
508 <h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
511 <p>The WAYF service can be either outsourced and operated by a
512 federation or deployed as part of the SHIRE. It is responsible for
513 allowing a user to associate themself with an institution of their
514 specification, then redirecting the user to the known address for
515 the handle service of that institution.</p>
518 <h4><a name="1.d."></a>1.d. Federations</h4>
521 <p>A federation provides part of the underlying trust required for
522 function of the Shibboleth architecture. A federation in the
523 context of Shibboleth is a group of organizations(universities,
524 corporations, content providers, etc.) who agree to exchange
525 attributes using the SAML/Shibboleth protocols and abide by a
526 common set of policies and practices. In so doing, they must
527 implicitly or explicitly agree to a common set of guidelines.
528 Joining a federation is not explicitly necessary for operation of
529 Shibboleth, but it dramatically expands the number of targets and
530 origins that can interact without defining bilateral agreements
531 between all these parties.</p>
533 <p>A federation can be created in a variety of formats and trust
534 models, but to support Shibboleth, it must provide a certain set
535 of services to federation members. It needs to supply a registry
536 to process applications to the federation and distribute
537 membership information to the origin and target sites. This must
538 include distribution of the PKI components necessary for trust
539 between origins and targets. There also needs to be a set of
540 agreements and best practices defined by the federation governing
541 the exchange, use, and population of attributes before and after
542 transit, and there should be a way to find information on local
543 authentication and authorization practices for federation
553 <h3><a name="2."></a>2. Planning</h3>
555 <p>There are several essential elements that must be present in
556 the environment to ensure Shibboleth functions well, both
557 political and technical. Shibboleth currently runs on a
558 specific range of platforms and web server environments. The
559 SHAR and SHIRE are implemented entirely in C/C++. These are the
560 recommendations and requirements for a successful implementation
561 of a Shibboleth target.</p>
563 <h4><a name="2.a."></a>2.a. Requirements</h4>
566 <p>Shibboleth currently only supports Linux and Solaris. At
567 present, Shibboleth consists of Apache plugins and a separate SHAR
568 process. The plugins use the ONC RPC mechanism to communicate with
569 the SHAR. The target's web servers must be running <a href=
570 "http://http://www.apache.org/dist/httpd/">Apache</a> 1.3.26+, but
571 not Apache 2. More precise technical details are discussed in <a
572 href="#3.a.">3.a</a>.</p>
575 <h4><a name="2.b."></a>2.b. Join a Federation</h4>
578 <p>While it is not necessary for a target or origin to join a
579 federation, doing so greatly facilitates the implementation of
580 multilateral trust relationships. Each federation will have a
581 different application process.</p>
583 <p>For more information on federations, refer to <a href=
584 "#1.d.">1.d</a> or the Shibboleth v1.0 architectural
588 <h4><a name="2.c."></a>2.c. Security Considerations</h4>
591 <p>Shibboleth's protocols and software have been extensively
592 engineered to provide protection against many attacks.
593 However, the most secure protocol can be compromised if it is
594 placed in an insecure environment. To ensure Shibboleth is as
595 secure as possible, there are several recommended security
596 precautions which should be in place at local sites.</p>
600 <p>SSL use is optional for target sites. Federation guidelines
601 should be considered when determining whether to
602 implement SSL, and, in general, SSL should be used for
603 interactions with client machines to provide the
604 necessary authentication and encryption to ensure
605 protection from man-in-the-middle attacks. It is strongly
606 suggested that all password traffic or similarly
607 sensitive data should be SSL-protected. Assessment of the
608 risk tradeoff against possible performance degradation
609 should be performed for all applications.</p>
613 <p>Many other attacks can be made on the several
614 redirection steps that Shibboleth takes to complete
615 attribute transfer. The best protection against this is
616 safeguarding the WAYF service and ensuring that rogue
617 targets and origins are not used, generally by
618 development of the trust model underneath Shibboleth.
619 Shibboleth also leverages DNS for security, which is not
620 uncommon, but attacks concerning bad domain information
621 should be considered.</p>
625 <p>Information regarding origin users is generally
626 provided by the authoritative enterprise directory, and
627 the acceptance of requests from target applications can
628 be carefully restricted to ensure that all requests the
629 SHAR performs are authorized and all information the
630 origin provides is accurate. Use of plaintext passwords
631 is strongly advised against.</p>
635 <p>Server platforms should be properly secured,
636 commensurate with the level that would be expected for a
637 campus' other security services, and cookie stores on
638 client machines should be well protected.</p>
643 <h4><a name="2.d."></a>2.d. Server Certs</h4>
646 <p>In the Shibboleth architecture, the SHAR, HS, and AA must
647 all have various client and/or server certificates for use in
648 signing assertions and creating SSL channels. These should be
649 issued by a commonly accepted CA, which may be stipulated by
650 your federation. After understanding the CA's acceptible to your
651 federations, consult chapter <a href="#4.c.">4.c</a> for
652 information on certificate and key generation.</p>
655 <h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
658 <p>The Attribute Authority maintains a set of rules called
659 Attribute Release Policies (ARP's) that define which
660 attributes are released to which targets. When a browser user
661 tries to access a resource, the SHAR asks the origin site AA
662 to release all the attributes it is allowed to know. The SHAR
663 provides its own name and an optional URL on behalf of which
664 the attribute request is made which can further refine the
665 information the SHAR is allowed to know. The AA processes this
666 request using all applicable ARP's, determines which
667 attributes and values it will release, and then obtains the
668 values actually associated with the browser user. The AA sends
669 these attributes and values back to the SHAR.</p>
671 <p>Targets should work together with expected origin sites to
672 ensure that the sets of attributes that both sites expect to
673 correspond using are congruent.</p>
676 <h4><a name="2.f."></a>2.f. Designate Contacts</h4>
679 <p>Since Shibboleth deals both with daily technical and
680 operational issues and also with contractual issues, a set of
681 contacts should be set up to support the user base and to
682 facilitate interactions with other Shibboleth sites and federation
683 members. It is recommended that at least technical and
684 administrative contacts be designated. Names, titles, e-mail
685 addresses, and phone numbers may all be useful information to
689 <h4><a name="2.g."></a>2.g. Browser Requirements</h4>
692 <p>A primary Shibboleth design consideration was to require
693 very little or no modification to client machines. The only
694 requirement is that a browser is used which supports cookies,
695 redirection and SSL. Browser users will have to perform an
696 additional click to submit the authentication assertion if
697 JavaScript is not functional.</p>
700 <h4><a name="2.h."></a>2.h. Clocks</h4>
703 <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should
704 be run on all web servers. Shibboleth employs a short handle
705 issuance time to protect against replay attacks. Because of
706 this, any significant degree of clock skew can hinder the
707 ability of users to access sites successfully.</p>
710 <h4><a name="2.h."></a>2.i. Other Considerations</h4>
713 <p>Especially for higher education, there are a handful of
714 laws enacted which may have important ramifications on the
715 disclosure of personal information and attributes. Since
716 Shibboleth does not necessarily need to transmit identity, it
717 is an ideal solution for many higher education situations.
718 Nevertheless, all parties within the United States of America
719 are strongly advised to consult the <a href=
720 "http://www.ed.gov/offices/OM/fpco/ferpa/">Family Educational
721 Rights and Privacy Act of 1974(FERPA)</a>, and all other
722 relevant state and federal legislation before deploying
731 <h3><a name="3."></a>3. Installation</h3>
733 <h4><a name="3.a."></a>3.a. Software Requirements</h4>
735 <p>The Shibboleth project makes binary packages available for
736 Solaris and Linux that are precompiled against recent releases
737 of various required libraries such as OpenSSL. It is highly
738 advisable to build from source when using Shibboleth in a
739 production environment in order to permit patching or updating
740 of packages as security holes and bugs are fixed. Building from
741 source is necessary to give you complete control over your
742 deployment platform. The binary packages represent a snapshot in
743 time only. To build from source, see the <span class="fixedwidth">INSTALL.txt</span>
744 files in the root of the OpenSAML and Shibboleth source
748 <b>Operating System:</b>
756 <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
759 <p>Apache must be compiled with mod_so for DSO
760 module support, and must include SSL
761 support (preferably using <span class="fixedwidth">mod_ssl</span>), and
762 EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
763 provides). Shibboleth can coexist with
764 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
765 into the server for use elsewhere, but Shibboleth
766 does not need or use it. The most recent Red Hat
767 RPM (1.3.23-14 as of this writing) is sufficient.
772 <p>On Linux, Shibboleth requires that Apache and
773 Apache-SSL be built with <span
774 class="fixedwidth">libpthread</span>, or loading the
775 <span class="fixedwidth">mod_shibrm</span> or <span
776 class="fixedwidth">mod_shire</span> modules will
777 cause Apache to stop. While RedHat's Apache is
778 compatible, Debian's Apache must be rebuilt with
779 <span class="fixedwidth">libpthread</span>:</p>
781 <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
782 $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
788 "http://shibboleth.internet2.edu/release/shib-download.html">
789 Shibboleth v1.0 Target for RedHat</a></li>
791 <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
792 revision <span class="fixedwidth">i</span> or newer</a></li>
795 libstdc++3-3.0.4-1.i386.rpm and
796 libgcc-3.0.4-1.i386.rpm
799 <p>Shibboleth binaries are currently built with <a href=
800 "http://www.gnu.org/software/gcc/gcc.html">GCC
801 3.04</a>, and require these specific library
802 versions. They are available as RPMs and are
803 available in the RedHat 7.2 updates directory on
805 "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
806 RedHat mirror</a>. They can be installed alongside
807 earlier and later GCC libraries.</p>
811 <li><b>Portions of the <span
812 class="fixedwidth">libphp4</span> Apache plugin are written
813 in C++, as is Shibboleth. There is a known conflict between
814 the PHP extensions <span
815 class="fixedwidth">libpspell.so</span> and <span
816 class="fixedwidth">libsablot.so</span> which will manifest
817 itself as segmentation faults when starting Apache. If a
818 site wants to use <span class="fixedwidth">libphp4.so</span>
819 and Shibboleth at once, then one of the following may be
823 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
826 Rebuild these two modules using
827 the same version of GCC that was used to compile Shibboleth.
839 "ftp://ftp.openssl.org/source/openssl-0.9.7a.tar.gz">
843 <p>The shared library version of OpenSSL is required
844 by Shibboleth. The static libraries may be installed as
845 well if necessary for other applications, but cannot be
846 used within mod_ssl or any other Apache modules.</p>
851 <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
854 <p>Apache must be compiled with mod_so for DSO
855 module support, and must include SSL
856 support (preferably using <span class="fixedwidth">mod_ssl</span>) and EAPI
857 support (which <span class="fixedwidth">mod_ssl</span> requires and
858 provides). Shibboleth can coexist with
859 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
860 into the server for use elsewhere, but Shibboleth
861 does not need or use it.</p>
863 <p><span class="fixedwidth">mod_ssl</span>'s
864 loadable module, <span class="fixedwidth">libssl.so</span>, must be
865 compiled against <span class="fixedwidth">OpenSSL
866 0.9.7a</span>'s shared libraries. Other versions or
867 a statically linked build of <span
868 class="fixedwidth">libssl.so</span> will cause
869 failures such as bus errors when used with
872 <p>To check how OpenSSL was built, run the <span
873 class="fixedwidth">ldd</span> command against <span
874 class="fixedwidth">libssl.so</span> in the Apache
875 <span class="fixedwidth">/libexec/</span> folder and
876 check the output for references to <span
877 class="fixedwidth">libssl.so.0.9.7a</span>. If you
878 see an earlier version mentioned, or no mention of
879 it at all, then <span class="fixedwidth">OpenSSL
880 0.9.7a</span> must be rebuilt with shared libraries
886 "ftp://ftp.sunfreeware.com/pub/freeware/sparc/8/libgcc-3.2.2-sol8-sparc-local.gz">
887 libgcc v3.2.2+ and libstdc++ v3.2.2+</a></li>
890 "http://shibboleth.internet2.edu/release/shib-download.html">
891 Shibboleth v1.0 Target for Solaris</a></li>
893 <li><b>Portions of the <span
894 class="fixedwidth">libphp4</span> Apache plugin are written
895 in C++, as is Shibboleth. There is a known conflict with
896 the PHP extensions <span
897 class="fixedwidth">libpspell.so</span> and <span
898 class="fixedwidth">libsablot.so</span> which will manifest
899 itself as segmentation faults when starting Apache. If a
900 site wants to use <span class="fixedwidth">libphp4.so</span>
901 and Shibboleth at once, then one of the following may be
905 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
908 Rebuild these two modules using the same version of GCC
909 that was used to compile Shibboleth.
919 <p>RedHat 8 ships with Apache 2, which is not supported by
920 Shibboleth. To run Shibboleth under this OS, <a
921 href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
922 must be installed.</p>
925 <p>Apache must be compiled with mod_so for DSO
926 module support, and must include SSL
927 support (preferably using <span class="fixedwidth">mod_ssl</span>), and
928 EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
929 provides). Shibboleth can coexist with
930 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
931 into the server for use elsewhere, but Shibboleth
932 does not need or use it. The most recent Red Hat
933 RPM (1.3.23-14 as of this writing) is sufficient.
938 <p>On Linux, Shibboleth requires that Apache and
939 Apache-SSL be built with <span
940 class="fixedwidth">libpthread</span>, or loading the
941 <span class="fixedwidth">mod_shibrm</span> or <span
942 class="fixedwidth">mod_shire</span> modules will
943 cause Apache to stop. While RedHat's Apache is
944 compatible, Debian's Apache must be rebuilt with
945 <span class="fixedwidth">libpthread</span>:</p>
947 <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
948 $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
955 "http://shibboleth.internet2.edu/release/shib-download.html">
956 Shibboleth 1.0 Target for RedHat</a></li>
958 <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
959 revision <span class="fixedwidth">i</span> or newer</a></li>
962 libstdc++3-3.0.4-1.i386.rpm and
963 libgcc-3.0.4-1.i386.rpm
966 <p>Shibboleth binaries are currently built with <a href=
967 "http://www.gnu.org/software/gcc/gcc.html">GCC
968 3.04</a>, and require these specific library
969 versions. They are available as RPMs and are
970 available in the RedHat 7.2 updates directory on
972 "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
973 RedHat mirror</a>. They can be installed alongside
974 earlier and later GCC libraries.</p>
978 <li><b>Portions of the <span
979 class="fixedwidth">libphp4</span> Apache plugin are written
980 in C++, as is Shibboleth. There is a known conflict with
981 the PHP extensions <span
982 class="fixedwidth">libpspell.so</span> and <span
983 class="fixedwidth">libsablot.so</span> which will manifest
984 itself as segmentation faults when starting Apache. If a
985 site wants to use <span class="fixedwidth">libphp4.so</span>
986 and Shibboleth at once, then one of the following may be
990 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
993 Rebuild these two modules using
994 the same version of GCC that was used to compile Shibboleth.
1003 <h4><a name="3.b."></a>3.b. Deploy the Shibboleth Package</h4>
1006 <p>For the sake of clarity, this deployment guide assumes
1007 that standard directories are used for all installations.
1008 These directories may be changed for local implementations,
1009 but must be done so consistently.</p>
1013 <p>Ensure that you have obtained the proper <a href=
1014 "http://shibboleth.internet2.edu/release/shib-download.html">
1015 tarball</a> for your operating system.</p>
1019 <p>The tarballs expand into <span class="fixedwidth">/opt/shibboleth</span>,
1020 and should be expanded as <span class="fixedwidth">root</span> from <span class="fixedwidth">/</span>.
1021 You should see the following directory structure:</p>
1024 <span class="fixedwidth">$ ls -al<br>
1025 drwxr-xr-x 10 root root 4096 Oct 24 03:54 .<br>
1026 drwxr-xr-x 3 root root 4096 Oct 24 00:37 ..<br>
1027 drwxr-xr-x 2 root root 4096 Oct 24 03:54 bin<br>
1028 drwxr-xr-x 2 root root 4096 Oct 24 03:54 doc<br>
1029 drwxr-xr-x 4 root root 4096 Oct 24 03:54 etc<br>
1030 drwxr-xr-x 13 root root 4096 Oct 24 03:54 include<br>
1031 drwxr-xr-x 4 root root 4096 Oct 24 03:55 lib<br>
1032 drwxr-xr-x 2 root root 4096 Oct 24 03:55 libexec<br>
1033 drwxr-xr-x 4 root root 4096 Oct 24 02:02 share<br>
1040 <h4><a name="3.c."></a>3.c. Configure Apache</h4>
1045 <p>Shibboleth includes configuration directives in the
1046 file <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/apache.config</span>
1047 which must be added to the httpd.conf file used locally.
1048 It is recommended that these directives simply be added
1049 to the end of the existing <span class="fixedwidth">httpd.conf</span> file
1050 rather than trying to merge it in-line;
1051 <a href="#3.c.2.">step 2</a> describes the necessary
1052 modifications to the Apache startup script. The default
1053 configuration will often work, but if customization is
1054 necessary, these options may be modified:</p>
1058 <dd class="attribute">
1059 <span class="fixedwidth">LoadModule <module>
1060 <pathname></span>
1064 <p>Specifies the title and location of the
1065 <span class="fixedwidth">shibrm_module</span> resource manager and
1066 <span class="fixedwidth">shire_module</span> SHIRE modules. These are
1067 installed by default at
1068 <span class="fixedwidth">/opt/shibboleth/libexec/mod_shibrm.so</span>
1070 <span class="fixedwidth">/opt/shibboleth/libexec/mod_shire.so</span></p>
1073 <dd class="attribute">
1074 <span class="fixedwidth">SHIREConfig <pathname></span>
1078 <p>Specifies the <span class="fixedwidth">pathname</span> of the SHIRE's
1079 configuration file. Defaults to
1080 <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span>.</p>
1083 <dd class="attribute"><span class="fixedwidth">SHIREURL <url><br>
1084 <Location <url>><br>
1085 SetHandler <method><br>
1086 </Location></span></dd>
1089 <p>Specifies the <span class="fixedwidth">URL</span> and the
1090 <span class="fixedwidth">method</span> the target uses to handle
1091 requests for Shibboleth-protected resources.
1092 Currently, <span class="fixedwidth">shib-shire-post</span> is the only
1093 available handler <span class="fixedwidth">method</span>.
1094 <span class="fixedwidth">SHIREURL</span> is used by Shibboleth when
1095 re-directing the user to the WAYF and
1096 <span class="fixedwidth"><Location></span> by Apache; for this
1097 reason, both <span class="fixedwidth">URL</span> specifications must
1098 match. Note that the configuration file itself
1099 contains <>'s, and <span class="fixedwidth">Location</span> should
1100 not be replaced.</p>
1102 <p>The referenced <span class="fixedwidth">URL</span> can be either a
1103 partial path or an absolute URL. The partial path
1104 allows each virtual server to use its own
1105 hostname and port in the SHIRE for session cookie
1106 purposes, while the absolute URL forces HTTP
1107 virtual servers to use HTTPS for the SHIRE. Use
1108 of a full <span class="fixedwidth">https://</span> URL is advised.</p>
1111 <dd class="attribute">
1112 <span class="fixedwidth">ShibMapAttribute <attribute-uri>
1113 <HTTP-header> [alias]</span>
1117 <p>Registers attributes to be recognized and maps
1118 them to an authorization <span class="fixedwidth">alias</span> for use
1119 in <span class="fixedwidth">.htaccess</span> files or Location Blocks
1120 with <span class="fixedwidth">require</span> directives.
1121 <span class="fixedwidth">REMOTE_USER</span> is a special case, suggested
1122 for use with <span class="fixedwidth">eduPersonPrincipalName</span>, and
1123 is automatically checked by a <span class="fixedwidth">require
1124 user</span> rule.</p>
1131 <a name="3.c.2."></a>
1133 <p>These modifications must be made to the Apache startup
1136 <p>Add the following environment variables:</p>
1139 <span class="fixedwidth">
1140 SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.ini;
1141 export SHIBCONFIG</span>
1144 <p>If the OpenSSL libraries are not in the system's search
1145 path, they should be added to <span class="fixedwidth">LD_LIBRARY_PATH</span> as
1148 <p>If the SHIBCONFIG environment variable is not
1149 specified, Shibboleth will use
1150 <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span> by
1155 <p>The SHAR must be started before Apache. Among other
1156 methods, this can be done either by creating a separate
1157 SHAR startup script or by modifying Apache's RC script to
1158 start/stop the <span class="fixedwidth">SHAR</span> <b>before</b>
1159 <span class="fixedwidth">httpd</span>. It is suggested that Apache's script be
1160 modified by adding:</p>
1163 <span class="fixedwidth">/opt/shibboleth/bin/shar -f &</span>
1166 <p>Sample <span class="fixedwidth">init.d</span> scripts may be included with
1167 future releases. Ensure that the environment variables
1168 referenced in <a href="#3.c.2">3.c.2</a> are in
1174 <p>The options in <span class="fixedwidth">shibboleth.ini</span> must be
1175 configured as documented in <a href="#4.a.">4.a</a>.
1176 Apache content will then need to be modified for
1177 Shibboleth authentication. This is discussed in <a href=
1178 "#4.d.">4.d</a>. It is recommended that the target then
1179 be tested as detailed in section <a href=
1180 "#5.a.">5.a</a>.</p>
1189 <h3><a name="4."></a>4. Getting Running</h3>
1191 <h4><a name="4.a."></a>4.a. Configuring
1192 <span class="fixedwidth">shibboleth.ini</span></h4>
1195 <p>Most of the configuration for the SHAR, SHIRE, and RM is stored
1196 in the file <span class="fixedwidth">shibboleth.ini</span>. This
1197 file is split into several pre-defined sections. The first
1198 sections, <span class="fixedwidth">general</span>, <span
1199 class="fixedwidth">shire</span>, and <span
1200 class="fixedwidth">shar</span>, define the operational parameters
1201 for the <span class="fixedwidth">SHIRE</span> and <span
1202 class="fixedwidth">SHAR</span>. The <span
1203 class="fixedwidth">general</span> section holds global tags, used
1204 by all pieces. The <span class="fixedwidth">shire</span> and <span
1205 class="fixedwidth">shar</span> sections can override the <span
1206 class="fixedwidth">general</span> tags with SHIRE- or
1207 SHAR-specific configuration. For example, if the SHAR is looking
1208 for a tag, it will look first in the <span
1209 class="fixedwidth">shar</span> section; if it does not find the
1210 tag there, it will proceed to look in the <span
1211 class="fixedwidth">general</span> section. The following
1212 sections, <span class="fixedwidth">metadata_shire</span>, <span
1213 class="fixedwidth">metadata_shar</span>, <span
1214 class="fixedwidth">attributes</span>, and <span
1215 class="fixedwidth">policies</span>, define the trust framework
1216 within the SHIRE and SHAR operate. Example configuration files
1217 are bundled with the Shibboleth distribution.</p>
1219 <p>There is also information that must be configured in
1220 <span class="fixedwidth">/usr/local/apache/conf/httpd.conf</span>; for more
1221 information, refer to <a href="#3.c.2.">3.c</a>.</p>
1223 <p>Information in the logger files referenced by
1224 <span class="fixedwidth">shibboleth.ini</span> may require additional configuration.
1225 It is recommended that after initial installation is
1226 completed, the log level in both files be changed to either
1227 <span class="fixedwidth">INFO</span> or <span class="fixedwidth">WARN</span>.</p>
1229 <p>Fields that are purple are optional; grey fields are
1232 <p><span class="fixedwidth">[general]</span>:</p>
1235 <dd class="attribute">
1236 <span class="fixedwidth">logger = <pathname></span>
1240 <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
1241 configuration file for most Shibboleth events. This
1242 element may also be optionally specified for each of
1243 the components individually. Default logging settings (using local log files)
1244 should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
1245 daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1246 <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
1247 to <span class="fixedwidth">enable logging from remote machines.</span> The
1248 logging level is also defined in the logger configuration.
1249 The configuration format and log levels are similar to that of the
1250 <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
1251 property format.</p>
1254 <dd class="attribute">
1255 <span class="fixedwidth">schemadir = <pathname></span>
1259 <p>Specifies the directory in which the XML schema
1260 files are located; defaults to
1261 <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>.</p>
1264 <dd class="attribute">
1265 <span class="fixedwidth">sharsocket = <pathname></span>
1269 <p>Specifies the location of the socket the SHAR uses to
1270 form connections. Note that if you change this, the SHAR and Apache
1271 should both be restarted immediately, since new Apache child processes will
1272 use the changed value as soon as they start up.</p>
1276 <p>The next segment of the <span class="fixedwidth">[general]</span> configuration
1277 section defines server-specific tags in sections defined by
1278 the server name for use by the SHIRE and RM. For example, if
1279 you have a web server at www.example.edu, you can define a
1280 section <span class="fixedwidth">[www.example.edu]</span> and override global tags
1281 with tags for that server only.</p>
1283 <p>The following table lists the server-specific tags. It is
1284 broken into mandatory tags, and optional tags. Tags in the <span
1285 class="fixedwidth">[general]</span> section correspond to all
1286 servers; to override specific tags on a per-server basis, use
1287 <span class="fixedwidth">[<FQDN>]</span> as the header for a
1290 <span class="fixedwidth">[<general>]</span>:
1294 <dd class="attributeopt">
1295 <span class="fixedwidth">normalizeRequest = <true/false></span>
1298 <dd class="valueopt">
1299 <p>If true, all redirects generated by
1300 <span class="fixedwidth">mod_shire</span> will be created using the virtual
1301 server name assigned to the server containing this
1302 command. If <span class="fixedwidth">false</span>, the browser's supplied
1303 URL is used to compute the redirect back.</p>
1306 <dd class="attributeopt">
1307 <span class="fixedwidth">checkIPAddress = <true/false></span>
1310 <dd class="valueopt">
1311 <p>If <span class="fixedwidth">true</span>, Shibboleth will check client
1312 addresses for impersonation protection. In most
1313 circumstances, this should be enabled to prevent
1314 certain attacks concerning stolen cookies. Defaults
1315 to <span class="fixedwidth">false</span>.</p>
1318 <dd class="attributeopt">
1319 <span class="fixedwidth">supportContact = <e-mail></span>
1322 <dd class="valueopt">
1323 <p>Specifies the e-mail address used in the
1324 generation of error pages.</p>
1327 <dd class="attributeopt">
1328 <span class="fixedwidth">logoLocation = <pathname></span>
1331 <dd class="valueopt">
1332 <p>Specifies the location of the logo used in the
1333 generation of error pages. This logo can be in any
1334 format that the web browser will understand.</p>
1337 <dd class="attribute">
1338 <span class="fixedwidth">wayfURL = <url></span>
1342 <p>Specifies the URL of the WAYF service the user is
1343 redirected to. Federations will generally provide this URL
1344 or provide information on how to locally host WAYF's with
1345 a distributed hosts file.</p>
1348 <dd class="attribute">
1349 <span class="fixedwidth">cookieName = <string></span>
1353 <p>Defines the name to be used for session cookies.</p>
1356 <dd class="attribute">
1357 <span class="fixedwidth">shireSSLOnly = <true/false></span>
1361 <p>If <span class="fixedwidth">true</span>, the SHIRE will reject HTTP
1362 connections that are not SSL-protected. This guards the initial session
1363 sign-on from the browser, but does not preclude non-SSL content. Use of
1364 SSL is strongly recommended; see section <a href=
1365 "#2.c.">2.c</a> for more information.</p>
1368 <dd class="attribute">
1369 <span class="fixedwidth">shireError = <pathname></span>
1373 <p>Specifies the location of the template for the
1374 error page generated when there is an error
1375 re-directing the user to the WAYF or processing a
1379 <dd class="attribute">
1380 <span class="fixedwidth">rmError = <pathname></span>
1384 <p>Specifies the location of the template for the
1385 error page generated if internal errors occur in the
1389 <dd class="attribute">
1390 <span class="fixedwidth">accessError = <pathname></span>
1394 <p>Specifies the location of the template for the
1395 page displayed to users when access to a protected
1396 resource is denied by the RM.</p>
1400 <span class="fixedwidth">[shire]</span>:
1403 <dd class="attribute">
1404 <span class="fixedwidth">logger = <pathname></span>
1408 <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
1409 configuration file for most Shibboleth events. This
1410 element may also be optionally specified for each of
1411 the components individually. Default logging settings (using local log files)
1412 should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
1413 daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1414 <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
1415 to <span class="fixedwidth">enable logging from remote machines.</span> The
1416 logging level is also defined in the logger configuration.
1417 The configuration format and log levels are similar to that of the
1418 <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
1419 property format.</p>
1422 <dd class="attributeopt">
1423 <span class="fixedwidth">aap-uri = <uri></span>
1426 <dd class="valueopt">
1427 <p>Specifies the URI of an attribute acceptance policy XML
1428 file. Attributes must be listed in the <span
1429 class="fixedwidth">aap-uri</span> file if they are to be
1430 visible to the Apache server. Unlisted or rejected attributes are
1431 filtered out and hidden from the web server (but also see the
1432 <b>ShibExportAssertion</b> Apache command).
1433 For more information, refer to section <a href="#4.e.">4.e</a>.</p>
1436 <dd class="attributeopt">
1437 <span class="fixedwidth">metadata = <tag></span>
1440 <dd class="valueopt">
1441 <p>Specifies the tag that defines the section of <span
1442 class="fixedwidth">shibboleth.ini</span> the SHIRE should
1443 use to acquire its metadata. The SHIRE does not need trust
1444 metadata, and so generally it will only need sites data to
1445 enforce attribute policies like scope limitations(e.g. MIT
1446 not asserting @brown.edu attributes.)</p>
1450 <span class="fixedwidth">[shar]</span>:
1453 <dd class="attribute">
1454 <span class="fixedwidth">logger = <pathname></span>
1458 <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
1459 configuration file for most Shibboleth events. This
1460 element may also be optionally specified for each of
1461 the components individually. Default logging settings (using local log files)
1462 should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
1463 daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1464 <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
1465 to <span class="fixedwidth">enable logging from remote machines.</span> The
1466 logging level is also defined in the logger configuration.
1467 The configuration format and log levels are similar to that of the
1468 <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
1469 property format.</p>
1472 <dd class="attributeopt">
1473 <span class="fixedwidth">metadata = <tag></span>
1476 <dd class="valueopt">
1477 <p>Specifies the tag that defines the section of <span
1478 class="fixedwidth">shibboleth.ini</span> the SHAR should
1479 use to acquire its site and trust metadata.</p>
1482 <dd class="attributeopt">
1483 <span class="fixedwidth">certFile = <pathname></span>
1486 <dd class="valueopt">
1487 <p>Specifies the location of the PEM-format certificate used by
1488 the SHAR to communicate in authenticated fashion with
1489 origin site Attribute Authorities.</p>
1492 <dd class="attributeopt">
1493 <span class="fixedwidth">keyFile = <pathname></span>
1496 <dd class="valueopt">
1497 <p>Specifies the location of the PEM-format private key used by
1498 the SHAR to communicate in authenticated fashion with
1499 origin site Attribute Authorities.</p>
1502 <dd class="attributeopt">
1503 <span class="fixedwidth">keyPass = <password></span>
1506 <dd class="valueopt">
1507 <p>Specifies the <span class="fixedwidth">password</span> used to access the
1508 <span class="fixedwidth">keyFile</span>, if any.</p>
1511 <dd class="attribute">
1512 <span class="fixedwidth">calist = <pathname></span>
1516 <p>Specifies a single file of PEM-format certificates containing
1517 the root CAs the SHAR will consider to be valid signers of AA server
1518 certificates. Currently applies globally to all communication with AAs.</p>
1521 <dd class="attribute">
1522 <span class="fixedwidth">AATimeout = <seconds></span>
1526 <p>Specifies the number of seconds that the SHAR will wait
1527 for attributes to be sent from an AA. Defaults to <span
1528 class="fixedwidth">60</span>.</p>
1531 <dd class="attribute">
1532 <span class="fixedwidth">AAConnectTimeout = <seconds></span>
1536 <p>Specifies the number of seconds that the SHAR will wait
1537 for a connection to be established with an AA.
1538 Defaults to <span class="fixedwidth">30</span>.</p>
1541 <dd class="attribute">
1542 <span class="fixedwidth">cacheType = <method></span>
1546 <p>Specifies the method used by the SHAR to cache received
1547 attributes. The default is <span
1548 class="fixedwidth">memory</span>, which indicates that
1549 the SHAR should store received attributes in its memory.
1550 Another option is <span class="fixedwidth">mysql</span>,
1551 which will use the MySQL Credential Cache. The steps to using this are described
1552 in the MySQL Credential Cache guide.</p>
1555 <dd class="attribute">
1556 <span class="fixedwidth">cacheClean = <seconds></span>
1560 <p>Specifies the duration in seconds between cleanups of
1561 the SHAR's cached but expired attributes. Defaults to <span
1562 class="fixedwidth">300</span>, or 5 minutes.</p>
1565 <dd class="attribute">
1566 <span class="fixedwidth">cacheTimeout = <seconds></span>
1570 <p>Specifies the duration in <span
1571 class="fixedwidth">seconds</span> that must elapse
1572 between user accesses before that user's session is
1573 destroyed, including the associated handle and all
1574 cached attributes. Defaults to <span
1575 class="fixedwidth">28800</span> seconds, or 8 hours.</p>
1579 <p><span class="fixedwidth">[metadata]</span> sections must be
1580 created and named in accordance with the value of the <span
1581 class="fixedwidth">metadata</span> parameter in the <span
1582 class="fixedwidth">[shire]</span> and <span
1583 class="fixedwidth">[shar]</span> sections. Metadata sections may
1584 be shared or defined for each component. Two providers are
1585 supported by Shibboleth, but additional providers may be
1586 specified with name/value pairs consisting of <span
1587 class="fixedwidth"><metadata provider type>=<source></span>.</p>
1589 <p><span class="fixedwidth">[<metadata>]</span>:</p>
1592 <dd class="attributelong">
1593 <span class="fixedwidth">edu.internet2.middleware.shibboleth.metadata.XML = <pathname></span>
1597 <p>Specifies the location of the file to load site
1598 metadata from. This will often be a <span
1599 class="fixedwidth">sites.xml</span> file stored locally,
1600 and may be used by both the SHIRE and SHAR.</p>
1602 <p>Shibboleth provides a simple utility called <span
1603 class="fixedwidth">siterefresh</span> for updating the
1604 metadata file as described in section <a
1605 href="#4.g.">4.g</a>.</p>
1608 <dd class="attributelong">
1609 <span class="fixedwidth">edu.internet2.middleware.shibboleth.trust.XML = <pathname></span>
1613 <p>Specifies the location of the trust database of
1614 certificates and/or CA roots used by the SHAR during
1615 session initiation. The SHIRE module generally does not need trust
1620 <p>In order for an attribute to be used by Shibboleth, it must be
1621 recognized as valid by the SHAR and implemented with any specific
1622 rules for how to understand and express its value based on the XML
1623 from the AA. Additional string-valued attributes may be added to
1624 the SHAR using the <span class="fixedwidth">[attributes]</span>
1627 <p><span class="fixedwidth">[attributes]</span>:</p>
1630 <dd class="attribute">
1631 <span class="fixedwidth"><attribute_URI>=<type></span>
1635 <p>Attribute names are URI's that are assigned by the
1636 parties standardizing the attribute. Frequently, a
1637 federation or standard object class may define these URI's.
1638 The attribute type may be either <span
1639 class="fixedwidth">scoped</span> or <span
1640 class="fixedwidth">simple</span>, which defines how
1641 the attribute is processed as described in section <a
1642 href="#4.e.">4.e</a>.</p>
1646 <p>The <span class="fixedwidth">[policies]</span> section contains the policy URI
1647 values that control acceptance of assertions from origin
1648 sites. This may eventually have multiple elements associated
1649 it for targets that are members of multiple federations.</p>
1651 <p><span class="fixedwidth">[policies]</span>:</p>
1654 <dd class="attribute">
1655 <span class="fixedwidth"><federation> = <URI></span>
1659 <p>The name of the <span
1660 class="fixedwidth">federation</span> and its
1661 associated policy <span class="fixedwidth">URI</span>.
1662 These URI's will be provided by federations.</p>
1664 <p>This set of URI values is matched against the SAML
1665 <span class="fixedwidth">Audience</span> fields of
1666 assertions received from HS's and AA's. One of the
1667 URI's specified by the origin in <span
1668 class="fixedwidth">edu.internet2.middleware.shibboleth.audiences</span>
1669 must match one of these URIs or the
1670 assertion will not be accepted by design.</p>
1674 <p>Additional sections for individual servers may be defined with
1675 either parameters overriding those found in <span
1676 class="fixedwidth">[general]</span>, or the following additional
1679 <p><span class="fixedwidth">[<FQDN>]</span>:</p>
1682 <dd class="attributeopt">
1683 <span class="fixedwidth">requestAttributes = <attr1> <attr2>
1684 <attr3>...</span>
1687 <dd class="valueopt">
1688 <p>Specifies a space-delimited list of attributes named by
1689 URI that the SHAR will request of an AA. If the parameter
1690 does not exist or is null, then the SHAR will receive all
1691 attributes the AA is willing to release to it.</p>
1697 <h4><a name="4.b."></a>4.b. Dynamic Error Page Generation</h4>
1700 <p>Shibboleth supports the dynamic generation of information
1701 in error pages referenced by <span class="fixedwidth">shibboleth.ini</span>. The
1702 Shib Target employs a special Markup Language Processor to
1703 insert special tags into the generated HTML. The parser will
1704 read the error file looking for any tag that looks like:</p>
1707 <span class="fixedwidth"><shibmlp tag-name /></span>
1710 <p>Shibboleth will replace <span class="fixedwidth">tag-name</span> with the
1711 appropriate markup tag from the table below:</p>
1714 <dd class="attribute"><span class="fixedwidth">supportContact</span></dd>
1716 <dd class="value">The value of the <span class="fixedwidth">supportContact</span> for this
1719 <dd class="attribute"><span class="fixedwidth">logoLocation</span></dd>
1721 <dd class="value">The value of the <span
1722 class="fixedwidth">logoLocation</span> for this server. This
1723 is used to fill in the template error page only; if a custom
1724 error page is created, then the image may be linked to
1725 statically by the page itself.</dd>
1727 <dd class="attribute"><span class="fixedwidth">requestURL</span></dd>
1729 <dd class="value">The user's requested URL.</dd>
1731 <dd class="attribute"><span class="fixedwidth">errorType</span></dd>
1733 <dd class="value">The type of error.</dd>
1735 <dd class="attribute"><span class="fixedwidth">errorText</span></dd>
1737 <dd class="value">The actual error message.</dd>
1739 <dd class="attribute"><span class="fixedwidth">errorDesc</span></dd>
1741 <dd class="value">A textual description of the error intended for human
1744 <dd class="attribute"><span class="fixedwidth">originContactName</span></dd>
1746 <dd class="value">The contact name for the origin site provided by that
1747 site's metadata.</dd>
1749 <dd class="attribute"><span class="fixedwidth">originContactEmail</span></dd>
1751 <dd class="value">The contact email address for the origin site provided by that
1752 site's metadata.</dd>
1754 <dd class="attribute"><span class="fixedwidth">originErrorURL</span></dd>
1756 <dd class="value">The URL of an error handling page for the origin site
1757 provided by that site's metadata.</dd>
1760 <p>This configuration is only for Apache servers, and is only
1761 used by resources protected by Shibboleth. See section <a
1762 href= "#4.d.">4.d</a>.</p>
1764 <p>Sample error templates for different kinds of errors are
1765 included in the Shibboleth distribution, and can be triggered
1766 by anything that will cause Shibboleth to be unable to make an
1767 authorization decision, including a bad sites file, certificate chain,
1768 or skewed clock.</p>
1770 <p><b>You should edit these templates, provide or remove style sheets and
1771 images, and otherwise customize these templates to suit the user experience
1772 you want your users to have when errors occur.</b></p>
1776 <h4><a name="4.c."></a>4.c. Key Generation and Certificate
1780 <p>The only target component that must have a private key and
1781 certificate is the SHAR. While the target server itself should support
1782 SSL in most cases, it is mandatory for the SHAR to
1783 authenticate when contacting an AA, and it must therefore be
1784 given a key and an SSL client certificate. It is permissible
1785 for the SHAR to use the same keypair and certificate used by
1786 the target server itself, provided the certificate is signed
1787 by a CA accepted by the community of sites.</p>
1789 <p>The certificate and key should be placed based on whether
1790 they will also be used for Apache's server cert. If they will
1791 be used as a server certificate as well, they should probably
1792 be in the Apache tree in the usual <span class="fixedwidth">mod_ssl</span> spot, and
1793 the SHAR can read them from there. If the SHAR is not running
1794 as <span class="fixedwidth">root</span>, permissions might need to be changed to
1795 allow this access. If the certificate and key will only be
1796 used for the SHAR, they can be put in the same folder with the
1797 <span class="fixedwidth">shibboleth.ini</span> file.</p>
1799 <p>The SHAR is assigned a key and a certificate using
1800 shibboleth.ini's <span class="fixedwidth">certFile</span>,
1801 <span class="fixedwidth">keyFile</span> and
1802 <span class="fixedwidth">keyPass</span>, described in <a href="#4.a.">4.a</a>. These
1803 files must currently be in PEM format. OpenSSL commands to
1804 generate a new keypair and a certificate request are shown
1805 here, assuming RSA keys are to be used:</p>
1808 <span class="fixedwidth">$ openssl genrsa -des3 -out ssl.key 2048<br>
1809 $ openssl req -new -key ssl.key -out ssl.csr</span>
1812 <p>The signed certificate file returned by the CA should be
1813 usable directly, or can be converted to PEM format using the
1814 <span class="fixedwidth">openssl x509</span> command.</p>
1816 <p>The key and certificate files can be placed anywhere,
1817 though in or beneath the <span class="fixedwidth">/usr/local/apache/conf</span>
1818 directory is a good choice. The Apache child processes,
1819 often running as <span class="fixedwidth">nobody</span>, must be able to read them
1820 while the server is running, which may require permission
1823 <p>This particularly applies when sharing the key and
1824 certificate used by mod_ssl, which are only readable by root
1825 by default. The password, if any, must be placed in the conf
1826 file, since the module cannot prompt for it as the initial
1827 startup of mod_ssl can. The issues surrounding how to
1828 securely obtain a key while running as <span class="fixedwidth">nobody</span>
1829 may be addressed in a later release. Since the password will be
1830 stored in clear text in a frequently examined file, it is
1831 suggested to use a password not used elsewhere.</p>
1833 <p>Finally, the <span class="fixedwidth">calist</span> command provides the SHAR
1834 with a set of CA roots to trust when validating AA server
1835 certificates. In all cases, the SHAR verifies that the
1836 certificate's Subject CN equals the AA's hostname, but the CA root
1837 bundle restricts the accepted signers to those permitted by
1838 the SHAR. The parameter can be omitted to skip such validation.</p>
1841 <h4><a name="4.d."></a>4.d. Protecting Webpages</h4>
1844 <p>Protection of webpages is primarily achieved through
1845 "mapping" attributes provided by an AA to a localized
1846 vocabulary for authorization rules. Each attribute can be
1847 mapped using the <span class="fixedwidth">ShibMapAttribute</span> command to an HTTP
1848 header name where it can subsequently be accessed by
1849 applications, and optionally to an <span class="fixedwidth">alias</span> that can be
1850 used in a <span class="fixedwidth">Require</span> command to search for a matching
1851 value. This mapping command must be in <span class="fixedwidth">httpd.conf</span>,
1852 while the rest of the commands described here appear in
1853 content-specific configuration or <span class="fixedwidth">.htaccess</span>
1856 <p>Any of the typical ways of protecting content may be used
1857 (.htaccess, Directory, Location, Files, etc.). There are two
1858 ways to trigger Shibboleth authentication: specifying an
1859 <span class="fixedwidth">AuthType</span> of <span class="fixedwidth">shibboleth</span> to use Shibboleth
1860 directly, or specifying <span class="fixedwidth">ShibBasicHijack On</span> to
1861 process existing .htaccess files using Shibboleth instead.
1862 Support for authorization consists of mod_auth-style require
1863 directives, as well as support for mod_auth group files.</p>
1865 <p>A complete list of the directives and their values is
1869 <dd class="attribute">
1870 <span class="fixedwidth">AuthType <string></span>
1874 <p>Use <span class="fixedwidth">shibboleth</span> for direct invocation, or
1875 <span class="fixedwidth">Basic</span> plus the <span class="fixedwidth">ShibBasicHijack On</span>
1876 option described below.</p>
1879 <dd class="attribute">
1880 <span class="fixedwidth">ShibSSLOnly<on/off></span>
1884 <p>Controls whether Shibboleth will reject non-SSL
1885 requests from clients. Defaults to <span class="fixedwidth">off</span>.</p>
1888 <dd class="attribute">
1889 <span class="fixedwidth">ShibBasicHijack <on/off></span>
1893 <p>Controls whether Shibboleth should or should not
1894 ignore requests for <span class="fixedwidth">AuthType Basic</span>. Defaults
1895 to <span class="fixedwidth">off</span>.</p>
1898 <dd class="attribute">
1899 <span class="fixedwidth">ShibExportAssertion <on/off></span>
1903 <p>Controls whether the SAML attribute assertion
1904 provided by the AA is exported in a base64-encoded
1905 HTTP header, <span class="fixedwidth">Shib-Attributes</span>. Defaults to
1906 <span class="fixedwidth">off</span>. While this does require parsing the
1907 raw XML, it also permits an application to see attributes that may have
1908 been filtered by an AAP, or to forward the SAML assertion to a third party.</p>
1911 <dd class="attribute">
1912 <span class="fixedwidth">ShibAuthLifetime <seconds></span>
1916 <p>Sets the maximum lifetime in seconds that a user
1917 session can survive. Omission or zero results in
1918 arbitrary session lifetime.</p>
1921 <dd class="attribute">
1922 <span class="fixedwidth">ShibAuthTimeout <seconds></span>
1926 <p>Sets the maximum number of seconds without any
1927 user activity that a session will remain alive. After
1928 <span class="fixedwidth">seconds</span> seconds without activity, the
1929 session is considered dead. Omission or <span class="fixedwidth">0</span>
1930 results in an arbitrary session timeout.</p>
1933 <dd class="attribute">
1934 <span class="fixedwidth">AuthGroupFile <pathname></span>
1938 <p>Same as mod_auth; collects EPPN's into a named
1939 group for access control. Note that mod_auth will not
1940 support group files when mod_shibrm is loaded, since
1941 they share the same command.</p>
1946 "http://httpd.apache.org/docs/mod/core.html#require">This
1947 is implemented</a> by placing a <span class="fixedwidth">.htaccess</span>
1948 file that references an <span class="fixedwidth">AuthGroupFile</span> stored
1949 at <span class="fixedwidth">/path</span>:</p>
1952 <span class="fixedwidth">authgroupfile /path<br>
1953 require group workgroup</span>
1956 <p>Note that an <a href=
1957 "http://httpd.apache.org/docs/mod/mod_auth.html#authgroupfile">
1958 AuthGroupFile</a> used by Shibboleth would resemble
1959 <span class="fixedwidth">workgroup: joe@example.edu, jane@demo.edu,
1960 jim@sample.edu</span>.</p>
1964 <dd class="attribute">
1965 <span class="fixedwidth">Require <string></span>
1969 <p>Enforce authorization using one of the following methods.</p>
1974 <span class="fixedwidth">valid-user</span>
1977 <p>Any Shibboleth user from a trusted origin site is accepted,
1978 even if no actual attributes are received. This is a very minimal
1979 kind of policy, but is useful for testing or for deferring real
1980 policy to an application.</p>
1984 <span class="fixedwidth">user</span>
1987 <p>A space-delimited list of EPPN values, provided that the
1988 <span class="fixedwidth">urn:mace:dir:attribute-def:eduPersonPrincipalName</span>
1989 attribute has been mapped to the
1990 <span class="fixedwidth">REMOTE_USER</span> header (as per the earlier
1991 example configuration commands). Actually, any attribute can be mapped to
1992 REMOTE_USER, even if this doesn't always make sense.</p>
1997 <span class="fixedwidth">group</span>
2000 <p>A space-delimited list of group names defined
2001 within <span class="fixedwidth">AuthGroupFile</span> files, again
2002 provided that a mapping to <span class="fixedwidth">REMOTE_USER</span>
2008 <span class="fixedwidth"><alias></span>
2011 <p>An arbitrary rule tag that matches an alias
2012 defined in a <span class="fixedwidth">ShibMapAttribute</span> server
2013 command. The rule value is a space-delimited
2014 list of attribute values, whose format depends on
2015 the attribute in question (e.g. an affiliation
2016 rule might look like <span class="fixedwidth">require affiliation
2017 staff@osu.edu faculty@mit.edu</span>).</p>
2022 <p>Additionally, for <span class="fixedwidth">user</span> and
2023 <span class="fixedwidth"><alias></span>-based rules, if a tilde character
2024 is placed immediately following <span class="fixedwidth">user</span> or
2025 <span class="fixedwidth"><alias></span>, the expressions that follow are
2026 treated as regular expressions.</p>
2028 <p>For example, the regular expression AAP <span
2029 class="fixedwidth">require affiliation ~
2030 ^member@.+\.edu$</span> would evaluate to allowing
2031 anyone with an <span
2032 class="fixedwidth">eduPersonScopedAffiliation</span> of
2033 <span class="fixedwidth">member</span> from a .edu
2041 <h4><a name="4.e."></a>4.e. Designing AAP's</h4>
2044 <p>Shibboleth allows a user and a site to release a varying
2045 set of attributes to a destination site, and does not impose
2046 restrictions on the kinds of attribute information provided
2047 by an AA. Target implementations must also be prepared to
2048 examine the attributes they receive and filter them based on
2049 policies about what information to permit an origin site to
2050 assert about its users.</p>
2052 <p>Attribute acceptance is the process of filtering attribute
2053 values before passing them on to a resource manager, such as
2054 the <span class="fixedwidth">mod_shibrm</span> module. Data blocked by AAP filters
2055 will not be passed to the CGI environment or used when
2056 enforcing <span class="fixedwidth">.htaccess</span> rules.
2057 Note that the attribute assertion exported to the
2058 <span class="fixedwidth">Shib-Attributes</span> header is unfiltered.</p>
2060 <p>The Shibboleth distribution supports <span class="fixedwidth">scoped</span> and
2061 <span class="fixedwidth">simple</span> filtering policies for different kinds of
2064 <p><b>An essential part of the Shibboleth trust fabric is ensuring
2065 that sites only assert attributes for domains for which they are
2066 considered authoritative by the target. Typically, this means
2067 that Brown University will be trusted to assert attributes only
2068 scoped to <span class="fixedwidth">brown.edu</span>. Unless
2069 there are very specific circumstances requiring this restriction
2070 be removed, it is strongly encouraged that such policies be in place.</b></p>
2074 <p>Scoped attributes are a special kind of attribute whose
2075 values are a combination of a <span class="fixedwidth">value</span> and a
2076 <span class="fixedwidth">scope</span>, or <span class="fixedwidth">context</span> for the value. An
2077 example is <span class="fixedwidth">eduPersonScopedAffiliation</span>, which adds a
2078 scope to the defined set of <span class="fixedwidth">eduPersonAffiliation</span>
2079 values, such as <span class="fixedwidth">student</span>, <span class="fixedwidth">member</span>, or
2080 <span class="fixedwidth">faculty</span>. Scopes are expressed as DNS domains and
2083 <p>Any <span class="fixedwidth">scoped</span> attribute can be
2084 scoped only to the origin site's permitted domains. These
2085 domains are listed in the sites file that provides trust
2086 information to the system. Domains can be explicit or
2087 regular expressions, and can be changed by a target to meet
2088 its needs if a local version of the file is created. Thus,
2089 attribute acceptance processing for <span class="fixedwidth">scoped</span>
2090 attributes is based on the sites file, in addition to the mechanism described
2091 below for <span class="fixedwidth">simple</span> attributes.</p>
2096 <p>Simple attributes are attributes whose value is expressed
2097 in XML as a Text node; that is, the value is just a string.
2098 Multiple values are permitted.
2099 <span class="fixedwidth">eduPersonEntitlement</span>, in which the values are URIs,
2100 is one example of a simple attribute.</p>
2101 <p>In this release, simple (and scoped) attribute acceptance is
2102 controlled with an external policy file written in XML. The
2103 schema for the file is described by the
2104 <span class="fixedwidth">shibboleth.xsd</span> schema, and an example file is
2105 included, <span class="fixedwidth">AAP.xml</span>. If the <span class="fixedwidth">aap-uri</span>
2106 parameter in the <span class="fixedwidth">shibboleth.ini</span> file is left out,
2107 then no policy is applied, and no filtering is done.
2108 Otherwise, the rules encoded in the file are used.</p>
2109 <p>The policy is a default-deny algorithm that requires
2110 permissible attributes and values be listed explicitly. That
2111 is, an empty file permits nothing. Each attribute to be
2112 permitted must be listed in the file by name in an
2113 <span class="fixedwidth"><AttributeRule></span>. Each such rule is a
2114 collection of <span class="fixedwidth"><SiteRule></span> elements along with
2115 an optional <span class="fixedwidth"><AnySite></span> default rule. In turn
2116 each site rule is a set of <span class="fixedwidth"><Value></span> rules that
2117 specify matches to permit, either literal or regular
2121 <p>A syntax summary follows:</p>
2124 <p><span class="fixedwidth"><AttributeAcceptancePolicy</span></p>
2125 <blockquote>The top level element in the
2128 <p><span class="fixedwidth"><AttributeRule Name="attribute
2129 URI"></span></p>
2130 <blockquote>Specifies a rule for an attribute, named with
2131 its URI.</blockquote>
2133 <p><span class="fixedwidth"><AnySite></span></p>
2134 <blockquote>Specifies a rule that always applies to the
2135 attribute, regardless of the asserting AA.</blockquote>
2137 <p><span class="fixedwidth"><SiteRule
2138 Name="site.domain.name"></span></p>
2139 <blockquote>A rule that applies to the origin site AA
2140 corresponding to the domain name.</blockquote>
2142 <p><span class="fixedwidth"><AnyValue></span></p>
2143 <blockquote>Specifies a rule that always applies to the
2144 attribute and site, regardless of the value(s).</blockquote>
2146 <p><span class="fixedwidth"><Value Type="type"></span></p>
2147 <blockquote>Specifies a value to permit, either directly
2148 using <span class="fixedwidth">type</span> <span class="fixedwidth">literal</span>, or using a set of
2149 matching expressions as <span class="fixedwidth">type</span> <span class="fixedwidth">regexp</span>.
2150 <span class="fixedwidth">literal</span> is the default if <span class="fixedwidth">Type</span> is not
2151 specified.</blockquote>
2155 <p>The regular expression syntax is a subset of the usual
2156 Perl and Unix syntaxes that is described in the XML Schema
2157 specification by the W3C. Most typical expressions should
2158 work. Be sure to anchor them using <span class="fixedwidth">^</span> and <span class="fixedwidth">$</span>
2159 to avoid unintentional matches midstring.</p>
2161 <p>Note that the AAP rules described in this section are not
2162 part of the Shibboleth architecture and are simply one
2163 possible set of approaches provided by this implementation.</p>
2166 <h4><a name="4.f."></a>4.f. Using Attributes in
2170 <p>Apart from the simple RM functionality provided, attribute
2171 information may be made available directly to applications
2172 via the standard practice of creating custom HTTP request
2173 headers before passing control to the application.
2174 Applications should make no assumption about the presence of
2175 specific attributes for their use unless they have intimate
2176 knowledge of the attribute release policies in place.</p>
2178 <p>The <span class="fixedwidth">ShibMapAttribute</span> directive controls this
2179 interface, and maps a Shibboleth attribute (identified by an
2180 unambiguous URI) to a header name, such as
2181 <span class="fixedwidth">Shib-EP-Affiliation</span>. Using that example, any values
2182 of the mapped attribute will be placed in that header,
2183 delimited by spaces. An application that uses a CGI-like
2184 syntax to access the header will find the values in the
2185 <span class="fixedwidth">HTTP_SHIB_EP_AFFILIATION</span> variable. Using the
2186 command, any attribute can be placed in any header, to drive
2187 legacy applications that expect information in a particular
2190 <p>The <span class="fixedwidth">REMOTE_USER</span> variable is a special case that
2191 is generally populated automatically by the web server based
2192 on an internal piece of data that represents the user's
2193 <span class="fixedwidth">username</span>. Unlike many authentication modules,
2194 Shibboleth does not guarantee that <span class="fixedwidth">REMOTE_USER</span> will
2195 have any value. If it does, it is set solely based on a
2196 <span class="fixedwidth">ShibMapAttribute</span> command. For many purposes, the
2197 <span class="fixedwidth">urn:mace:dir:attribute-def:eduPersonPrincipalName</span>
2198 attribute should be mapped to <span class="fixedwidth">REMOTE_USER</span>. Even so,
2199 EPPN may not be provided by the AA, and <span class="fixedwidth">REMOTE_USER</span>
2200 might still be empty.</p>
2202 <p>The <span class="fixedwidth">Shib-Origin-Site</span> variable will contain the
2203 unique name/identifier of the origin site of the user. Some applications may use this
2204 to lookup additional policy or application data. It normally takes the form of a URI
2205 but could be any string.</p>
2207 <p>Finally, the <span class="fixedwidth">ShibExportAssertion</span> flag instructs
2208 the module to place the entire XML message containing the
2209 SAML attribute information from the AA into a base64-encoded
2210 header called <span class="fixedwidth">Shib-Attributes</span>. This is a raw
2211 interface that provides an application with the entire AA
2212 response, and is not a filtered view based on any attribute
2213 acceptance rules or even based on what attributes are
2214 recognized by the target. What was sent is what you see.</p>
2217 <h4><a name="4.g."></a>4.g. <span
2218 class="fixedwidth">siterefresh</span></h4>
2221 <p>Shibboleth provides a simple tool called <span
2222 class="fixedwidth">siterefresh</span> in the <span
2223 class="fixedwidth">/opt/shibboleth/bin</span> folder of the
2224 distribution to maintain metadata files referenced by <span
2225 class="fixedwidth">shibboleth.ini</span>. It will return 0 on
2226 success and a negative number on failure and log errors to <span
2227 class="fixedwidth">stderr</span>. If the data in the new metadata
2228 file is bad or the signature is invalid, the existing copy is
2229 kept. The SHAR and SHIRE stat the file each time the data is
2230 used, allowing them to detect and utilize updates in real-time
2233 <p><span class="fixedwidth">siterefresh</span> takes the following
2234 command-line parameters:</p>
2237 <dd class="attribute">
2238 <span class="fixedwidth">--url <URL></span>
2242 <p>Specifies the <span class="fixedwidth">URL</span> of the
2243 remote metadata file to update the local file.</p>
2246 <dd class="attribute">
2247 <span class="fixedwidth">--out <pathname></span>
2251 <p>Specifies the local file to write the new metadata to.</p>
2254 <dd class="attributeopt">
2255 <span class="fixedwidth">--cert <pathname></span>
2258 <dd class="valueopt">
2259 <p>Specifies the location of a certificate stored in <span
2260 class="fixedwidth">PEM</span> format used to validate the
2261 signature of the metadata file. Since much of Shibboleth's
2262 trust flows from this metadata file, this option is highly
2266 <dd class="attributeopt">
2267 <span class="fixedwidth">--schema <pathname></span>
2270 <dd class="valueopt">
2271 <p>Optionally defines a base path for schemas. Defaults to
2273 class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>.</p>
2277 <p>A complete command issued to <span
2278 class="fixedwidth">siterefresh</span> would take the form:</p>
2280 <blockquote><span class="fixedwidth">
2281 /opt/shibboleth/bin/siterefresh --out sites.xml --cert internet2.pem \<br>
2282 --url http://wayf.internet2.edu/InQueue/sites.xml
2283 </span></blockquote>
2285 <p>It is recommended that similar commands be added to a <span
2286 class="fixedwidth">crontab</span> to keep the sites and trust files refreshed.</p>
2294 <h3><a name="5."></a>5. Troubleshooting</h3>
2296 <p>This section provides basic information about testing
2297 Shibboleth targets. This information is not intended to be
2298 comprehensive, but instead rudimentary guidelines for basic
2299 configuration tests and problems. For more detailed information
2300 or answers to specific problems not addressed in this section,
2301 please mail <a href=
2302 "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>
2303 with a thorough description of errors and configurations
2306 <h4><a name="5.a."></a>5.a. Basic Testing</h4>
2309 <p>The target may be tested by generating a folder with very
2310 basic access controls on it, and accessing it using a web
2311 browser. Place a simple webpage such as <span class="fixedwidth">index.html</span>
2312 in <span class="fixedwidth">/secure/</span>. Then, add the following lines to
2313 <span class="fixedwidth">httpd.conf</span>, which should be removed when testing is
2317 <span class="fixedwidth"># Configure a test directory<br>
2318 <Location /secure><br>
2319 AuthType shibboleth<br>
2320 require valid-user<br>
2322 # Per-directory SHIRE Configuration<br>
2323 #ShibBasicHijack On<br>
2324 #ShibSSLOnly On<br>
2325 #ShibAuthLifetime 60<br>
2326 #ShibAuthTimeout 600<br>
2328 # RM Configuration<br>
2329 #AuthGroupFile /foo<br>
2330 #ShibExportAssertion On<br>
2331 </Location><br>
2335 <p><b>For information regarding specific error messages that
2336 may be generated if the target does not work successfully,
2337 please refer to section <a href="#4.b.">4.b</a>, or write <a
2339 "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.</b></p>
2342 <h4><a name="5.b."></a>5.b. Common Problems</h4>
2345 <p>A knowledge base is being developed in the <a
2346 href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.
2347 html">Shibboleth Deployer's FAQ</a>. Please mail <a href=
2348 "mailto:mace-shib-users@internet2.edu">mace-shib-users@
2349 internet2.edu</a> with any additional questions or problems
2350 encountered that are not answered by this basic guide.</p>
projects / shibboleth / sp.git / blob