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 Shibboleth Version 1.0<br />
155 <h3>This version of the deploy guide is for Shibboleth v1.0. For
156 documentation related to prior versions of Shibboleth, please
157 consult the appropriate branch in the Shibboleth CVS.</h3>
159 <h3>Federations have been abstracted out from the Shibboleth
160 documentation. For further information on using Shibboleth in a
161 federation, refer to the federation guide.</h3>
163 <p>Shibboleth v1.0 is stable and secure enough to deploy in
164 production scenarios. While attempts have been made to include all
165 functionality that would represent a break of interoperability with
166 previous versions in v1.0, be aware that future versions of
167 Shibboleth are likely to be developed and may include further
168 implementation of the architectural document, functional
169 enhancements, and user interface improvements.</p>
171 <h4>Major New Features - 1.0</h4>
172 This new release contains many improvements and enhancements, including:
174 <h5>Federation Support</h5>
177 Federation and trust support has been substantially extended. Federation
178 structures are now defined. The set of metadata collected and managed
179 by each Federation is more fully defined. The configuration values
180 assigned by a Federation are now identified. <br>
183 There is some support for targets to be members of multiple federations;
184 this support will continue to evolve. When a browser user arrives,
185 a target will determine which federation their origin belongs to,
186 and then use the trust fabric associated with that Federation. <br>
189 Better support for flexible and bilateral trust agreements. A key
190 specific to an origin site can be used to vallidate its signature.
195 This version contains a significantly more mature security implementation,
196 and should meet the security requirements of typical sites. <p></p>
203 <li> The Attribute Authority has a powerful new attribute resolver.
204 Simple scenarios (using a string attribute stored in ldap) can be
205 accomplished by merely editing a configuration file. Java classes
206 may still be written for more complex evaluations (eg retrieving information
207 from multiple disparate repositories, and computing the SAML attribute
208 using business rules). This should greatly simplify the process of
209 configuring the AA to support additional general attributes.<br>
215 <li> Significantly more flexibility in configuring targets to ensure
216 robustness. Failover and redundant configurations are now supported.
219 <li>The SHAR may now optionally store its session and attribute
220 cache in a back-end database in addition to the previously available
221 in-memory option. This would allow a site to run an apache server
222 farm, with multiple SHARs, supporting the same set of sessions.
224 <li>Federation supplied files (sites.xml and trust.xml) are now
225 refreshed in a much more robust manner. <br>
230 <li>Attribute acceptance policies have been greatly enhanced, and now
231 supports filtering of attribute values by sites. <br>
233 <li>The SHAR can be configured to request specific attributes from the
237 <h5>Miscellaneous</h5>
239 <li>Origin sites can configure a value to describe the type of authentication
240 mechanism used at the origin site(e.g. password, Kerberos, PKI, etc.).
241 This value is made available on the target side as Shib-Authentication-Method.
244 <li>Various improvements to error handling. Origin sites are now able
245 to supply an "error URL" and contact information to a federation.
246 When a target encounters an error, it can include this information
247 in the error page. <br>
250 <li>Local time string values are now used in log files. <br>
252 <li>Internationalization support has been extended.</li>
255 <p>Before starting, please sign up for all applicable <a href=
256 "http://shibboleth.internet2.edu/shib-misc.html#mailinglist">
257 mailing lists</a>. Announcements pertinent to Shibboleth
258 deployments and developments and resources for deployment
259 assistance can be found here.</p>
261 <p>Please send any questions, concerns, or eventual confusion
263 "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.
264 This should include, but not be limited to, questions about the
265 documentation, undocumented problems, installation or
266 operational issues, and anything else that arises. Please
267 ensure that you have the <a href=
268 "http://shibboleth.internet2.edu/release/shib-download.html">appropriate
269 tarball</a> for your operating system.</p>
276 <h3><a name="TOC"></a>Shibboleth Target -- Table of
283 <h4><a href="#1."><font color="black">Shibboleth
284 Overview</font></a></h4>
287 <li><a href="#1.a."><font color=
288 "black">Origin</font></a></li>
290 <li><a href="#1.b."><font color=
291 "black">Target</font></a></li>
293 <li><a href="#1.c."><font color=
294 "black">WAYF</font></a></li>
296 <li><a href="#1.d."><font color=
297 "black">Federations</font></a></li>
302 <h4><a href="#2."><font color=
303 "black">Planning</font></a></h4>
306 <li><a href="#2.a."><font color=
307 "black">Requirements</font></a></li>
309 <li><a href="#2.b."><font color="black">Join a
310 Federation</font></a></li>
312 <li><a href="#2.c."><font color="black">Security
313 Considerations</font></a></li>
315 <li><a href="#2.d."><font color="black">Server
316 Certs</font></a></li>
318 <li><a href="#2.e."><font color="black">Attribute Release
319 Policies</font></a></li>
321 <li><a href="#2.f."><font color="black">Designate
322 Contacts</font></a></li>
324 <li><a href="#2.g."><font color="black">Browser
325 Requirements</font></a></li>
327 <li><a href="#2.h."><font color=
328 "black">Clocks</font></a></li>
330 <li><a href="#2.i."><font color="black">Other
331 Considerations</font></a></li>
336 <h4><a href="#3."><font color=
337 "black">Installation</font></a></h4>
340 <li><a href="#3.a."><font color="black">Software
341 Requirements</font></a></li>
343 <li><a href="#3.b."><font color="black">Deploy the
344 Shibboleth Package</font></a></li>
346 <li><a href="#3.c."><font color="black">Configure
347 Apache</font></a></li>
352 <h4><a href="#4."><font color="black">Getting
353 Running</font></a></h4>
356 <li><a href="#4.a."><font color="black">Configuring
357 <span class="fixedwidth">shibboleth.ini</span></font></a></li>
359 <li><a href="#4.b."><font color="black">Dynamic Error
360 Page Generation</font></a></li>
362 <li><a href="#4.c."><font color="black">Key Generation
363 and Certificate Installation</font></a></li>
365 <li><a href="#4.d."><font color="black">Protecting
366 Webpages</font></a></li>
368 <li><a href="#4.e."><font color="black">Designing
369 AAP's</font></a></li>
371 <li><a href="#4.f."><font color="black">Using Attributes
372 in Applications</font></a></li>
374 <li><a href="#4.g."><font color="black"><span
375 class="fixedwidth">siterefresh</span></font></a></li>
380 <h4><a href="#5."><font color=
381 "black">Troubleshooting</font></a></h4>
384 <li><a href="#5.a."><font color="black">Basic
385 Testing</font></a></li>
387 <li><a href="#5.b."><font color="black">Common
388 Problems</font></a></li>
397 <h3><a name="1."></a>1. Shibboleth Overview</h3>
399 <p>Shibboleth is a system designed to exchange attributes
400 across realms for the primary purpose of authorization. It
401 provides a secure framework for one organization to transmit
402 attributes about a web-browsing individual across security
403 domains to another institution. In the primary usage case, when
404 a user attempts to access a resource at a remote domain, the
405 user's own home security domain can send certain information
406 about that user to the target site in a trusted exchange. These
407 attributes can then be used by the resource to help determine
408 whether to grant the user access to the resource. The user may
409 have the ability to decide whether to release specific
410 attributes to certain sites by specifying personal Attribute
411 Release Policies (ARP's), effectively preserving privacy while
412 still granting access based on trusted information.</p>
414 <p>When a user first tries to access a resource protected by
415 Shibboleth, they are redirected to a service which asks the
416 user to specify the organization from which they want to
417 authenticate. If the user has not yet locally authenticated to
418 a WebISO service, the user will then be redirected to their
419 home institution's authentication system. After the user
420 authenticates, the Shibboleth components at the local
421 institution will generate a temporary reference to the user,
422 known as a handle, for the individual and send this to the
423 target site. The target site can then use the handle to ask for
424 attributes about this individual. Based on these attributes,
425 the target can decide whether or not to grant access to the
426 resource. The user may then be allowed to access the requested
429 <p>There are several controls on privacy in Shibboleth, and
430 mechanisms are provided to allow users to determine exactly
431 which information about them is released. A user's actual
432 identity isn't necessary for many access control decisions, so
433 privacy often is needlessly compromised. Instead, the resource
434 often utilizes other attributes such as faculty member or member
435 of a certain class. While these are commonly determined using
436 the identity of the user, Shibboleth provides a way to mutually
437 refer to the same principal without revealing that principal's
438 identity. Because the user is initially known to the target site
439 only by a randomly generated temporary handle, if sufficient,
440 the target site might know no more about the user than that the
441 user is a member of the origin organization. This handle should
442 never be used to decide whether or not to grant access, and is
443 intended only as a temporary reference for requesting
446 <h4><a name="1.a."></a>1.a. Origin</h4>
449 <p>There are four primary components to the origin side in
450 Shibboleth: the Attribute Authority (AA), the Handle Service
451 (HS), the directory service, and the local sign-on system
452 (SSO). The AA and HS are provided with Shibboleth, and an
453 open-source WebISO solution Pubcookie is also supplied; the
454 directory is provided by the origin site. Shibboleth is able
455 to interface with a directory exporting an LDAP interface or a
456 SQL database containing user attributes, and is designed such
457 that programming interfaces to other repositories should be
458 readily implemented. Shibboleth relies on standard web server
459 mechanisms to trigger local authentication. A .htaccess file
460 can be easily used to trigger either the local WebISO system
461 or the web server's own Basic Auth mechanism, which will
462 likely utilize an enterprise authentication system, such as
465 <p>From the origin site's point of view, the first contact
466 will be the redirection of a user to the handle service,
467 which will then consult the SSO system to determine whether
468 the user has already been authenticated. If not, then the
469 browser user will be asked to authenticate, and then sent
470 back to the target URL with a handle bundled in an attribute
471 assertion. Next, a request from the Shibboleth Attribute
472 Requester (SHAR) will arrive at the AA which will include the
473 previously mentioned handle. The AA then consults the ARP's
474 for the directory entry corresponding to the handle, queries
475 the directory for these attributes, and releases to the SHAR
476 all attributes the SHAR is entitled to know about that
480 <h4><a name="1.b."></a>1.b. Target</h4>
483 <p>There are three primary components to the target side in
484 Shibboleth: the Shibboleth Indexical Reference Establisher
485 (SHIRE), the Shibboleth Attribute Requester (SHAR), and the
486 resource manager (RM). An implementation of each of these is
487 included in the standard Shibboleth distribution. These
488 components are intended to run on the same web server.</p>
490 <p>From the target's point of view, a browser will hit the RM
491 with a request for a Shibboleth-protected resource. The RM
492 then allows the SHIRE to step in, which will use the WAYF to
493 acquire the name of a handle service to ask about the user.
494 The handle service (HS) will then reply with a SAML
495 authentication assertion containing a handle, which the SHIRE
496 then hands off to the SHAR. The SHAR uses the handle and the
497 supplied address of the corresponding attribute authority
498 (AA) to request all attributes it is allowed to know about
499 the handle. The SHAR performs some basic validation and
500 analysis based on attribute acceptance policies (AAP's).
501 These attributes are then handed off to the RM, which is
502 responsible for using these attributes to decide whether to
506 <h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
509 <p>The WAYF service can be either outsourced and operated by a
510 federation or deployed as part of the SHIRE. It is responsible for
511 allowing a user to associate themself with an institution of their
512 specification, then redirecting the user to the known address for
513 the handle service of that institution.</p>
516 <h4><a name="1.d."></a>1.d. Federations</h4>
519 <p>A federation provides part of the underlying trust required for
520 function of the Shibboleth architecture. A federation in the
521 context of Shibboleth is a group of organizations(universities,
522 corporations, content providers, etc.) who agree to exchange
523 attributes using the SAML/Shibboleth protocols and abide by a
524 common set of policies and practices. In so doing, they must
525 implicitly or explicitly agree to a common set of guidelines.
526 Joining a federation is not explicitly necessary for operation of
527 Shibboleth, but it dramatically expands the number of targets and
528 origins that can interact without defining bilateral agreements
529 between all these parties.</p>
531 <p>A federation can be created in a variety of formats and trust
532 models, but to support Shibboleth, it must provide a certain set
533 of services to federation members. It needs to supply a registry
534 to process applications to the federation and distribute
535 membership information to the origin and target sites. This must
536 include distribution of the PKI components necessary for trust
537 between origins and targets. There also needs to be a set of
538 agreements and best practices defined by the federation governing
539 the exchange, use, and population of attributes before and after
540 transit, and there should be a way to find information on local
541 authentication and authorization practices for federation
551 <h3><a name="2."></a>2. Planning</h3>
553 <p>There are several essential elements that must be present in
554 the environment to ensure Shibboleth functions well, both
555 political and technical. Shibboleth currently runs on a
556 specific range of platforms and web server environments. The
557 SHAR and SHIRE are implemented entirely in C/C++. These are the
558 recommendations and requirements for a successful implementation
559 of a Shibboleth target.</p>
561 <h4><a name="2.a."></a>2.a. Requirements</h4>
564 <p>Shibboleth currently only supports Linux and Solaris. At
565 present, Shibboleth consists of Apache plugins and a separate SHAR
566 process. The plugins use the ONC RPC mechanism to communicate with
567 the SHAR. The target's web servers must be running <a href=
568 "http://http://www.apache.org/dist/httpd/">Apache</a> 1.3.26+, but
569 not Apache 2. More precise technical details are discussed in <a
570 href="#3.a.">3.a</a>.</p>
573 <h4><a name="2.b."></a>2.b. Join a Federation</h4>
576 <p>While it is not necessary for a target or origin to join a
577 federation, doing so greatly facilitates the implementation of
578 multilateral trust relationships. Each federation will have a
579 different application process.</p>
581 <p>For more information on federations, refer to <a href=
582 "#1.d.">1.d</a> or the Shibboleth v1.0 architectural
586 <h4><a name="2.c."></a>2.c. Security Considerations</h4>
589 <p>Shibboleth's protocols and software have been extensively
590 engineered to provide protection against many attacks.
591 However, the most secure protocol can be compromised if it is
592 placed in an insecure environment. To ensure Shibboleth is as
593 secure as possible, there are several recommended security
594 precautions which should be in place at local sites.</p>
598 <p>SSL use is optional for target sites. Federation guidelines
599 should be considered when determining whether to
600 implement SSL, and, in general, SSL should be used for
601 interactions with client machines to provide the
602 necessary authentication and encryption to ensure
603 protection from man-in-the-middle attacks. It is strongly
604 suggested that all password traffic or similarly
605 sensitive data should be SSL-protected. Assessment of the
606 risk tradeoff against possible performance degradation
607 should be performed for all applications.</p>
611 <p>Many other attacks can be made on the several
612 redirection steps that Shibboleth takes to complete
613 attribute transfer. The best protection against this is
614 safeguarding the WAYF service and ensuring that rogue
615 targets and origins are not used, generally by
616 development of the trust model underneath Shibboleth.
617 Shibboleth also leverages DNS for security, which is not
618 uncommon, but attacks concerning bad domain information
619 should be considered.</p>
623 <p>Information regarding origin users is generally
624 provided by the authoritative enterprise directory, and
625 the acceptance of requests from target applications can
626 be carefully restricted to ensure that all requests the
627 SHAR performs are authorized and all information the
628 origin provides is accurate. Use of plaintext passwords
629 is strongly advised against.</p>
633 <p>Server platforms should be properly secured,
634 commensurate with the level that would be expected for a
635 campus' other security services, and cookie stores on
636 client machines should be well protected.</p>
641 <h4><a name="2.d."></a>2.d. Server Certs</h4>
644 <p>In the Shibboleth architecture, the SHAR, HS, and AA must
645 all have various client and/or server certificates for use in
646 signing assertions and creating SSL channels. These should be
647 issued by a commonly accepted CA, which may be stipulated by
648 your federation. After understanding the CA's acceptible to your
649 federations, consult chapter <a href="#4.c.">4.c</a> for
650 information on certificate and key generation.</p>
653 <h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
656 <p>The Attribute Authority maintains a set of rules called
657 Attribute Release Policies (ARP's) that define which
658 attributes are released to which targets. When a browser user
659 tries to access a resource, the SHAR asks the origin site AA
660 to release all the attributes it is allowed to know. The SHAR
661 provides its own name and an optional URL on behalf of which
662 the attribute request is made which can further refine the
663 information the SHAR is allowed to know. The AA processes this
664 request using all applicable ARP's, determines which
665 attributes and values it will release, and then obtains the
666 values actually associated with the browser user. The AA sends
667 these attributes and values back to the SHAR.</p>
669 <p>Targets should work together with expected origin sites to
670 ensure that the sets of attributes that both sites expect to
671 correspond using are congruent.</p>
674 <h4><a name="2.f."></a>2.f. Designate Contacts</h4>
677 <p>Since Shibboleth deals both with daily technical and
678 operational issues and also with contractual issues, a set of
679 contacts should be set up to support the user base and to
680 facilitate interactions with other Shibboleth sites and federation
681 members. It is recommended that at least technical and
682 administrative contacts be designated. Names, titles, e-mail
683 addresses, and phone numbers may all be useful information to
687 <h4><a name="2.g."></a>2.g. Browser Requirements</h4>
690 <p>A primary Shibboleth design consideration was to require
691 very little or no modification to client machines. The only
692 requirement is that a browser is used which supports cookies,
693 redirection and SSL. Browser users will have to perform an
694 additional click to submit the authentication assertion if
695 JavaScript is not functional.</p>
698 <h4><a name="2.h."></a>2.h. Clocks</h4>
701 <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should
702 be run on all web servers. Shibboleth employs a short handle
703 issuance time to protect against replay attacks. Because of
704 this, any significant degree of clock skew can hinder the
705 ability of users to access sites successfully.</p>
708 <h4><a name="2.h."></a>2.i. Other Considerations</h4>
711 <p>Especially for higher education, there are a handful of
712 laws enacted which may have important ramifications on the
713 disclosure of personal information and attributes. Since
714 Shibboleth does not necessarily need to transmit identity, it
715 is an ideal solution for many higher education situations.
716 Nevertheless, all parties within the United States of America
717 are strongly advised to consult the <a href=
718 "http://www.ed.gov/offices/OM/fpco/ferpa/">Family Educational
719 Rights and Privacy Act of 1974(FERPA)</a>, and all other
720 relevant state and federal legislation before deploying
729 <h3><a name="3."></a>3. Installation</h3>
731 <h4><a name="3.a."></a>3.a. Software Requirements</h4>
733 <p>The Shibboleth project makes binary packages available for
734 Solaris and Linux that are precompiled against recent releases
735 of various required libraries such as OpenSSL. It is highly
736 advisable to build from source when using Shibboleth in a
737 production environment in order to permit patching or updating
738 of packages as security holes and bugs are fixed. Building from
739 source is necessary to give you complete control over your
740 deployment platform. The binary packages represent a snapshot in
741 time only. To build from source, see the <span class="fixedwidth">INSTALL.txt</span>
742 files in the root of the OpenSAML and Shibboleth source
746 <b>Operating System:</b>
754 <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
757 <p>Apache must be compiled with mod_so for DSO
758 module support, and must include SSL
759 support (preferably using <span class="fixedwidth">mod_ssl</span>), and
760 EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
761 provides). Shibboleth can coexist with
762 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
763 into the server for use elsewhere, but Shibboleth
764 does not need or use it. The most recent Red Hat
765 RPM (1.3.23-14 as of this writing) is sufficient.
770 <p>On Linux, Shibboleth requires that Apache and
771 Apache-SSL be built with <span
772 class="fixedwidth">libpthread</span>, or loading the
773 <span class="fixedwidth">mod_shibrm</span> or <span
774 class="fixedwidth">mod_shire</span> modules will
775 cause Apache to stop. While RedHat's Apache is
776 compatible, Debian's Apache must be rebuilt with
777 <span class="fixedwidth">libpthread</span>:</p>
779 <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
780 $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
786 "http://shibboleth.internet2.edu/release/shib-download.html">
787 Shibboleth v1.0 Target for RedHat</a></li>
789 <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
790 revision <span class="fixedwidth">i</span> or newer</a></li>
793 libstdc++3-3.0.4-1.i386.rpm and
794 libgcc-3.0.4-1.i386.rpm
797 <p>Shibboleth binaries are currently built with <a href=
798 "http://www.gnu.org/software/gcc/gcc.html">GCC
799 3.04</a>, and require these specific library
800 versions. They are available as RPMs and are
801 available in the RedHat 7.2 updates directory on
803 "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
804 RedHat mirror</a>. They can be installed alongside
805 earlier and later GCC libraries.</p>
809 <li><b>Portions of the <span
810 class="fixedwidth">libphp4</span> Apache plugin are written
811 in C++, as is Shibboleth. There is a known conflict between
812 the PHP extensions <span
813 class="fixedwidth">libpspell.so</span> and <span
814 class="fixedwidth">libsablot.so</span> which will manifest
815 itself as segmentation faults when starting Apache. If a
816 site wants to use <span class="fixedwidth">libphp4.so</span>
817 and Shibboleth at once, then one of the following may be
821 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
824 Rebuild these two modules using
825 the same version of GCC that was used to compile Shibboleth.
837 "ftp://ftp.openssl.org/source/openssl-0.9.7a.tar.gz">
841 <p>The shared library version of OpenSSL is required
842 by Shibboleth. The static libraries may be installed as
843 well if necessary for other applications, but cannot be
844 used within mod_ssl or any other Apache modules.</p>
849 <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
852 <p>Apache must be compiled with mod_so for DSO
853 module support, and must include SSL
854 support (preferably using <span class="fixedwidth">mod_ssl</span>) and EAPI
855 support (which <span class="fixedwidth">mod_ssl</span> requires and
856 provides). Shibboleth can coexist with
857 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
858 into the server for use elsewhere, but Shibboleth
859 does not need or use it.</p>
861 <p><span class="fixedwidth">mod_ssl</span>'s
862 loadable module, <span class="fixedwidth">libssl.so</span>, must be
863 compiled against <span class="fixedwidth">OpenSSL
864 0.9.7a</span>'s shared libraries. Other versions or
865 a statically linked build of <span
866 class="fixedwidth">libssl.so</span> will cause
867 failures such as bus errors when used with
870 <p>To check how OpenSSL was built, run the <span
871 class="fixedwidth">ldd</span> command against <span
872 class="fixedwidth">libssl.so</span> in the Apache
873 <span class="fixedwidth">/libexec/</span> folder and
874 check the output for references to <span
875 class="fixedwidth">libssl.so.0.9.7a</span>. If you
876 see an earlier version mentioned, or no mention of
877 it at all, then <span class="fixedwidth">OpenSSL
878 0.9.7a</span> must be rebuilt with shared libraries
884 "ftp://ftp.sunfreeware.com/pub/freeware/sparc/8/libgcc-3.2.2-sol8-sparc-local.gz">
885 libgcc v3.2.2+ and libstdc++ v3.2.2+</a></li>
888 "http://shibboleth.internet2.edu/release/shib-download.html">
889 Shibboleth v1.0 Target for Solaris</a></li>
891 <li><b>Portions of the <span
892 class="fixedwidth">libphp4</span> Apache plugin are written
893 in C++, as is Shibboleth. There is a known conflict with
894 the PHP extensions <span
895 class="fixedwidth">libpspell.so</span> and <span
896 class="fixedwidth">libsablot.so</span> which will manifest
897 itself as segmentation faults when starting Apache. If a
898 site wants to use <span class="fixedwidth">libphp4.so</span>
899 and Shibboleth at once, then one of the following may be
903 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
906 Rebuild these two modules using the same version of GCC
907 that was used to compile Shibboleth.
917 <p>RedHat 8 ships with Apache 2, which is not supported by
918 Shibboleth. To run Shibboleth under this OS, <a
919 href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
920 must be installed.</p>
923 <p>Apache must be compiled with mod_so for DSO
924 module support, and must include SSL
925 support (preferably using <span class="fixedwidth">mod_ssl</span>), and
926 EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
927 provides). Shibboleth can coexist with
928 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
929 into the server for use elsewhere, but Shibboleth
930 does not need or use it. The most recent Red Hat
931 RPM (1.3.23-14 as of this writing) is sufficient.
936 <p>On Linux, Shibboleth requires that Apache and
937 Apache-SSL be built with <span
938 class="fixedwidth">libpthread</span>, or loading the
939 <span class="fixedwidth">mod_shibrm</span> or <span
940 class="fixedwidth">mod_shire</span> modules will
941 cause Apache to stop. While RedHat's Apache is
942 compatible, Debian's Apache must be rebuilt with
943 <span class="fixedwidth">libpthread</span>:</p>
945 <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
946 $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
953 "http://shibboleth.internet2.edu/release/shib-download.html">
954 Shibboleth 1.0 Target for RedHat</a></li>
956 <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
957 revision <span class="fixedwidth">i</span> or newer</a></li>
960 libstdc++3-3.0.4-1.i386.rpm and
961 libgcc-3.0.4-1.i386.rpm
964 <p>Shibboleth binaries are currently built with <a href=
965 "http://www.gnu.org/software/gcc/gcc.html">GCC
966 3.04</a>, and require these specific library
967 versions. They are available as RPMs and are
968 available in the RedHat 7.2 updates directory on
970 "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
971 RedHat mirror</a>. They can be installed alongside
972 earlier and later GCC libraries.</p>
976 <li><b>Portions of the <span
977 class="fixedwidth">libphp4</span> Apache plugin are written
978 in C++, as is Shibboleth. There is a known conflict with
979 the PHP extensions <span
980 class="fixedwidth">libpspell.so</span> and <span
981 class="fixedwidth">libsablot.so</span> which will manifest
982 itself as segmentation faults when starting Apache. If a
983 site wants to use <span class="fixedwidth">libphp4.so</span>
984 and Shibboleth at once, then one of the following may be
988 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
991 Rebuild these two modules using
992 the same version of GCC that was used to compile Shibboleth.
1001 <h4><a name="3.b."></a>3.b. Deploy the Shibboleth Package</h4>
1004 <p>For the sake of clarity, this deployment guide assumes
1005 that standard directories are used for all installations.
1006 These directories may be changed for local implementations,
1007 but must be done so consistently.</p>
1011 <p>Ensure that you have obtained the proper <a href=
1012 "http://shibboleth.internet2.edu/release/shib-download.html">
1013 tarball</a> for your operating system.</p>
1017 <p>The tarballs expand into <span class="fixedwidth">/opt/shibboleth</span>,
1018 and should be expanded as <span class="fixedwidth">root</span> from <span class="fixedwidth">/</span>.
1019 You should see the following directory structure:</p>
1022 <span class="fixedwidth">$ ls -al<br>
1023 drwxr-xr-x 10 root root 4096 Oct 24 03:54 .<br>
1024 drwxr-xr-x 3 root root 4096 Oct 24 00:37 ..<br>
1025 drwxr-xr-x 2 root root 4096 Oct 24 03:54 bin<br>
1026 drwxr-xr-x 2 root root 4096 Oct 24 03:54 doc<br>
1027 drwxr-xr-x 4 root root 4096 Oct 24 03:54 etc<br>
1028 drwxr-xr-x 13 root root 4096 Oct 24 03:54 include<br>
1029 drwxr-xr-x 4 root root 4096 Oct 24 03:55 lib<br>
1030 drwxr-xr-x 2 root root 4096 Oct 24 03:55 libexec<br>
1031 drwxr-xr-x 4 root root 4096 Oct 24 02:02 share<br>
1038 <h4><a name="3.c."></a>3.c. Configure Apache</h4>
1043 <p>Shibboleth includes configuration directives in the
1044 file <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/apache.config</span>
1045 which must be added to the httpd.conf file used locally.
1046 It is recommended that these directives simply be added
1047 to the end of the existing <span class="fixedwidth">httpd.conf</span> file
1048 rather than trying to merge it in-line;
1049 <a href="#3.c.2.">step 2</a> describes the necessary
1050 modifications to the Apache startup script. The default
1051 configuration will often work, but if customization is
1052 necessary, these options may be modified:</p>
1056 <dd class="attribute">
1057 <span class="fixedwidth">LoadModule <module>
1058 <pathname></span>
1062 <p>Specifies the title and location of the
1063 <span class="fixedwidth">shibrm_module</span> resource manager and
1064 <span class="fixedwidth">shire_module</span> SHIRE modules. These are
1065 installed by default at
1066 <span class="fixedwidth">/opt/shibboleth/libexec/mod_shibrm.so</span>
1068 <span class="fixedwidth">/opt/shibboleth/libexec/mod_shire.so</span></p>
1071 <dd class="attribute">
1072 <span class="fixedwidth">SHIREConfig <pathname></span>
1076 <p>Specifies the <span class="fixedwidth">pathname</span> of the SHIRE's
1077 configuration file. Defaults to
1078 <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span>.</p>
1081 <dd class="attribute"><span class="fixedwidth">SHIREURL <url><br>
1082 <Location <url>><br>
1083 SetHandler <method><br>
1084 </Location></span></dd>
1087 <p>Specifies the <span class="fixedwidth">URL</span> and the
1088 <span class="fixedwidth">method</span> the target uses to handle
1089 requests for Shibboleth-protected resources.
1090 Currently, <span class="fixedwidth">shib-shire-post</span> is the only
1091 available handler <span class="fixedwidth">method</span>.
1092 <span class="fixedwidth">SHIREURL</span> is used by Shibboleth when
1093 re-directing the user to the WAYF and
1094 <span class="fixedwidth"><Location></span> by Apache; for this
1095 reason, both <span class="fixedwidth">URL</span> specifications must
1096 match. Note that the configuration file itself
1097 contains <>'s, and <span class="fixedwidth">Location</span> should
1098 not be replaced.</p>
1100 <p>The referenced <span class="fixedwidth">URL</span> can be either a
1101 partial path or an absolute URL. The partial path
1102 allows each virtual server to use its own
1103 hostname and port in the SHIRE for session cookie
1104 purposes, while the absolute URL forces HTTP
1105 virtual servers to use HTTPS for the SHIRE. Use
1106 of a full <span class="fixedwidth">https://</span> URL is advised.</p>
1109 <dd class="attribute">
1110 <span class="fixedwidth">ShibMapAttribute <attribute-uri>
1111 <HTTP-header> [alias]</span>
1115 <p>Registers attributes to be recognized and maps
1116 them to an authorization <span class="fixedwidth">alias</span> for use
1117 in <span class="fixedwidth">.htaccess</span> files or Location Blocks
1118 with <span class="fixedwidth">require</span> directives.
1119 <span class="fixedwidth">REMOTE_USER</span> is a special case, suggested
1120 for use with <span class="fixedwidth">eduPersonPrincipalName</span>, and
1121 is automatically checked by a <span class="fixedwidth">require
1122 user</span> rule.</p>
1129 <a name="3.c.2."></a>
1131 <p>These modifications must be made to the Apache startup
1134 <p>Add the following environment variables:</p>
1137 <span class="fixedwidth">
1138 SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.ini;
1139 export SHIBCONFIG</span>
1142 <p>If the OpenSSL libraries are not in the system's search
1143 path, they should be added to <span class="fixedwidth">LD_LIBRARY_PATH</span> as
1146 <p>If the SHIBCONFIG environment variable is not
1147 specified, Shibboleth will use
1148 <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span> by
1153 <p>The SHAR must be started before Apache. Among other
1154 methods, this can be done either by creating a separate
1155 SHAR startup script or by modifying Apache's RC script to
1156 start/stop the <span class="fixedwidth">SHAR</span> <b>before</b>
1157 <span class="fixedwidth">httpd</span>. It is suggested that Apache's script be
1158 modified by adding:</p>
1161 <span class="fixedwidth">/opt/shibboleth/bin/shar -f &</span>
1164 <p>Sample <span class="fixedwidth">init.d</span> scripts may be included with
1165 future releases. Ensure that the environment variables
1166 referenced in <a href="#3.c.2">3.c.2</a> are in
1172 <p>The options in <span class="fixedwidth">shibboleth.ini</span> must be
1173 configured as documented in <a href="#4.a.">4.a</a>.
1174 Apache content will then need to be modified for
1175 Shibboleth authentication. This is discussed in <a href=
1176 "#4.d.">4.d</a>. It is recommended that the target then
1177 be tested as detailed in section <a href=
1178 "#5.a.">5.a</a>.</p>
1187 <h3><a name="4."></a>4. Getting Running</h3>
1189 <h4><a name="4.a."></a>4.a. Configuring
1190 <span class="fixedwidth">shibboleth.ini</span></h4>
1193 <p>Most of the configuration for the SHAR, SHIRE, and RM is stored
1194 in the file <span class="fixedwidth">shibboleth.ini</span>. This
1195 file is split into several pre-defined sections. The first
1196 sections, <span class="fixedwidth">general</span>, <span
1197 class="fixedwidth">shire</span>, and <span
1198 class="fixedwidth">shar</span>, define the operational parameters
1199 for the <span class="fixedwidth">SHIRE</span> and <span
1200 class="fixedwidth">SHAR</span>. The <span
1201 class="fixedwidth">general</span> section holds global tags, used
1202 by all pieces. The <span class="fixedwidth">shire</span> and <span
1203 class="fixedwidth">shar</span> sections can override the <span
1204 class="fixedwidth">general</span> tags with SHIRE- or
1205 SHAR-specific configuration. For example, if the SHAR is looking
1206 for a tag, it will look first in the <span
1207 class="fixedwidth">shar</span> section; if it does not find the
1208 tag there, it will proceed to look in the <span
1209 class="fixedwidth">general</span> section. The following
1210 sections, <span class="fixedwidth">metadata_shire</span>, <span
1211 class="fixedwidth">metadata_shar</span>, <span
1212 class="fixedwidth">attributes</span>, and <span
1213 class="fixedwidth">policies</span>, define the trust framework
1214 within the SHIRE and SHAR operate. Example configuration files
1215 are bundled with the Shibboleth distribution.</p>
1217 <p>There is also information that must be configured in
1218 <span class="fixedwidth">/usr/local/apache/conf/httpd.conf</span>; for more
1219 information, refer to <a href="#3.c.2.">3.c</a>.</p>
1221 <p>Information in the logger files referenced by
1222 <span class="fixedwidth">shibboleth.ini</span> may require additional configuration.
1223 It is recommended that after initial installation is
1224 completed, the log level in both files be changed to either
1225 <span class="fixedwidth">INFO</span> or <span class="fixedwidth">WARN</span>.</p>
1227 <p>Fields that are purple are optional; grey fields are
1230 <p><span class="fixedwidth">[general]</span>:</p>
1233 <dd class="attribute">
1234 <span class="fixedwidth">logger = <pathname></span>
1238 <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
1239 configuration file for most Shibboleth events. This
1240 element may also be optionally specified for each of
1241 the components individually. Default logging settings (using local log files)
1242 should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
1243 daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1244 <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
1245 to <span class="fixedwidth">enable logging from remote machines.</span> The
1246 logging level is also defined in the logger configuration.
1247 The configuration format and log levels are similar to that of the
1248 <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
1249 property format.</p>
1252 <dd class="attribute">
1253 <span class="fixedwidth">schemadir = <pathname></span>
1257 <p>Specifies the directory in which the XML schema
1258 files are located; defaults to
1259 <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>.</p>
1262 <dd class="attribute">
1263 <span class="fixedwidth">sharsocket = <pathname></span>
1267 <p>Specifies the location of the socket the SHAR uses to
1268 form connections. Note that if you change this, the SHAR and Apache
1269 should both be restarted immediately, since new Apache child processes will
1270 use the changed value as soon as they start up.</p>
1274 <p>The next segment of the <span class="fixedwidth">[general]</span> configuration
1275 section defines server-specific tags in sections defined by
1276 the server name for use by the SHIRE and RM. For example, if
1277 you have a web server at www.example.edu, you can define a
1278 section <span class="fixedwidth">[www.example.edu]</span> and override global tags
1279 with tags for that server only.</p>
1281 <p>The following table lists the server-specific tags. It is
1282 broken into mandatory tags, and optional tags. Tags in the <span
1283 class="fixedwidth">[general]</span> section correspond to all
1284 servers; to override specific tags on a per-server basis, use
1285 <span class="fixedwidth">[<FQDN>]</span> as the header for a
1288 <span class="fixedwidth">[<general>]</span>:
1292 <dd class="attributeopt">
1293 <span class="fixedwidth">normalizeRequest = <true/false></span>
1296 <dd class="valueopt">
1297 <p>If true, all redirects generated by
1298 <span class="fixedwidth">mod_shire</span> will be created using the virtual
1299 server name assigned to the server containing this
1300 command. If <span class="fixedwidth">false</span>, the browser's supplied
1301 URL is used to compute the redirect back.</p>
1304 <dd class="attributeopt">
1305 <span class="fixedwidth">checkIPAddress = <true/false></span>
1308 <dd class="valueopt">
1309 <p>If <span class="fixedwidth">true</span>, Shibboleth will check client
1310 addresses for impersonation protection. In most
1311 circumstances, this should be enabled to prevent
1312 certain attacks concerning stolen cookies. Defaults
1313 to <span class="fixedwidth">false</span>.</p>
1316 <dd class="attributeopt">
1317 <span class="fixedwidth">supportContact = <e-mail></span>
1320 <dd class="valueopt">
1321 <p>Specifies the e-mail address used in the
1322 generation of error pages.</p>
1325 <dd class="attributeopt">
1326 <span class="fixedwidth">logoLocation = <pathname></span>
1329 <dd class="valueopt">
1330 <p>Specifies the location of the logo used in the
1331 generation of error pages. This logo can be in any
1332 format that the web browser will understand.</p>
1335 <dd class="attribute">
1336 <span class="fixedwidth">wayfURL = <url></span>
1340 <p>Specifies the URL of the WAYF service the user is
1341 redirected to. Federations will generally provide this URL
1342 or provide information on how to locally host WAYF's with
1343 a distributed hosts file.</p>
1346 <dd class="attribute">
1347 <span class="fixedwidth">cookieName = <string></span>
1351 <p>Defines the name to be used for session cookies.</p>
1354 <dd class="attribute">
1355 <span class="fixedwidth">shireSSLOnly = <true/false></span>
1359 <p>If <span class="fixedwidth">true</span>, the SHIRE will reject HTTP
1360 connections that are not SSL-protected. This guards the initial session
1361 sign-on from the browser, but does not preclude non-SSL content. Use of
1362 SSL is strongly recommended; see section <a href=
1363 "#2.c.">2.c</a> for more information.</p>
1366 <dd class="attribute">
1367 <span class="fixedwidth">shireError = <pathname></span>
1371 <p>Specifies the location of the template for the
1372 error page generated when there is an error
1373 re-directing the user to the WAYF or processing a
1377 <dd class="attribute">
1378 <span class="fixedwidth">rmError = <pathname></span>
1382 <p>Specifies the location of the template for the
1383 error page generated if internal errors occur in the
1387 <dd class="attribute">
1388 <span class="fixedwidth">accessError = <pathname></span>
1392 <p>Specifies the location of the template for the
1393 page displayed to users when access to a protected
1394 resource is denied by the RM.</p>
1398 <span class="fixedwidth">[shire]</span>:
1401 <dd class="attribute">
1402 <span class="fixedwidth">logger = <pathname></span>
1406 <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
1407 configuration file for most Shibboleth events. This
1408 element may also be optionally specified for each of
1409 the components individually. Default logging settings (using local log files)
1410 should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
1411 daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1412 <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
1413 to <span class="fixedwidth">enable logging from remote machines.</span> The
1414 logging level is also defined in the logger configuration.
1415 The configuration format and log levels are similar to that of the
1416 <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
1417 property format.</p>
1420 <dd class="attributeopt">
1421 <span class="fixedwidth">aap-uri = <uri></span>
1424 <dd class="valueopt">
1425 <p>Specifies the URI of an attribute acceptance policy XML
1426 file. Attributes must be listed in the <span
1427 class="fixedwidth">aap-uri</span> file if they are to be
1428 visible to the Apache server. Unlisted or rejected attributes are
1429 filtered out and hidden from the web server (but also see the
1430 <b>ShibExportAssertion</b> Apache command).
1431 For more information, refer to section <a href="#4.e.">4.e</a>.</p>
1434 <dd class="attributeopt">
1435 <span class="fixedwidth">metadata = <tag></span>
1438 <dd class="valueopt">
1439 <p>Specifies the tag that defines the section of <span
1440 class="fixedwidth">shibboleth.ini</span> the SHIRE should
1441 use to acquire its metadata. The SHIRE does not need trust
1442 metadata, and so generally it will only need sites data to
1443 enforce attribute policies like scope limitations(e.g. MIT
1444 not asserting @brown.edu attributes.)</p>
1448 <span class="fixedwidth">[shar]</span>:
1451 <dd class="attribute">
1452 <span class="fixedwidth">logger = <pathname></span>
1456 <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
1457 configuration file for most Shibboleth events. This
1458 element may also be optionally specified for each of
1459 the components individually. Default logging settings (using local log files)
1460 should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
1461 daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1462 <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
1463 to <span class="fixedwidth">enable logging from remote machines.</span> The
1464 logging level is also defined in the logger configuration.
1465 The configuration format and log levels are similar to that of the
1466 <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
1467 property format.</p>
1470 <dd class="attributeopt">
1471 <span class="fixedwidth">metadata = <tag></span>
1474 <dd class="valueopt">
1475 <p>Specifies the tag that defines the section of <span
1476 class="fixedwidth">shibboleth.ini</span> the SHAR should
1477 use to acquire its site and trust metadata.</p>
1480 <dd class="attributeopt">
1481 <span class="fixedwidth">certFile = <pathname></span>
1484 <dd class="valueopt">
1485 <p>Specifies the location of the PEM-format certificate used by
1486 the SHAR to communicate in authenticated fashion with
1487 origin site Attribute Authorities.</p>
1490 <dd class="attributeopt">
1491 <span class="fixedwidth">keyFile = <pathname></span>
1494 <dd class="valueopt">
1495 <p>Specifies the location of the PEM-format private key used by
1496 the SHAR to communicate in authenticated fashion with
1497 origin site Attribute Authorities.</p>
1500 <dd class="attributeopt">
1501 <span class="fixedwidth">keyPass = <password></span>
1504 <dd class="valueopt">
1505 <p>Specifies the <span class="fixedwidth">password</span> used to access the
1506 <span class="fixedwidth">keyFile</span>, if any.</p>
1509 <dd class="attribute">
1510 <span class="fixedwidth">calist = <pathname></span>
1514 <p>Specifies a single file of PEM-format certificates containing
1515 the root CAs the SHAR will consider to be valid signers of AA server
1516 certificates. Currently applies globally to all communication with AAs.</p>
1519 <dd class="attribute">
1520 <span class="fixedwidth">AATimeout = <seconds></span>
1524 <p>Specifies the number of seconds that the SHAR will wait
1525 for attributes to be sent from an AA. Defaults to <span
1526 class="fixedwidth">60</span>.</p>
1529 <dd class="attribute">
1530 <span class="fixedwidth">AAConnectTimeout = <seconds></span>
1534 <p>Specifies the number of seconds that the SHAR will wait
1535 for a connection to be established with an AA.
1536 Defaults to <span class="fixedwidth">30</span>.</p>
1539 <dd class="attribute">
1540 <span class="fixedwidth">cacheType = <method></span>
1544 <p>Specifies the method used by the SHAR to cache received
1545 attributes. The default is <span
1546 class="fixedwidth">memory</span>, which indicates that
1547 the SHAR should store received attributes in its memory.
1548 Another option is <span class="fixedwidth">mysql</span>,
1549 which will use the MySQL Credential Cache. The steps to using this are described
1550 in the MySQL Credential Cache guide.</p>
1553 <dd class="attribute">
1554 <span class="fixedwidth">cacheClean = <seconds></span>
1558 <p>Specifies the duration in seconds between cleanups of
1559 the SHAR's cached but expired attributes. Defaults to <span
1560 class="fixedwidth">300</span>, or 5 minutes.</p>
1563 <dd class="attribute">
1564 <span class="fixedwidth">cacheTimeout = <seconds></span>
1568 <p>Specifies the duration in <span
1569 class="fixedwidth">seconds</span> that must elapse
1570 between user accesses before that user's session is
1571 destroyed, including the associated handle and all
1572 cached attributes. Defaults to <span
1573 class="fixedwidth">28800</span> seconds, or 8 hours.</p>
1577 <p><span class="fixedwidth">[metadata]</span> sections must be
1578 created and named in accordance with the value of the <span
1579 class="fixedwidth">metadata</span> parameter in the <span
1580 class="fixedwidth">[shire]</span> and <span
1581 class="fixedwidth">[shar]</span> sections. Metadata sections may
1582 be shared or defined for each component. Two providers are
1583 supported by Shibboleth, but additional providers may be
1584 specified with name/value pairs consisting of <span
1585 class="fixedwidth"><metadata provider type>=<source></span>.</p>
1587 <p><span class="fixedwidth">[<metadata>]</span>:</p>
1590 <dd class="attributelong">
1591 <span class="fixedwidth">edu.internet2.middleware.shibboleth.metadata.XML = <pathname></span>
1595 <p>Specifies the location of the file to load site
1596 metadata from. This will often be a <span
1597 class="fixedwidth">sites.xml</span> file stored locally,
1598 and may be used by both the SHIRE and SHAR.</p>
1600 <p>Shibboleth provides a simple utility called <span
1601 class="fixedwidth">siterefresh</span> for updating the
1602 metadata file as described in section <a
1603 href="#4.g.">4.g</a>.</p>
1606 <dd class="attributelong">
1607 <span class="fixedwidth">edu.internet2.middleware.shibboleth.trust.XML = <pathname></span>
1611 <p>Specifies the location of the trust database of
1612 certificates and/or CA roots used by the SHAR during
1613 session initiation. The SHIRE module generally does not need trust
1618 <p>In order for an attribute to be used by Shibboleth, it must be
1619 recognized as valid by the SHAR and implemented with any specific
1620 rules for how to understand and express its value based on the XML
1621 from the AA. Additional string-valued attributes may be added to
1622 the SHAR using the <span class="fixedwidth">[attributes]</span>
1625 <p><span class="fixedwidth">[attributes]</span>:</p>
1628 <dd class="attribute">
1629 <span class="fixedwidth"><attribute_URI>=<type></span>
1633 <p>Attribute names are URI's that are assigned by the
1634 parties standardizing the attribute. Frequently, a
1635 federation or standard object class may define these URI's.
1636 The attribute type may be either <span
1637 class="fixedwidth">scoped</span> or <span
1638 class="fixedwidth">simple</span>, which defines how
1639 the attribute is processed as described in section <a
1640 href="#4.e.">4.e</a>.</p>
1644 <p>The <span class="fixedwidth">[policies]</span> section contains the policy URI
1645 values that control acceptance of assertions from origin
1646 sites. This may eventually have multiple elements associated
1647 it for targets that are members of multiple federations.</p>
1649 <p><span class="fixedwidth">[policies]</span>:</p>
1652 <dd class="attribute">
1653 <span class="fixedwidth"><federation> = <URI></span>
1657 <p>The name of the <span
1658 class="fixedwidth">federation</span> and its
1659 associated policy <span class="fixedwidth">URI</span>.
1660 These URI's will be provided by federations.</p>
1662 <p>This set of URI values is matched against the SAML
1663 <span class="fixedwidth">Audience</span> fields of
1664 assertions received from HS's and AA's. One of the
1665 URI's specified by the origin in <span
1666 class="fixedwidth">edu.internet2.middleware.shibboleth.audiences</span>
1667 must match one of these URIs or the
1668 assertion will not be accepted by design.</p>
1672 <p>Additional sections for individual servers may be defined with
1673 either parameters overriding those found in <span
1674 class="fixedwidth">[general]</span>, or the following additional
1677 <p><span class="fixedwidth">[<FQDN>]</span>:</p>
1680 <dd class="attributeopt">
1681 <span class="fixedwidth">requestAttributes = <attr1> <attr2>
1682 <attr3>...</span>
1685 <dd class="valueopt">
1686 <p>Specifies a space-delimited list of attributes named by
1687 URI that the SHAR will request of an AA. If the parameter
1688 does not exist or is null, then the SHAR will receive all
1689 attributes the AA is willing to release to it.</p>
1695 <h4><a name="4.b."></a>4.b. Dynamic Error Page Generation</h4>
1698 <p>Shibboleth supports the dynamic generation of information
1699 in error pages referenced by <span class="fixedwidth">shibboleth.ini</span>. The
1700 Shib Target employs a special Markup Language Processor to
1701 insert special tags into the generated HTML. The parser will
1702 read the error file looking for any tag that looks like:</p>
1705 <span class="fixedwidth"><shibmlp tag-name /></span>
1708 <p>Shibboleth will replace <span class="fixedwidth">tag-name</span> with the
1709 appropriate markup tag from the table below:</p>
1712 <dd class="attribute"><span class="fixedwidth">supportContact</span></dd>
1714 <dd class="value">The value of the <span class="fixedwidth">supportContact</span> for this
1717 <dd class="attribute"><span class="fixedwidth">logoLocation</span></dd>
1719 <dd class="value">The value of the <span
1720 class="fixedwidth">logoLocation</span> for this server. This
1721 is used to fill in the template error page only; if a custom
1722 error page is created, then the image may be linked to
1723 statically by the page itself.</dd>
1725 <dd class="attribute"><span class="fixedwidth">requestURL</span></dd>
1727 <dd class="value">The user's requested URL.</dd>
1729 <dd class="attribute"><span class="fixedwidth">errorType</span></dd>
1731 <dd class="value">The type of error.</dd>
1733 <dd class="attribute"><span class="fixedwidth">errorText</span></dd>
1735 <dd class="value">The actual error message.</dd>
1737 <dd class="attribute"><span class="fixedwidth">errorDesc</span></dd>
1739 <dd class="value">A textual description of the error intended for human
1742 <dd class="attribute"><span class="fixedwidth">originContactName</span></dd>
1744 <dd class="value">The contact name for the origin site provided by that
1745 site's metadata.</dd>
1747 <dd class="attribute"><span class="fixedwidth">originContactEmail</span></dd>
1749 <dd class="value">The contact email address for the origin site provided by that
1750 site's metadata.</dd>
1752 <dd class="attribute"><span class="fixedwidth">originErrorURL</span></dd>
1754 <dd class="value">The URL of an error handling page for the origin site
1755 provided by that site's metadata.</dd>
1758 <p>This configuration is only for Apache servers, and is only
1759 used by resources protected by Shibboleth. See section <a
1760 href= "#4.d.">4.d</a>.</p>
1762 <p>Sample error templates for different kinds of errors are
1763 included in the Shibboleth distribution, and can be triggered
1764 by anything that will cause Shibboleth to be unable to make an
1765 authorization decision, including a bad sites file, certificate chain,
1766 or skewed clock.</p>
1768 <p><b>You should edit these templates, provide or remove style sheets and
1769 images, and otherwise customize these templates to suit the user experience
1770 you want your users to have when errors occur.</b></p>
1774 <h4><a name="4.c."></a>4.c. Key Generation and Certificate
1778 <p>The only target component that must have a private key and
1779 certificate is the SHAR. While the target server itself should support
1780 SSL in most cases, it is mandatory for the SHAR to
1781 authenticate when contacting an AA, and it must therefore be
1782 given a key and an SSL client certificate. It is permissible
1783 for the SHAR to use the same keypair and certificate used by
1784 the target server itself, provided the certificate is signed
1785 by a CA accepted by the community of sites.</p>
1787 <p>The certificate and key should be placed based on whether
1788 they will also be used for Apache's server cert. If they will
1789 be used as a server certificate as well, they should probably
1790 be in the Apache tree in the usual <span class="fixedwidth">mod_ssl</span> spot, and
1791 the SHAR can read them from there. If the SHAR is not running
1792 as <span class="fixedwidth">root</span>, permissions might need to be changed to
1793 allow this access. If the certificate and key will only be
1794 used for the SHAR, they can be put in the same folder with the
1795 <span class="fixedwidth">shibboleth.ini</span> file.</p>
1797 <p>The SHAR is assigned a key and a certificate using
1798 shibboleth.ini's <span class="fixedwidth">certFile</span>,
1799 <span class="fixedwidth">keyFile</span> and
1800 <span class="fixedwidth">keyPass</span>, described in <a href="#4.a.">4.a</a>. These
1801 files must currently be in PEM format. OpenSSL commands to
1802 generate a new keypair and a certificate request are shown
1803 here, assuming RSA keys are to be used:</p>
1806 <span class="fixedwidth">$ openssl genrsa -des3 -out ssl.key 2048<br>
1807 $ openssl req -new -key ssl.key -out ssl.csr</span>
1810 <p>The signed certificate file returned by the CA should be
1811 usable directly, or can be converted to PEM format using the
1812 <span class="fixedwidth">openssl x509</span> command.</p>
1814 <p>The key and certificate files can be placed anywhere,
1815 though in or beneath the <span class="fixedwidth">/usr/local/apache/conf</span>
1816 directory is a good choice. The Apache child processes,
1817 often running as <span class="fixedwidth">nobody</span>, must be able to read them
1818 while the server is running, which may require permission
1821 <p>This particularly applies when sharing the key and
1822 certificate used by mod_ssl, which are only readable by root
1823 by default. The password, if any, must be placed in the conf
1824 file, since the module cannot prompt for it as the initial
1825 startup of mod_ssl can. The issues surrounding how to
1826 securely obtain a key while running as <span class="fixedwidth">nobody</span>
1827 may be addressed in a later release. Since the password will be
1828 stored in clear text in a frequently examined file, it is
1829 suggested to use a password not used elsewhere.</p>
1831 <p>Finally, the <span class="fixedwidth">calist</span> command provides the SHAR
1832 with a set of CA roots to trust when validating AA server
1833 certificates. In all cases, the SHAR verifies that the
1834 certificate's Subject CN equals the AA's hostname, but the CA root
1835 bundle restricts the accepted signers to those permitted by
1836 the SHAR. The parameter can be omitted to skip such validation.</p>
1839 <h4><a name="4.d."></a>4.d. Protecting Webpages</h4>
1842 <p>Protection of webpages is primarily achieved through
1843 "mapping" attributes provided by an AA to a localized
1844 vocabulary for authorization rules. Each attribute can be
1845 mapped using the <span class="fixedwidth">ShibMapAttribute</span> command to an HTTP
1846 header name where it can subsequently be accessed by
1847 applications, and optionally to an <span class="fixedwidth">alias</span> that can be
1848 used in a <span class="fixedwidth">Require</span> command to search for a matching
1849 value. This mapping command must be in <span class="fixedwidth">httpd.conf</span>,
1850 while the rest of the commands described here appear in
1851 content-specific configuration or <span class="fixedwidth">.htaccess</span>
1854 <p>Any of the typical ways of protecting content may be used
1855 (.htaccess, Directory, Location, Files, etc.). There are two
1856 ways to trigger Shibboleth authentication: specifying an
1857 <span class="fixedwidth">AuthType</span> of <span class="fixedwidth">shibboleth</span> to use Shibboleth
1858 directly, or specifying <span class="fixedwidth">ShibBasicHijack On</span> to
1859 process existing .htaccess files using Shibboleth instead.
1860 Support for authorization consists of mod_auth-style require
1861 directives, as well as support for mod_auth group files.</p>
1863 <p>A complete list of the directives and their values is
1867 <dd class="attribute">
1868 <span class="fixedwidth">AuthType <string></span>
1872 <p>Use <span class="fixedwidth">shibboleth</span> for direct invocation, or
1873 <span class="fixedwidth">Basic</span> plus the <span class="fixedwidth">ShibBasicHijack On</span>
1874 option described below.</p>
1877 <dd class="attribute">
1878 <span class="fixedwidth">ShibSSLOnly<on/off></span>
1882 <p>Controls whether Shibboleth will reject non-SSL
1883 requests from clients. Defaults to <span class="fixedwidth">off</span>.</p>
1886 <dd class="attribute">
1887 <span class="fixedwidth">ShibBasicHijack <on/off></span>
1891 <p>Controls whether Shibboleth should or should not
1892 ignore requests for <span class="fixedwidth">AuthType Basic</span>. Defaults
1893 to <span class="fixedwidth">off</span>.</p>
1896 <dd class="attribute">
1897 <span class="fixedwidth">ShibExportAssertion <on/off></span>
1901 <p>Controls whether the SAML attribute assertion
1902 provided by the AA is exported in a base64-encoded
1903 HTTP header, <span class="fixedwidth">Shib-Attributes</span>. Defaults to
1904 <span class="fixedwidth">off</span>. While this does require parsing the
1905 raw XML, it also permits an application to see attributes that may have
1906 been filtered by an AAP, or to forward the SAML assertion to a third party.</p>
1909 <dd class="attribute">
1910 <span class="fixedwidth">ShibAuthLifetime <seconds></span>
1914 <p>Sets the maximum lifetime in seconds that a user
1915 session can survive. Omission or zero results in
1916 arbitrary session lifetime.</p>
1919 <dd class="attribute">
1920 <span class="fixedwidth">ShibAuthTimeout <seconds></span>
1924 <p>Sets the maximum number of seconds without any
1925 user activity that a session will remain alive. After
1926 <span class="fixedwidth">seconds</span> seconds without activity, the
1927 session is considered dead. Omission or <span class="fixedwidth">0</span>
1928 results in an arbitrary session timeout.</p>
1931 <dd class="attribute">
1932 <span class="fixedwidth">AuthGroupFile <pathname></span>
1936 <p>Same as mod_auth; collects EPPN's into a named
1937 group for access control. Note that mod_auth will not
1938 support group files when mod_shibrm is loaded, since
1939 they share the same command.</p>
1944 "http://httpd.apache.org/docs/mod/core.html#require">This
1945 is implemented</a> by placing a <span class="fixedwidth">.htaccess</span>
1946 file that references an <span class="fixedwidth">AuthGroupFile</span> stored
1947 at <span class="fixedwidth">/path</span>:</p>
1950 <span class="fixedwidth">authgroupfile /path<br>
1951 require group workgroup</span>
1954 <p>Note that an <a href=
1955 "http://httpd.apache.org/docs/mod/mod_auth.html#authgroupfile">
1956 AuthGroupFile</a> used by Shibboleth would resemble
1957 <span class="fixedwidth">workgroup: joe@example.edu, jane@demo.edu,
1958 jim@sample.edu</span>.</p>
1962 <dd class="attribute">
1963 <span class="fixedwidth">Require <string></span>
1967 <p>Enforce authorization using one of the following methods.</p>
1972 <span class="fixedwidth">valid-user</span>
1975 <p>Any Shibboleth user from a trusted origin site is accepted,
1976 even if no actual attributes are received. This is a very minimal
1977 kind of policy, but is useful for testing or for deferring real
1978 policy to an application.</p>
1982 <span class="fixedwidth">user</span>
1985 <p>A space-delimited list of EPPN values, provided that the
1986 <span class="fixedwidth">urn:mace:dir:attribute-def:eduPersonPrincipalName</span>
1987 attribute has been mapped to the
1988 <span class="fixedwidth">REMOTE_USER</span> header (as per the earlier
1989 example configuration commands). Actually, any attribute can be mapped to
1990 REMOTE_USER, even if this doesn't always make sense.</p>
1995 <span class="fixedwidth">group</span>
1998 <p>A space-delimited list of group names defined
1999 within <span class="fixedwidth">AuthGroupFile</span> files, again
2000 provided that a mapping to <span class="fixedwidth">REMOTE_USER</span>
2006 <span class="fixedwidth"><alias></span>
2009 <p>An arbitrary rule tag that matches an alias
2010 defined in a <span class="fixedwidth">ShibMapAttribute</span> server
2011 command. The rule value is a space-delimited
2012 list of attribute values, whose format depends on
2013 the attribute in question (e.g. an affiliation
2014 rule might look like <span class="fixedwidth">require affiliation
2015 staff@osu.edu faculty@mit.edu</span>).</p>
2020 <p>Additionally, for <span class="fixedwidth">user</span> and
2021 <span class="fixedwidth"><alias></span>-based rules, if a tilde character
2022 is placed immediately following <span class="fixedwidth">user</span> or
2023 <span class="fixedwidth"><alias></span>, the expressions that follow are
2024 treated as regular expressions.</p>
2026 <p>For example, the regular expression AAP <span
2027 class="fixedwidth">require affiliation ~
2028 ^member@.+\.edu$</span> would evaluate to allowing
2029 anyone with an <span
2030 class="fixedwidth">eduPersonScopedAffiliation</span> of
2031 <span class="fixedwidth">member</span> from a .edu
2039 <h4><a name="4.e."></a>4.e. Designing AAP's</h4>
2042 <p>Shibboleth allows a user and a site to release a varying
2043 set of attributes to a destination site, and does not impose
2044 restrictions on the kinds of attribute information provided
2045 by an AA. Target implementations must also be prepared to
2046 examine the attributes they receive and filter them based on
2047 policies about what information to permit an origin site to
2048 assert about its users.</p>
2050 <p>Attribute acceptance is the process of filtering attribute
2051 values before passing them on to a resource manager, such as
2052 the <span class="fixedwidth">mod_shibrm</span> module. Data blocked by AAP filters
2053 will not be passed to the CGI environment or used when
2054 enforcing <span class="fixedwidth">.htaccess</span> rules.
2055 Note that the attribute assertion exported to the
2056 <span class="fixedwidth">Shib-Attributes</span> header is unfiltered.</p>
2058 <p>The Shibboleth distribution supports <span class="fixedwidth">scoped</span> and
2059 <span class="fixedwidth">simple</span> filtering policies for different kinds of
2062 <p><b>An essential part of the Shibboleth trust fabric is ensuring
2063 that sites only assert attributes for domains for which they are
2064 considered authoritative by the target. Typically, this means
2065 that Brown University will be trusted to assert attributes only
2066 scoped to <span class="fixedwidth">brown.edu</span>. Unless
2067 there are very specific circumstances requiring this restriction
2068 be removed, it is strongly encouraged that such policies be in place.</b></p>
2072 <p>Scoped attributes are a special kind of attribute whose
2073 values are a combination of a <span class="fixedwidth">value</span> and a
2074 <span class="fixedwidth">scope</span>, or <span class="fixedwidth">context</span> for the value. An
2075 example is <span class="fixedwidth">eduPersonScopedAffiliation</span>, which adds a
2076 scope to the defined set of <span class="fixedwidth">eduPersonAffiliation</span>
2077 values, such as <span class="fixedwidth">student</span>, <span class="fixedwidth">member</span>, or
2078 <span class="fixedwidth">faculty</span>. Scopes are expressed as DNS domains and
2081 <p>Any <span class="fixedwidth">scoped</span> attribute can be
2082 scoped only to the origin site's permitted domains. These
2083 domains are listed in the sites file that provides trust
2084 information to the system. Domains can be explicit or
2085 regular expressions, and can be changed by a target to meet
2086 its needs if a local version of the file is created. Thus,
2087 attribute acceptance processing for <span class="fixedwidth">scoped</span>
2088 attributes is based on the sites file, in addition to the mechanism described
2089 below for <span class="fixedwidth">simple</span> attributes.</p>
2094 <p>Simple attributes are attributes whose value is expressed
2095 in XML as a Text node; that is, the value is just a string.
2096 Multiple values are permitted.
2097 <span class="fixedwidth">eduPersonEntitlement</span>, in which the values are URIs,
2098 is one example of a simple attribute.</p>
2099 <p>In this release, simple (and scoped) attribute acceptance is
2100 controlled with an external policy file written in XML. The
2101 schema for the file is described by the
2102 <span class="fixedwidth">shibboleth.xsd</span> schema, and an example file is
2103 included, <span class="fixedwidth">AAP.xml</span>. If the <span class="fixedwidth">aap-uri</span>
2104 parameter in the <span class="fixedwidth">shibboleth.ini</span> file is left out,
2105 then no policy is applied, and no filtering is done.
2106 Otherwise, the rules encoded in the file are used.</p>
2107 <p>The policy is a default-deny algorithm that requires
2108 permissible attributes and values be listed explicitly. That
2109 is, an empty file permits nothing. Each attribute to be
2110 permitted must be listed in the file by name in an
2111 <span class="fixedwidth"><AttributeRule></span>. Each such rule is a
2112 collection of <span class="fixedwidth"><SiteRule></span> elements along with
2113 an optional <span class="fixedwidth"><AnySite></span> default rule. In turn
2114 each site rule is a set of <span class="fixedwidth"><Value></span> rules that
2115 specify matches to permit, either literal or regular
2119 <p>A syntax summary follows:</p>
2122 <p><span class="fixedwidth"><AttributeAcceptancePolicy</span></p>
2123 <blockquote>The top level element in the
2126 <p><span class="fixedwidth"><AttributeRule Name="attribute
2127 URI"></span></p>
2128 <blockquote>Specifies a rule for an attribute, named with
2129 its URI.</blockquote>
2131 <p><span class="fixedwidth"><AnySite></span></p>
2132 <blockquote>Specifies a rule that always applies to the
2133 attribute, regardless of the asserting AA.</blockquote>
2135 <p><span class="fixedwidth"><SiteRule
2136 Name="site.domain.name"></span></p>
2137 <blockquote>A rule that applies to the origin site AA
2138 corresponding to the domain name.</blockquote>
2140 <p><span class="fixedwidth"><AnyValue></span></p>
2141 <blockquote>Specifies a rule that always applies to the
2142 attribute and site, regardless of the value(s).</blockquote>
2144 <p><span class="fixedwidth"><Value Type="type"></span></p>
2145 <blockquote>Specifies a value to permit, either directly
2146 using <span class="fixedwidth">type</span> <span class="fixedwidth">literal</span>, or using a set of
2147 matching expressions as <span class="fixedwidth">type</span> <span class="fixedwidth">regexp</span>.
2148 <span class="fixedwidth">literal</span> is the default if <span class="fixedwidth">Type</span> is not
2149 specified.</blockquote>
2153 <p>The regular expression syntax is a subset of the usual
2154 Perl and Unix syntaxes that is described in the XML Schema
2155 specification by the W3C. Most typical expressions should
2156 work. Be sure to anchor them using <span class="fixedwidth">^</span> and <span class="fixedwidth">$</span>
2157 to avoid unintentional matches midstring.</p>
2159 <p>Note that the AAP rules described in this section are not
2160 part of the Shibboleth architecture and are simply one
2161 possible set of approaches provided by this implementation.</p>
2164 <h4><a name="4.f."></a>4.f. Using Attributes in
2168 <p>Apart from the simple RM functionality provided, attribute
2169 information may be made available directly to applications
2170 via the standard practice of creating custom HTTP request
2171 headers before passing control to the application.
2172 Applications should make no assumption about the presence of
2173 specific attributes for their use unless they have intimate
2174 knowledge of the attribute release policies in place.</p>
2176 <p>The <span class="fixedwidth">ShibMapAttribute</span> directive controls this
2177 interface, and maps a Shibboleth attribute (identified by an
2178 unambiguous URI) to a header name, such as
2179 <span class="fixedwidth">Shib-EP-Affiliation</span>. Using that example, any values
2180 of the mapped attribute will be placed in that header,
2181 delimited by spaces. An application that uses a CGI-like
2182 syntax to access the header will find the values in the
2183 <span class="fixedwidth">HTTP_SHIB_EP_AFFILIATION</span> variable. Using the
2184 command, any attribute can be placed in any header, to drive
2185 legacy applications that expect information in a particular
2188 <p>The <span class="fixedwidth">REMOTE_USER</span> variable is a special case that
2189 is generally populated automatically by the web server based
2190 on an internal piece of data that represents the user's
2191 <span class="fixedwidth">username</span>. Unlike many authentication modules,
2192 Shibboleth does not guarantee that <span class="fixedwidth">REMOTE_USER</span> will
2193 have any value. If it does, it is set solely based on a
2194 <span class="fixedwidth">ShibMapAttribute</span> command. For many purposes, the
2195 <span class="fixedwidth">urn:mace:dir:attribute-def:eduPersonPrincipalName</span>
2196 attribute should be mapped to <span class="fixedwidth">REMOTE_USER</span>. Even so,
2197 EPPN may not be provided by the AA, and <span class="fixedwidth">REMOTE_USER</span>
2198 might still be empty.</p>
2200 <p>The <span class="fixedwidth">Shib-Origin-Site</span> variable will contain the
2201 unique name/identifier of the origin site of the user. Some applications may use this
2202 to lookup additional policy or application data. It normally takes the form of a URI
2203 but could be any string.</p>
2205 <p>Finally, the <span class="fixedwidth">ShibExportAssertion</span> flag instructs
2206 the module to place the entire XML message containing the
2207 SAML attribute information from the AA into a base64-encoded
2208 header called <span class="fixedwidth">Shib-Attributes</span>. This is a raw
2209 interface that provides an application with the entire AA
2210 response, and is not a filtered view based on any attribute
2211 acceptance rules or even based on what attributes are
2212 recognized by the target. What was sent is what you see.</p>
2215 <h4><a name="4.g."></a>4.g. <span
2216 class="fixedwidth">siterefresh</span></h4>
2219 <p>Shibboleth provides a simple tool called <span
2220 class="fixedwidth">siterefresh</span> in the <span
2221 class="fixedwidth">/opt/shibboleth/bin</span> folder of the
2222 distribution to maintain metadata files referenced by <span
2223 class="fixedwidth">shibboleth.ini</span>. It will return 0 on
2224 success and a negative number on failure and log errors to <span
2225 class="fixedwidth">stderr</span>. If the data in the new metadata
2226 file is bad or the signature is invalid, the existing copy is
2227 kept. The SHAR and SHIRE stat the file each time the data is
2228 used, allowing them to detect and utilize updates in real-time
2231 <p><span class="fixedwidth">siterefresh</span> takes the following
2232 command-line parameters:</p>
2235 <dd class="attribute">
2236 <span class="fixedwidth">--url <URL></span>
2240 <p>Specifies the <span class="fixedwidth">URL</span> of the
2241 remote metadata file to update the local file.</p>
2244 <dd class="attribute">
2245 <span class="fixedwidth">--out <pathname></span>
2249 <p>Specifies the local file to write the new metadata to.</p>
2252 <dd class="attributeopt">
2253 <span class="fixedwidth">--cert <pathname></span>
2256 <dd class="valueopt">
2257 <p>Specifies the location of a certificate stored in <span
2258 class="fixedwidth">PEM</span> format used to validate the
2259 signature of the metadata file. Since much of Shibboleth's
2260 trust flows from this metadata file, this option is highly
2264 <dd class="attributeopt">
2265 <span class="fixedwidth">--schema <pathname></span>
2268 <dd class="valueopt">
2269 <p>Optionally defines a base path for schemas. Defaults to
2271 class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>.</p>
2275 <p>A complete command issued to <span
2276 class="fixedwidth">siterefresh</span> would take the form:</p>
2278 <blockquote><span class="fixedwidth">
2279 /opt/shibboleth/bin/siterefresh --out sites.xml --cert internet2.pem \<br>
2280 --url http://wayf.internet2.edu/InQueue/sites.xml
2281 </span></blockquote>
2283 <p>It is recommended that similar commands be added to a <span
2284 class="fixedwidth">crontab</span> to keep the sites and trust files refreshed.</p>
2292 <h3><a name="5."></a>5. Troubleshooting</h3>
2294 <p>This section provides basic information about testing
2295 Shibboleth targets. This information is not intended to be
2296 comprehensive, but instead rudimentary guidelines for basic
2297 configuration tests and problems. For more detailed information
2298 or answers to specific problems not addressed in this section,
2299 please mail <a href=
2300 "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>
2301 with a thorough description of errors and configurations
2304 <h4><a name="5.a."></a>5.a. Basic Testing</h4>
2307 <p>The target may be tested by generating a folder with very
2308 basic access controls on it, and accessing it using a web
2309 browser. Place a simple webpage such as <span class="fixedwidth">index.html</span>
2310 in <span class="fixedwidth">/secure/</span>. Then, add the following lines to
2311 <span class="fixedwidth">httpd.conf</span>, which should be removed when testing is
2315 <span class="fixedwidth"># Configure a test directory<br>
2316 <Location /secure><br>
2317 AuthType shibboleth<br>
2318 require valid-user<br>
2320 # Per-directory SHIRE Configuration<br>
2321 #ShibBasicHijack On<br>
2322 #ShibSSLOnly On<br>
2323 #ShibAuthLifetime 60<br>
2324 #ShibAuthTimeout 600<br>
2326 # RM Configuration<br>
2327 #AuthGroupFile /foo<br>
2328 #ShibExportAssertion On<br>
2329 </Location><br>
2333 <p><b>For information regarding specific error messages that
2334 may be generated if the target does not work successfully,
2335 please refer to section <a href="#4.b.">4.b</a>, or write <a
2337 "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.</b></p>
2340 <h4><a name="5.b."></a>5.b. Common Problems</h4>
2343 <p>A knowledge base is being developed in the <a
2344 href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.
2345 html">Shibboleth Deployer's FAQ</a>. Please mail <a href=
2346 "mailto:mace-shib-users@internet2.edu">mace-shib-users@
2347 internet2.edu</a> with any additional questions or problems
2348 encountered that are not answered by this basic guide.</p>
projects / shibboleth / sp.git / blob