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 <p>Functionality which has been added since the previous
174 version (v0.8) includes:</p>
178 <p>Various improvements to error handling. Origin sites are now
179 able to supply a URL to a federation for users to be referred to
180 when Shibboleth encounters a problem. Targets will be able to
181 utilize this URL in error templates.</p>
185 <p>The SHAR may now store its session and attribute cache in a
186 back-end database in addition to the previously available
187 in-memory option. The method by which <span
188 class="fixedwidth">sites.xml</span> is refreshed has been
189 modified to improve robustness.</p>
193 <p>Attribute acceptance policies have been greatly enhanced,
194 with filtering of attribute values by sites supported.</p>
198 <p>OpenSAML now populates <span
199 class="fixedwidth">AuthType</span> element in the SAML Subject
200 element using a value specified by origin sites using a
201 configuration directive. This value describes the type of
202 authentication mechanism used at the origin site(e.g. Kerberos,
203 PKI, etc.). This value is made available on the target side as
204 another variable that may be used in authorization
209 <p>Origin sites whose HS certificate is not signed by one of a
210 federation's trusted roots are able to provide that federation
211 with the certificate; this cert can now be stored in the sites
212 metadata, and targets will be able to use this certificate to
213 validate the HS' signature.</p>
217 <p>The AA implementation has been improved with a powerful
218 attribute resolver. This should greatly simplify the process of
219 configuring the AA to support additional general attributes,
220 while Java classes may still be written for more complex
225 <p>Local time string values are now used in log files.</p>
229 <p>Targets may now also be run under Apache on a W2K box.</p>
233 <p>Before starting, please sign up for all applicable <a href=
234 "http://shibboleth.internet2.edu/shib-misc.html#mailinglist">
235 mailing lists</a>. Announcements pertinent to Shibboleth
236 deployments and developments and resources for deployment
237 assistance can be found here.</p>
239 <p>Please send any questions, concerns, or eventual confusion
241 "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.
242 This should include, but not be limited to, questions about the
243 documentation, undocumented problems, installation or
244 operational issues, and anything else that arises. Please
245 ensure that you have the <a href=
246 "http://shibboleth.internet2.edu/release/shib-download.html">appropriate
247 tarball</a> for your operating system.</p>
254 <h3><a name="TOC"></a>Shibboleth Target -- Table of
261 <h4><a href="#1."><font color="black">Shibboleth
262 Overview</font></a></h4>
265 <li><a href="#1.a."><font color=
266 "black">Origin</font></a></li>
268 <li><a href="#1.b."><font color=
269 "black">Target</font></a></li>
271 <li><a href="#1.c."><font color=
272 "black">WAYF</font></a></li>
274 <li><a href="#1.d."><font color=
275 "black">Federations</font></a></li>
280 <h4><a href="#2."><font color=
281 "black">Planning</font></a></h4>
284 <li><a href="#2.a."><font color=
285 "black">Requirements</font></a></li>
287 <li><a href="#2.b."><font color="black">Join a
288 Federation</font></a></li>
290 <li><a href="#2.c."><font color="black">Security
291 Considerations</font></a></li>
293 <li><a href="#2.d."><font color="black">Server
294 Certs</font></a></li>
296 <li><a href="#2.e."><font color="black">Attribute Release
297 Policies</font></a></li>
299 <li><a href="#2.f."><font color="black">Designate
300 Contacts</font></a></li>
302 <li><a href="#2.g."><font color="black">Browser
303 Requirements</font></a></li>
305 <li><a href="#2.h."><font color=
306 "black">Clocks</font></a></li>
308 <li><a href="#2.i."><font color="black">Other
309 Considerations</font></a></li>
314 <h4><a href="#3."><font color=
315 "black">Installation</font></a></h4>
318 <li><a href="#3.a."><font color="black">Software
319 Requirements</font></a></li>
321 <li><a href="#3.b."><font color="black">Deploy the
322 Shibboleth Package</font></a></li>
324 <li><a href="#3.c."><font color="black">Configure
325 Apache</font></a></li>
330 <h4><a href="#4."><font color="black">Getting
331 Running</font></a></h4>
334 <li><a href="#4.a."><font color="black">Configuring
335 <span class="fixedwidth">shibboleth.ini</span></font></a></li>
337 <li><a href="#4.b."><font color="black">Dynamic Error
338 Page Generation</font></a></li>
340 <li><a href="#4.c."><font color="black">Key Generation
341 and Certificate Installation</font></a></li>
343 <li><a href="#4.d."><font color="black">Protecting
344 Webpages</font></a></li>
346 <li><a href="#4.e."><font color="black">Designing
347 AAP's</font></a></li>
349 <li><a href="#4.f."><font color="black">Using Attributes
350 in Applications</font></a></li>
352 <li><a href="#4.g."><font color="black"><span
353 class="fixedwidth">siterefresh</span></font></a></li>
358 <h4><a href="#5."><font color=
359 "black">Troubleshooting</font></a></h4>
362 <li><a href="#5.a."><font color="black">Basic
363 Testing</font></a></li>
365 <li><a href="#5.b."><font color="black">Common
366 Problems</font></a></li>
375 <h3><a name="1."></a>1. Shibboleth Overview</h3>
377 <p>Shibboleth is a system designed to exchange attributes
378 across realms for the primary purpose of authorization. It
379 provides a secure framework for one organization to transmit
380 attributes about a web-browsing individual across security
381 domains to another institution. In the primary usage case, when
382 a user attempts to access a resource at a remote domain, the
383 user's own home security domain can send certain information
384 about that user to the target site in a trusted exchange. These
385 attributes can then be used by the resource to help determine
386 whether to grant the user access to the resource. The user may
387 have the ability to decide whether to release specific
388 attributes to certain sites by specifying personal Attribute
389 Release Policies (ARP's), effectively preserving privacy while
390 still granting access based on trusted information.</p>
392 <p>When a user first tries to access a resource protected by
393 Shibboleth, they are redirected to a service which asks the
394 user to specify the organization from which they want to
395 authenticate. If the user has not yet locally authenticated to
396 a WebISO service, the user will then be redirected to their
397 home institution's authentication system. After the user
398 authenticates, the Shibboleth components at the local
399 institution will generate a temporary reference to the user,
400 known as a handle, for the individual and send this to the
401 target site. The target site can then use the handle to ask for
402 attributes about this individual. Based on these attributes,
403 the target can decide whether or not to grant access to the
404 resource. The user may then be allowed to access the requested
407 <p>There are several controls on privacy in Shibboleth, and
408 mechanisms are provided to allow users to determine exactly
409 which information about them is released. A user's actual
410 identity isn't necessary for many access control decisions, so
411 privacy often is needlessly compromised. Instead, the resource
412 often utilizes other attributes such as faculty member or member
413 of a certain class. While these are commonly determined using
414 the identity of the user, Shibboleth provides a way to mutually
415 refer to the same principal without revealing that principal's
416 identity. Because the user is initially known to the target site
417 only by a randomly generated temporary handle, if sufficient,
418 the target site might know no more about the user than that the
419 user is a member of the origin organization. This handle should
420 never be used to decide whether or not to grant access, and is
421 intended only as a temporary reference for requesting
424 <h4><a name="1.a."></a>1.a. Origin</h4>
427 <p>There are four primary components to the origin side in
428 Shibboleth: the Attribute Authority (AA), the Handle Service
429 (HS), the directory service, and the local sign-on system
430 (SSO). The AA and HS are provided with Shibboleth, and an
431 open-source WebISO solution Pubcookie is also supplied; the
432 directory is provided by the origin site. Shibboleth is able
433 to interface with a directory exporting an LDAP interface or a
434 SQL database containing user attributes, and is designed such
435 that programming interfaces to other repositories should be
436 readily implemented. Shibboleth relies on standard web server
437 mechanisms to trigger local authentication. A .htaccess file
438 can be easily used to trigger either the local WebISO system
439 or the web server's own Basic Auth mechanism, which will
440 likely utilize an enterprise authentication system, such as
443 <p>From the origin site's point of view, the first contact
444 will be the redirection of a user to the handle service,
445 which will then consult the SSO system to determine whether
446 the user has already been authenticated. If not, then the
447 browser user will be asked to authenticate, and then sent
448 back to the target URL with a handle bundled in an attribute
449 assertion. Next, a request from the Shibboleth Attribute
450 Requester (SHAR) will arrive at the AA which will include the
451 previously mentioned handle. The AA then consults the ARP's
452 for the directory entry corresponding to the handle, queries
453 the directory for these attributes, and releases to the SHAR
454 all attributes the SHAR is entitled to know about that
458 <h4><a name="1.b."></a>1.b. Target</h4>
461 <p>There are three primary components to the target side in
462 Shibboleth: the Shibboleth Indexical Reference Establisher
463 (SHIRE), the Shibboleth Attribute Requester (SHAR), and the
464 resource manager (RM). An implementation of each of these is
465 included in the standard Shibboleth distribution. These
466 components are intended to run on the same web server.</p>
468 <p>From the target's point of view, a browser will hit the RM
469 with a request for a Shibboleth-protected resource. The RM
470 then allows the SHIRE to step in, which will use the WAYF to
471 acquire the name of a handle service to ask about the user.
472 The handle service (HS) will then reply with a SAML
473 authentication assertion containing a handle, which the SHIRE
474 then hands off to the SHAR. The SHAR uses the handle and the
475 supplied address of the corresponding attribute authority
476 (AA) to request all attributes it is allowed to know about
477 the handle. The SHAR performs some basic validation and
478 analysis based on attribute acceptance policies (AAP's).
479 These attributes are then handed off to the RM, which is
480 responsible for using these attributes to decide whether to
484 <h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
487 <p>The WAYF service can be either outsourced and operated by a
488 federation or deployed as part of the SHIRE. It is responsible for
489 allowing a user to associate themself with an institution of their
490 specification, then redirecting the user to the known address for
491 the handle service of that institution.</p>
494 <h4><a name="1.d."></a>1.d. Federations</h4>
497 <p>A federation provides part of the underlying trust required for
498 function of the Shibboleth architecture. A federation in the
499 context of Shibboleth is a group of organizations(universities,
500 corporations, content providers, etc.) who agree to exchange
501 attributes using the SAML/Shibboleth protocols and abide by a
502 common set of policies and practices. In so doing, they must
503 implicitly or explicitly agree to a common set of guidelines.
504 Joining a federation is not explicitly necessary for operation of
505 Shibboleth, but it dramatically expands the number of targets and
506 origins that can interact without defining bilateral agreements
507 between all these parties.</p>
509 <p>A federation can be created in a variety of formats and trust
510 models, but to support Shibboleth, it must provide a certain set
511 of services to federation members. It needs to supply a registry
512 to process applications to the federation and distribute
513 membership information to the origin and target sites. This must
514 include distribution of the PKI components necessary for trust
515 between origins and targets. There also needs to be a set of
516 agreements and best practices defined by the federation governing
517 the exchange, use, and population of attributes before and after
518 transit, and there should be a way to find information on local
519 authentication and authorization practices for federation
529 <h3><a name="2."></a>2. Planning</h3>
531 <p>There are several essential elements that must be present in
532 the environment to ensure Shibboleth functions well, both
533 political and technical. Shibboleth currently runs on a
534 specific range of platforms and web server environments. The
535 SHAR and SHIRE are implemented entirely in C/C++. These are the
536 recommendations and requirements for a successful implementation
537 of a Shibboleth target.</p>
539 <h4><a name="2.a."></a>2.a. Requirements</h4>
542 <p>Shibboleth currently only supports Linux and Solaris. At
543 present, Shibboleth consists of Apache plugins and a separate SHAR
544 process. The plugins use the ONC RPC mechanism to communicate with
545 the SHAR. The target's web servers must be running <a href=
546 "http://http://www.apache.org/dist/httpd/">Apache</a> 1.3.26+, but
547 not Apache 2. More precise technical details are discussed in <a
548 href="#3.a.">3.a</a>.</p>
551 <h4><a name="2.b."></a>2.b. Join a Federation</h4>
554 <p>While it is not necessary for a target or origin to join a
555 federation, doing so greatly facilitates the implementation of
556 multilateral trust relationships. Each federation will have a
557 different application process.</p>
559 <p>For more information on federations, refer to <a href=
560 "#1.d.">1.d</a> or the Shibboleth v1.0 architectural
564 <h4><a name="2.c."></a>2.c. Security Considerations</h4>
567 <p>Shibboleth's protocols and software have been extensively
568 engineered to provide protection against many attacks.
569 However, the most secure protocol can be compromised if it is
570 placed in an insecure environment. To ensure Shibboleth is as
571 secure as possible, there are several recommended security
572 precautions which should be in place at local sites.</p>
576 <p>SSL use is optional for target sites. Federation guidelines
577 should be considered when determining whether to
578 implement SSL, and, in general, SSL should be used for
579 interactions with client machines to provide the
580 necessary authentication and encryption to ensure
581 protection from man-in-the-middle attacks. It is strongly
582 suggested that all password traffic or similarly
583 sensitive data should be SSL-protected. Assessment of the
584 risk tradeoff against possible performance degradation
585 should be performed for all applications.</p>
589 <p>Many other attacks can be made on the several
590 redirection steps that Shibboleth takes to complete
591 attribute transfer. The best protection against this is
592 safeguarding the WAYF service and ensuring that rogue
593 targets and origins are not used, generally by
594 development of the trust model underneath Shibboleth.
595 Shibboleth also leverages DNS for security, which is not
596 uncommon, but attacks concerning bad domain information
597 should be considered.</p>
601 <p>Information regarding origin users is generally
602 provided by the authoritative enterprise directory, and
603 the acceptance of requests from target applications can
604 be carefully restricted to ensure that all requests the
605 SHAR performs are authorized and all information the
606 origin provides is accurate. Use of plaintext passwords
607 is strongly advised against.</p>
611 <p>Server platforms should be properly secured,
612 commensurate with the level that would be expected for a
613 campus' other security services, and cookie stores on
614 client machines should be well protected.</p>
619 <h4><a name="2.d."></a>2.d. Server Certs</h4>
622 <p>In the Shibboleth architecture, the SHAR, HS, and AA must
623 all have various client and/or server certificates for use in
624 signing assertions and creating SSL channels. These should be
625 issued by a commonly accepted CA, which may be stipulated by
626 your federation. After understanding the CA's acceptible to your
627 federations, consult chapter <a href="#4.c.">4.c</a> for
628 information on certificate and key generation.</p>
631 <h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
634 <p>The Attribute Authority maintains a set of rules called
635 Attribute Release Policies (ARP's) that define which
636 attributes are released to which targets. When a browser user
637 tries to access a resource, the SHAR asks the origin site AA
638 to release all the attributes it is allowed to know. The SHAR
639 provides its own name and an optional URL on behalf of which
640 the attribute request is made which can further refine the
641 information the SHAR is allowed to know. The AA processes this
642 request using all applicable ARP's, determines which
643 attributes and values it will release, and then obtains the
644 values actually associated with the browser user. The AA sends
645 these attributes and values back to the SHAR.</p>
647 <p>Targets should work together with expected origin sites to
648 ensure that the sets of attributes that both sites expect to
649 correspond using are congruent.</p>
652 <h4><a name="2.f."></a>2.f. Designate Contacts</h4>
655 <p>Since Shibboleth deals both with daily technical and
656 operational issues and also with contractual issues, a set of
657 contacts should be set up to support the user base and to
658 facilitate interactions with other Shibboleth sites and federation
659 members. It is recommended that at least technical and
660 administrative contacts be designated. Names, titles, e-mail
661 addresses, and phone numbers may all be useful information to
665 <h4><a name="2.g."></a>2.g. Browser Requirements</h4>
668 <p>A primary Shibboleth design consideration was to require
669 very little or no modification to client machines. The only
670 requirement is that a browser is used which supports cookies,
671 redirection and SSL. Browser users will have to perform an
672 additional click to submit the authentication assertion if
673 JavaScript is not functional.</p>
676 <h4><a name="2.h."></a>2.h. Clocks</h4>
679 <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should
680 be run on all web servers. Shibboleth employs a short handle
681 issuance time to protect against replay attacks. Because of
682 this, any significant degree of clock skew can hinder the
683 ability of users to access sites successfully.</p>
686 <h4><a name="2.h."></a>2.i. Other Considerations</h4>
689 <p>Especially for higher education, there are a handful of
690 laws enacted which may have important ramifications on the
691 disclosure of personal information and attributes. Since
692 Shibboleth does not necessarily need to transmit identity, it
693 is an ideal solution for many higher education situations.
694 Nevertheless, all parties within the United States of America
695 are strongly advised to consult the <a href=
696 "http://www.ed.gov/offices/OM/fpco/ferpa/">Family Educational
697 Rights and Privacy Act of 1974(FERPA)</a>, and all other
698 relevant state and federal legislation before deploying
707 <h3><a name="3."></a>3. Installation</h3>
709 <h4><a name="3.a."></a>3.a. Software Requirements</h4>
711 <p>The Shibboleth project makes binary packages available for
712 Solaris and Linux that are precompiled against recent releases
713 of various required libraries such as OpenSSL. It is highly
714 advisable to build from source when using Shibboleth in a
715 production environment in order to permit patching or updating
716 of packages as security holes and bugs are fixed. Building from
717 source is necessary to give you complete control over your
718 deployment platform. The binary packages represent a snapshot in
719 time only. To build from source, see the <span class="fixedwidth">INSTALL.txt</span>
720 files in the root of the OpenSAML and Shibboleth source
724 <b>Operating System:</b>
732 <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
735 <p>Apache must be compiled with mod_so for DSO
736 module support, and must include SSL
737 support (preferably using <span class="fixedwidth">mod_ssl</span>), and
738 EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
739 provides). Shibboleth can coexist with
740 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
741 into the server for use elsewhere, but Shibboleth
742 does not need or use it. The most recent Red Hat
743 RPM (1.3.23-14 as of this writing) is sufficient.
748 <p>On Linux, Shibboleth requires that Apache and
749 Apache-SSL be built with <span
750 class="fixedwidth">libpthread</span>, or loading the
751 <span class="fixedwidth">mod_shibrm</span> or <span
752 class="fixedwidth">mod_shire</span> modules will
753 cause Apache to stop. While RedHat's Apache is
754 compatible, Debian's Apache must be rebuilt with
755 <span class="fixedwidth">libpthread</span>:</p>
757 <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
758 $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
764 "http://shibboleth.internet2.edu/release/shib-download.html">
765 Shibboleth v1.0 Target for RedHat</a></li>
767 <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
768 revision <span class="fixedwidth">i</span> or newer</a></li>
771 libstdc++3-3.0.4-1.i386.rpm and
772 libgcc-3.0.4-1.i386.rpm
775 <p>Shibboleth binaries are currently built with <a href=
776 "http://www.gnu.org/software/gcc/gcc.html">GCC
777 3.04</a>, and require these specific library
778 versions. They are available as RPMs and are
779 available in the RedHat 7.2 updates directory on
781 "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
782 RedHat mirror</a>. They can be installed alongside
783 earlier and later GCC libraries.</p>
787 <li><b>Portions of the <span
788 class="fixedwidth">libphp4</span> Apache plugin are written
789 in C++, as is Shibboleth. There is a known conflict between
790 the PHP extensions <span
791 class="fixedwidth">libpspell.so</span> and <span
792 class="fixedwidth">libsablot.so</span> which will manifest
793 itself as segmentation faults when starting Apache. If a
794 site wants to use <span class="fixedwidth">libphp4.so</span>
795 and Shibboleth at once, then one of the following may be
799 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
802 Rebuild these two modules using
803 the same version of GCC that was used to compile Shibboleth.
815 "ftp://ftp.openssl.org/source/openssl-0.9.7a.tar.gz">
819 <p>The shared library version of OpenSSL is required
820 by Shibboleth. The static libraries may be installed as
821 well if necessary for other applications, but cannot be
822 used within mod_ssl or any other Apache modules.</p>
827 <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
830 <p>Apache must be compiled with mod_so for DSO
831 module support, and must include SSL
832 support (preferably using <span class="fixedwidth">mod_ssl</span>) and EAPI
833 support (which <span class="fixedwidth">mod_ssl</span> requires and
834 provides). Shibboleth can coexist with
835 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
836 into the server for use elsewhere, but Shibboleth
837 does not need or use it.</p>
839 <p><span class="fixedwidth">mod_ssl</span>'s
840 loadable module, <span class="fixedwidth">libssl.so</span>, must be
841 compiled against <span class="fixedwidth">OpenSSL
842 0.9.7a</span>'s shared libraries. Other versions or
843 a statically linked build of <span
844 class="fixedwidth">libssl.so</span> will cause
845 failures such as bus errors when used with
848 <p>To check how OpenSSL was built, run the <span
849 class="fixedwidth">ldd</span> command against <span
850 class="fixedwidth">libssl.so</span> in the Apache
851 <span class="fixedwidth">/libexec/</span> folder and
852 check the output for references to <span
853 class="fixedwidth">libssl.so.0.9.7a</span>. If you
854 see an earlier version mentioned, or no mention of
855 it at all, then <span class="fixedwidth">OpenSSL
856 0.9.7a</span> must be rebuilt with shared libraries
862 "ftp://ftp.sunfreeware.com/pub/freeware/sparc/8/libgcc-3.2.2-sol8-sparc-local.gz">
863 libgcc v3.2.2+ and libstdc++ v3.2.2+</a></li>
866 "http://shibboleth.internet2.edu/release/shib-download.html">
867 Shibboleth v1.0 Target for Solaris</a></li>
869 <li><b>Portions of the <span
870 class="fixedwidth">libphp4</span> Apache plugin are written
871 in C++, as is Shibboleth. There is a known conflict with
872 the PHP extensions <span
873 class="fixedwidth">libpspell.so</span> and <span
874 class="fixedwidth">libsablot.so</span> which will manifest
875 itself as segmentation faults when starting Apache. If a
876 site wants to use <span class="fixedwidth">libphp4.so</span>
877 and Shibboleth at once, then one of the following may be
881 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
884 Rebuild these two modules using the same version of GCC
885 that was used to compile Shibboleth.
895 <p>RedHat 8 ships with Apache 2, which is not supported by
896 Shibboleth. To run Shibboleth under this OS, <a
897 href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
898 must be installed.</p>
901 <p>Apache must be compiled with mod_so for DSO
902 module support, and must include SSL
903 support (preferably using <span class="fixedwidth">mod_ssl</span>), and
904 EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
905 provides). Shibboleth can coexist with
906 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
907 into the server for use elsewhere, but Shibboleth
908 does not need or use it. The most recent Red Hat
909 RPM (1.3.23-14 as of this writing) is sufficient.
914 <p>On Linux, Shibboleth requires that Apache and
915 Apache-SSL be built with <span
916 class="fixedwidth">libpthread</span>, or loading the
917 <span class="fixedwidth">mod_shibrm</span> or <span
918 class="fixedwidth">mod_shire</span> modules will
919 cause Apache to stop. While RedHat's Apache is
920 compatible, Debian's Apache must be rebuilt with
921 <span class="fixedwidth">libpthread</span>:</p>
923 <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
924 $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
931 "http://shibboleth.internet2.edu/release/shib-download.html">
932 Shibboleth 1.0 Target for RedHat</a></li>
934 <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
935 revision <span class="fixedwidth">i</span> or newer</a></li>
938 libstdc++3-3.0.4-1.i386.rpm and
939 libgcc-3.0.4-1.i386.rpm
942 <p>Shibboleth binaries are currently built with <a href=
943 "http://www.gnu.org/software/gcc/gcc.html">GCC
944 3.04</a>, and require these specific library
945 versions. They are available as RPMs and are
946 available in the RedHat 7.2 updates directory on
948 "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
949 RedHat mirror</a>. They can be installed alongside
950 earlier and later GCC libraries.</p>
954 <li><b>Portions of the <span
955 class="fixedwidth">libphp4</span> Apache plugin are written
956 in C++, as is Shibboleth. There is a known conflict with
957 the PHP extensions <span
958 class="fixedwidth">libpspell.so</span> and <span
959 class="fixedwidth">libsablot.so</span> which will manifest
960 itself as segmentation faults when starting Apache. If a
961 site wants to use <span class="fixedwidth">libphp4.so</span>
962 and Shibboleth at once, then one of the following may be
966 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
969 Rebuild these two modules using
970 the same version of GCC that was used to compile Shibboleth.
979 <h4><a name="3.b."></a>3.b. Deploy the Shibboleth Package</h4>
982 <p>For the sake of clarity, this deployment guide assumes
983 that standard directories are used for all installations.
984 These directories may be changed for local implementations,
985 but must be done so consistently.</p>
989 <p>Ensure that you have obtained the proper <a href=
990 "http://shibboleth.internet2.edu/release/shib-download.html">
991 tarball</a> for your operating system.</p>
995 <p>The tarballs expand into <span class="fixedwidth">/opt/shibboleth</span>,
996 and should be expanded as <span class="fixedwidth">root</span> from <span class="fixedwidth">/</span>.
997 You should see the following directory structure:</p>
1000 <span class="fixedwidth">$ ls -al<br>
1001 drwxr-xr-x 10 root root 4096 Oct 24 03:54 .<br>
1002 drwxr-xr-x 3 root root 4096 Oct 24 00:37 ..<br>
1003 drwxr-xr-x 2 root root 4096 Oct 24 03:54 bin<br>
1004 drwxr-xr-x 2 root root 4096 Oct 24 03:54 doc<br>
1005 drwxr-xr-x 4 root root 4096 Oct 24 03:54 etc<br>
1006 drwxr-xr-x 13 root root 4096 Oct 24 03:54 include<br>
1007 drwxr-xr-x 4 root root 4096 Oct 24 03:55 lib<br>
1008 drwxr-xr-x 2 root root 4096 Oct 24 03:55 libexec<br>
1009 drwxr-xr-x 4 root root 4096 Oct 24 02:02 share<br>
1016 <h4><a name="3.c."></a>3.c. Configure Apache</h4>
1021 <p>Shibboleth includes configuration directives in the
1022 file <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/apache.config</span>
1023 which must be added to the httpd.conf file used locally.
1024 It is recommended that these directives simply be added
1025 to the end of the existing <span class="fixedwidth">httpd.conf</span> file
1026 rather than trying to merge it in-line;
1027 <a href="#3.c.2.">step 2</a> describes the necessary
1028 modifications to the Apache startup script. The default
1029 configuration will often work, but if customization is
1030 necessary, these options may be modified:</p>
1034 <dd class="attribute">
1035 <span class="fixedwidth">LoadModule <module>
1036 <pathname></span>
1040 <p>Specifies the title and location of the
1041 <span class="fixedwidth">shibrm_module</span> resource manager and
1042 <span class="fixedwidth">shire_module</span> SHIRE modules. These are
1043 installed by default at
1044 <span class="fixedwidth">/opt/shibboleth/libexec/mod_shibrm.so</span>
1046 <span class="fixedwidth">/opt/shibboleth/libexec/mod_shire.so</span></p>
1049 <dd class="attribute">
1050 <span class="fixedwidth">SHIREConfig <pathname></span>
1054 <p>Specifies the <span class="fixedwidth">pathname</span> of the SHIRE's
1055 configuration file. Defaults to
1056 <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span>.</p>
1059 <dd class="attribute"><span class="fixedwidth">SHIREURL <url><br>
1060 <Location <url>><br>
1061 SetHandler <method><br>
1062 </Location></span></dd>
1065 <p>Specifies the <span class="fixedwidth">URL</span> and the
1066 <span class="fixedwidth">method</span> the target uses to handle
1067 requests for Shibboleth-protected resources.
1068 Currently, <span class="fixedwidth">shib-shire-post</span> is the only
1069 available handler <span class="fixedwidth">method</span>.
1070 <span class="fixedwidth">SHIREURL</span> is used by Shibboleth when
1071 re-directing the user to the WAYF and
1072 <span class="fixedwidth"><Location></span> by Apache; for this
1073 reason, both <span class="fixedwidth">URL</span> specifications must
1074 match. Note that the configuration file itself
1075 contains <>'s, and <span class="fixedwidth">Location</span> should
1076 not be replaced.</p>
1078 <p>The referenced <span class="fixedwidth">URL</span> can be either a
1079 partial path or an absolute URL. The partial path
1080 allows each virtual server to use its own
1081 hostname and port in the SHIRE for session cookie
1082 purposes, while the absolute URL forces HTTP
1083 virtual servers to use HTTPS for the SHIRE. Use
1084 of a full <span class="fixedwidth">https://</span> URL is advised.</p>
1087 <dd class="attribute">
1088 <span class="fixedwidth">ShibMapAttribute <attribute-uri>
1089 <HTTP-header> [alias]</span>
1093 <p>Registers attributes to be recognized and maps
1094 them to an authorization <span class="fixedwidth">alias</span> for use
1095 in <span class="fixedwidth">.htaccess</span> files or Location Blocks
1096 with <span class="fixedwidth">require</span> directives.
1097 <span class="fixedwidth">REMOTE_USER</span> is a special case, suggested
1098 for use with <span class="fixedwidth">eduPersonPrincipalName</span>, and
1099 is automatically checked by a <span class="fixedwidth">require
1100 user</span> rule.</p>
1107 <a name="3.c.2."></a>
1109 <p>These modifications must be made to the Apache startup
1112 <p>Add the following environment variables:</p>
1115 <span class="fixedwidth">
1116 SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.ini;
1117 export SHIBCONFIG</span>
1120 <p>If the OpenSSL libraries are not in the system's search
1121 path, they should be added to <span class="fixedwidth">LD_LIBRARY_PATH</span> as
1124 <p>If the SHIBCONFIG environment variable is not
1125 specified, Shibboleth will use
1126 <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span> by
1131 <p>The SHAR must be started before Apache. Among other
1132 methods, this can be done either by creating a separate
1133 SHAR startup script or by modifying Apache's RC script to
1134 start/stop the <span class="fixedwidth">SHAR</span> <b>before</b>
1135 <span class="fixedwidth">httpd</span>. It is suggested that Apache's script be
1136 modified by adding:</p>
1139 <span class="fixedwidth">/opt/shibboleth/bin/shar &</span>
1142 <p>Sample <span class="fixedwidth">init.d</span> scripts may be included with
1143 future releases. Ensure that the environment variables
1144 referenced in <a href="#3.c.2">3.c.2</a> are in
1150 <p>The options in <span class="fixedwidth">shibboleth.ini</span> must be
1151 configured as documented in <a href="#4.a.">4.a</a>.
1152 Apache content will then need to be modified for
1153 Shibboleth authentication. This is discussed in <a href=
1154 "#4.d.">4.d</a>. It is recommended that the target then
1155 be tested as detailed in section <a href=
1156 "#5.a.">5.a</a>.</p>
1165 <h3><a name="4."></a>4. Getting Running</h3>
1167 <h4><a name="4.a."></a>4.a. Configuring
1168 <span class="fixedwidth">shibboleth.ini</span></h4>
1171 <p>Most of the configuration for the SHAR, SHIRE, and RM is stored
1172 in the file <span class="fixedwidth">shibboleth.ini</span>. This
1173 file is split into several pre-defined sections. The first
1174 sections, <span class="fixedwidth">general</span>, <span
1175 class="fixedwidth">shire</span>, and <span
1176 class="fixedwidth">shar</span>, define the operational parameters
1177 for the <span class="fixedwidth">SHIRE</span> and <span
1178 class="fixedwidth">SHAR</span>. The <span
1179 class="fixedwidth">general</span> section holds global tags, used
1180 by all pieces. The <span class="fixedwidth">shire</span> and <span
1181 class="fixedwidth">shar</span> sections can override the <span
1182 class="fixedwidth">general</span> tags with SHIRE- or
1183 SHAR-specific configuration. For example, if the SHAR is looking
1184 for a tag, it will look first in the <span
1185 class="fixedwidth">shar</span> section; if it does not find the
1186 tag there, it will proceed to look in the <span
1187 class="fixedwidth">general</span> section. The following
1188 sections, <span class="fixedwidth">metadata_shire</span>, <span
1189 class="fixedwidth">metadata_shar</span>, <span
1190 class="fixedwidth">attributes</span>, and <span
1191 class="fixedwidth">policies</span>, define the trust framework
1192 within the SHIRE and SHAR operate. Example configuration files
1193 are bundled with the Shibboleth distribution.</p>
1195 <p>There is also information that must be configured in
1196 <span class="fixedwidth">/usr/local/apache/conf/httpd.conf</span>; for more
1197 information, refer to <a href="#3.c.2.">3.c</a>.</p>
1199 <p>Information in the logger files referenced by
1200 <span class="fixedwidth">shibboleth.ini</span> may require additional configuration.
1201 It is recommended that after initial installation is
1202 completed, the log level in both files be changed to either
1203 <span class="fixedwidth">INFO</span> or <span class="fixedwidth">WARN</span>.</p>
1205 <p>Fields that are purple are optional; grey fields are
1208 <p><span class="fixedwidth">[general]</span>:</p>
1211 <dd class="attribute">
1212 <span class="fixedwidth">logger = <pathname></span>
1216 <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
1217 configuration file for most Shibboleth events. This
1218 element may also be optionally specified for each of
1219 the components individually. Default logging settings
1220 should suffice. The <span class="fixedwidth">syslog</span> daemon must
1221 accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1222 <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span> to
1223 <span class="fixedwidth">enable logging from remote machines.</span> The
1224 logging levels are defined in the logger
1225 configuration. The configuration format is similar to
1227 href="http://jakarta.apache.org/log4j/docs/
1228 documentation.html">Log4j</a> package's format.</p>
1231 <dd class="attribute">
1232 <span class="fixedwidth">schemadir = <pathname></span>
1236 <p>Specifies the directory in which the XML schema
1237 files are located; defaults to
1238 <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>. Note that
1239 the <span class="fixedwidth">pathname</span> <b>must</b> have a trailing
1240 <span class="fixedwidth">/</span>.</p>
1243 <dd class="attribute">
1244 <span class="fixedwidth">sharsocket = <pathname></span>
1248 <p>Specifies the location of the socket the SHAR uses to
1249 form connections.</p>
1253 <p>The next segment of the <span class="fixedwidth">[general]</span> configuration
1254 section defines server-specific tags in sections defined by
1255 the server name for use by the SHIRE and RM. For example, if
1256 you have a web server at www.example.edu, you can define a
1257 section <span class="fixedwidth">[www.example.edu]</span> and override global tags
1258 with tags for that server only.</p>
1260 <p>The following table lists the server-specific tags. It is
1261 broken into mandatory tags, and optional tags. Tags in the <span
1262 class="fixedwidth">[general]</span> section correspond to all
1263 servers; to override specific tags on a per-server basis, use
1264 <span class="fixedwidth">[<FQDN>]</span> as the header for a
1267 <span class="fixedwidth">[<general>]</span>:
1271 <dd class="attributeopt">
1272 <span class="fixedwidth">normalizeRequest = <true/false></span>
1275 <dd class="valueopt">
1276 <p>If true, all redirects generated by
1277 <span class="fixedwidth">mod_shire</span> will be created using the virtual
1278 server name assigned to the server containing this
1279 command. If <span class="fixedwidth">false</span>, the browser's supplied
1280 URL is used to compute the redirect back.</p>
1283 <dd class="attributeopt">
1284 <span class="fixedwidth">checkIPAddress = <true/false></span>
1287 <dd class="valueopt">
1288 <p>If <span class="fixedwidth">true</span>, Shibboleth will check client
1289 addresses for impersonation protection. In most
1290 circumstances, this should be enabled to prevent
1291 certain attacks concerning stolen cookies. Defaults
1292 to <span class="fixedwidth">false</span>.</p>
1295 <dd class="attributeopt">
1296 <span class="fixedwidth">supportContact = <e-mail></span>
1299 <dd class="valueopt">
1300 <p>Specifies the e-mail address used in the
1301 generation of error pages.</p>
1304 <dd class="attributeopt">
1305 <span class="fixedwidth">logoLocation = <pathname></span>
1308 <dd class="valueopt">
1309 <p>Specifies the location of the logo used in the
1310 generation of error pages. This logo can be in any
1311 format that the web browser will understand.</p>
1314 <dd class="attribute">
1315 <span class="fixedwidth">wayfURL = <url></span>
1319 <p>Specifies the URL of the WAYF service the user is
1320 redirected to. Federations will generally provide this URL
1321 or provide information on how to locally host WAYF's with
1322 a distributed hosts file. Defaults to <span
1323 class="fixedwidth">https://wayf.internet2.edu/InQueue/WAYF</span>.</p>
1326 <dd class="attribute">
1327 <span class="fixedwidth">cookieName = <string></span>
1331 <p>Defines the name to be used for session cookies.</p>
1334 <dd class="attribute">
1335 <span class="fixedwidth">shireSSLOnly = <true/false></span>
1339 <p>If <span class="fixedwidth">true</span>, the SHIRE will reject HTTP
1340 connections that are not SSL-protected. This guards the initial session
1341 sign-on from the browser, but does not preclude non-SSL content. Use of
1342 SSL is strongly recommended; see section <a href=
1343 "#2.c.">2.c</a> for more information.</p>
1346 <dd class="attribute">
1347 <span class="fixedwidth">shireError = <pathname></span>
1351 <p>Specifies the location of the template for the
1352 error page generated when there is an error
1353 re-directing the user to the WAYF or processing a
1357 <dd class="attribute">
1358 <span class="fixedwidth">rmError = <pathname></span>
1362 <p>Specifies the location of the template for the
1363 error page generated if internal errors occur in the
1367 <dd class="attribute">
1368 <span class="fixedwidth">accessError = <pathname></span>
1372 <p>Specifies the location of the template for the
1373 page displayed to users when access to a protected
1374 resource is denied by the RM.</p>
1378 <span class="fixedwidth">[shire]</span>:
1381 <dd class="attribute">
1382 <span class="fixedwidth">logger = <pathname></span>
1386 <p>Specifies the location of a <span class="fixedwidth">log4cpp</span> which
1387 overrides the <span class="fixedwidth">[general]</span> log parameters for
1388 SHIRE events. Default logging settings should
1389 suffice. The <span class="fixedwidth">syslog</span> daemon must accept
1390 <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1391 <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span> to
1392 <span class="fixedwidth">enable logging from remote machines.</span> The
1393 logging levels are defined in the logger
1394 configuration. The configuration format is similar to
1396 href="http://jakarta.apache.org/log4j/docs/
1397 documentation.html">Log4j</a> package's format.</p>
1400 <dd class="attributeopt">
1401 <span class="fixedwidth">aap-uri = <uri></span>
1404 <dd class="valueopt">
1405 <p>Specifies the URI of an attribute acceptance policy XML
1406 file. Attributes must be listed in the <span
1407 class="fixedwidth">aap-uri</span> file if they are to be
1408 visible. For more information, refer to section <a
1409 href="#4.e.">4.e</a>.</p>
1412 <dd class="attributeopt">
1413 <span class="fixedwidth">metadata = <tag></span>
1416 <dd class="valueopt">
1417 <p>Specifies the tag that defines the section of <span
1418 class="fixedwidth">shibboleth.ini</span> the SHIRE should
1419 use to acquire its metadata. The SHIRE does not need trust
1420 metadata, and so generally it will only need sites data to
1421 enforce attribute policies like scope limitations(e.g. MIT
1422 not asserting @brown.edu attributes.)</p>
1426 <span class="fixedwidth">[shar]</span>:
1429 <dd class="attribute">
1430 <span class="fixedwidth">logger = <pathname></span>
1434 <p>Specifies the location of a <span class="fixedwidth">log4cpp</span> which
1435 overrides the <span class="fixedwidth">[general]</span> log parameters for
1436 SHAR events. Default logging settings should suffice.
1437 The <span class="fixedwidth">syslog</span> daemon must accept
1438 <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1439 <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span> to
1440 <span class="fixedwidth">enable logging from remote machines.</span> The
1441 logging levels are defined in the logger
1442 configuration. The configuration format is similar to
1444 href="http://jakarta.apache.org/log4j/docs/
1445 documentation.html">Log4j</a> package's format.</p>
1448 <dd class="attributeopt">
1449 <span class="fixedwidth">metadata = <tag></span>
1452 <dd class="valueopt">
1453 <p>Specifies the tag that defines the section of <span
1454 class="fixedwidth">shibboleth.ini</span> the SHAR should
1455 use to acquire its metadata.</p>
1458 <dd class="attributeopt">
1459 <span class="fixedwidth">certFile = <pathname></span>
1462 <dd class="valueopt">
1463 <p>Specifies the location of the PEM-format
1464 certificate used by the SHAR to communicate with
1468 <dd class="attributeopt">
1469 <span class="fixedwidth">keyFile = <pathname></span>
1472 <dd class="valueopt">
1473 <p>Specifies the location of the PEM-format private
1474 key used by the SHAR to communicate with AA's.</p>
1477 <dd class="attributeopt">
1478 <span class="fixedwidth">keyPass = <password></span>
1481 <dd class="valueopt">
1482 <p>Specifies the <span class="fixedwidth">password</span> used to access the
1483 <span class="fixedwidth">keyfile</span>.</p>
1486 <dd class="attribute">
1487 <span class="fixedwidth">calist = <pathname></span>
1491 <p>Specifies a single file of PEM-format
1492 certificates containing the certificates of root CA's
1493 the SHAR will consider valid signers of AA
1497 <dd class="attribute">
1498 <span class="fixedwidth">AATimeout = <seconds></span>
1502 <p>Specifies the number of seconds that the SHAR will wait
1503 for attributes to be sent from an AA. Defaults to <span
1504 class="fixedwidth">60</span>.</p>
1507 <dd class="attribute">
1508 <span class="fixedwidth">AAConnectTimeout = <seconds></span>
1512 <p>Specifies the number of seconds that the SHAR will wait
1513 for a connection to be established with a remote AA.
1514 Defaults to <span class="fixedwidth">30</span>.</p>
1517 <dd class="attribute">
1518 <span class="fixedwidth">cacheType = <method></span>
1522 <p>Specifies the method used by the SHAR to cache received
1523 attributes. The default is <span
1524 class="fixedwidth">memory</span>, which indicates that
1525 Shibboleth should store received attributes in memory.
1526 Another option is <span
1527 class="fixedwidth">mysql</span>, which will use the MySQL
1528 Credential Cache. The steps to using this are described
1529 in the MySQL Credential Cache guide.</p>
1532 <dd class="attribute">
1533 <span class="fixedwidth">cacheClean = <seconds></span>
1537 <p>Specifies the duration in seconds between cleanups of
1538 the SHAR's cached attributes. Defaults to <span
1539 class="fixedwidth">300</span>, or 5 minutes.</p>
1542 <dd class="attribute">
1543 <span class="fixedwidth">cacheTimeout = <seconds></span>
1547 <p>Specifies the duration in <span
1548 class="fixedwidth">seconds</span> that must elapse
1549 between user accesses before that user's session is
1550 destroyed, including the associated handle and all
1551 cached attributes. Defaults to <span
1552 class="fixedwidth">28800</span> seconds, or 8 hours.</p>
1556 <p><span class="fixedwidth">[metadata]</span> sections must be
1557 created and named in accordance with the value of the <span
1558 class="fixedwidth">metadata</span> parameter in the <span
1559 class="fixedwidth">[shire]</span> and <span
1560 class="fixedwidth">[shar]</span> sections. Metadata sections may
1561 be shared or defined for each component. Two providers are
1562 supported by Shibboleth, but additional providers may be
1563 specified with name/value pairs consisting of <span
1564 class="fixedwidth"><DEFANGED_metadata provider
1565 type>=<source></span>.</p>
1567 <p><span class="fixedwidth">[<metadata>]</span>:</p>
1570 <dd class="attributelong">
1571 <span class="fixedwidth">edu.internet2.middleware.shibboleth.metadata.XML = <pathname></span>
1575 <p>Specifies the location of the file to load site
1576 metadata from. This will often be a <span
1577 class="fixedwidth">sites.xml</span> file stored locally,
1578 and may be used by both the SHIRE and SHAR.</p>
1580 <p>Shibboleth provides a simple utility called <span
1581 class="fixedwidth">siterefresh</span> for updating the
1582 metadata file as described in section <a
1583 href="#4.g.">4.g</a>.</p>
1586 <dd class="attributelong">
1587 <span class="fixedwidth">edu.internet2.middleware.shibboleth.trust.XML = <pathname></span>
1591 <p>Specifies the location of the trust database of
1592 certificates and/or CA roots used by the SHAR during
1593 session initiation. The SHIRE does not need trust
1598 <p>In order for an attribute to be used by Shibboleth, it must be
1599 recognized as valid by the SHAR and implemented with any specific
1600 rules for how to understand and express its value based on the XML
1601 from the AA. Additional string-valued attributes may be added to
1602 the SHAR using the <span class="fixedwidth">[attributes]</span>
1605 <p><span class="fixedwidth">[attributes]</span>:</p>
1608 <dd class="attribute">
1609 <span class="fixedwidth"><attribute_URI>=<type></span>
1613 <p>Attribute names are URI's that are assigned by the
1614 parties standardizing the attribute. Frequently, a
1615 federation or standard object class may define these URI's.
1616 The attribute type may be either <span
1617 class="fixedwidth">scoped</span> or <span
1618 class="fixedwidth">simple</span>, which defines how
1619 the attribute is processed as described in section <a
1620 href="#4.e.">4.e</a>.</p>
1624 <p>The <span class="fixedwidth">[policies]</span> section contains the policy URI
1625 values that control acceptance of assertions from origin
1626 sites. This may eventually have multiple elements associated
1627 it for targets that are members of multiple federations.</p>
1629 <p><span class="fixedwidth">[policies]</span>:</p>
1632 <dd class="attribute">
1633 <span class="fixedwidth"><federation> = <URI></span>
1637 <p>The name of the <span
1638 class="fixedwidth">federation</span> and its
1639 associated policy <span class="fixedwidth">URI</span>.
1640 These URI's will be provided by federations.</p>
1642 <p>This set of URI values is matched against the SAML
1643 <span class="fixedwidth">Audience</span> fields of
1644 assertions received from HS's and AA's. One of the
1645 URI's specified by the origin in <span
1646 class="fixedwidth">edu.internet2.middleware.shibboleth.audiences</span>
1647 must match one of these URIs or the
1648 assertion will not be accepted by design.</p>
1652 <p>Additional sections for individual servers may be defined with
1653 either parameters overriding those found in <span
1654 class="fixedwidth">[general]</span>, or the following additional
1657 <p><span class="fixedwidth">[<FQDN>]</span>:</p>
1660 <dd class="attributeopt">
1661 <span class="fixedwidth">requestAttributes = <attr1> <attr2>
1662 <attr3>...</span>
1665 <dd class="valueopt">
1666 <p>Specifies a space-delimited list of attributes named by
1667 URI that the SHAR will request of an AA. If the parameter
1668 does not exist or is null, then the SHAR will receive all
1669 attributes the AA is willing to release to it.</p>
1675 <h4><a name="4.b."></a>4.b. Dynamic Error Page Generation</h4>
1678 <p>Shibboleth supports the dynamic generation of information
1679 in error pages referenced by <span class="fixedwidth">shibboleth.ini</span>. The
1680 Shib Target employs a special Markup Language Processor to
1681 insert special tags into the generated HTML. The parser will
1682 read the error file looking for any tag that looks like:</p>
1685 <span class="fixedwidth"><shibmlp tag-name /></span>
1688 <p>Shibboleth will replace <span class="fixedwidth">tag-name</span> with the
1689 appropriate markup tag from the table below:</p>
1692 <dd class="attribute"><span class="fixedwidth">supportContact</span></dd>
1694 <dd class="value">The value of the <span class="fixedwidth">supportContact</span> for this
1697 <dd class="attribute"><span class="fixedwidth">logoLocation</span></dd>
1699 <dd class="value">The value of the <span
1700 class="fixedwidth">logoLocation</span> for this server. This
1701 is used to fill in the template error page only; if a custom
1702 error page is created, then the image may be linked to
1703 statically by the page itself.</dd>
1705 <dd class="attribute"><span class="fixedwidth">requestURL</span></dd>
1707 <dd class="value">The user's requested URL.</dd>
1709 <dd class="attribute"><span class="fixedwidth">errorType</span></dd>
1711 <dd class="value">The type of error.</dd>
1713 <dd class="attribute"><span class="fixedwidth">errorText</span></dd>
1715 <dd class="value">The actual error message.</dd>
1717 <dd class="attribute"><span class="fixedwidth">errorDesc</span></dd>
1719 <dd class="value">A textual description of the error intended for human
1723 <p>This configuration is only for Apache servers, and is only
1724 used by resources protected by Shibboleth. See section <a
1725 href= "#4.d.">4.d</a>.</p>
1727 <p>A sample error template is included in the Shibboleth
1728 distribution, and can be triggered by anything that will cause
1729 Shibboleth to be unable to make an authorization decision,
1730 including a bad sites file, certificate chain, or skewed
1735 <h4><a name="4.c."></a>4.c. Key Generation and Certificate
1739 <p>The only target component that must have a private key and
1740 certificate is the SHAR. While the target server itself should support
1741 SSL in most cases, it is mandatory for the SHAR to
1742 authenticate when contacting an AA, and it must therefore be
1743 given a key and an SSL client certificate. It is permissible
1744 for the SHAR to use the same keypair and certificate used by
1745 the target server itself, provided the certificate is signed
1746 by a CA accepted by the community of sites.</p>
1748 <p>The certificate and key should be placed based on whether
1749 they will also be used for Apache's server cert. If they will
1750 be used as a server certificate as well, they should probably
1751 be in the Apache tree in the usual <span class="fixedwidth">mod_ssl</span> spot, and
1752 the SHAR can read them from there. If the SHAR is not running
1753 as <span class="fixedwidth">root</span>, permissions might need to be changed to
1754 allow this access. If the certificate and key will only be
1755 used for the SHAR, they can be put in the same folder with the
1756 <span class="fixedwidth">shibboleth.ini</span> file.</p>
1758 <p>The SHAR is assigned a key and a certificate using
1759 shibboleth.ini's <span class="fixedwidth">certfile</span>, <span class="fixedwidth">keyfile</span> and
1760 <span class="fixedwidth">keypass</span>, described in <a href="#4.a.">4.a</a>. These
1761 files must currently be in PEM format. OpenSSL commands to
1762 generate a new keypair and a certificate request are shown
1763 here, assuming RSA keys are to be used:</p>
1766 <span class="fixedwidth">$ openssl genrsa -des3 -out ssl.key 2048 $ openssl req
1767 -new -key ssl.key -out ssl.csr</span>
1770 <p>The signed certificate file returned by the CA should be
1771 usable directly, or can be converted to PEM format using the
1772 <span class="fixedwidth">openssl x509</span> command.</p>
1774 <p>The key and certificate files can be placed anywhere,
1775 though in or beneath <span class="fixedwidth">/usr/local/apache/conf
1776 directory</span> is a good choice. The Apache child processes,
1777 often running as <span class="fixedwidth">nobody</span>, must be able to read them
1778 while the server is running, which may require permission
1781 <p>This particularly applies when sharing the key and
1782 certificate used by mod_ssl, which are only readable by root
1783 by default. The password, if any, must be placed in the conf
1784 file, since the module cannot prompt for it as the initial
1785 startup of mod_ssl can. The issues surrounding how to
1786 securely obtain a key while running as <span class="fixedwidth">nobody</span> will
1787 be addressed in a later release. Since the password will be
1788 stored in clear text in a frequently examined file, it is
1789 suggested to not reuse a password used elsewhere, or to place
1790 the <span class="fixedwidth">keypass</span> directive in a separate file that is
1791 <span class="fixedwidth">Included</span> in the main configuration file, so that its
1792 permissions can be further restricted.</p>
1794 <p>Finally, the <span class="fixedwidth">calist</span> command provides the SHAR
1795 with a set of CA roots to trust when validating AA server
1796 certificates. In all cases, the SHAR verifies that the
1797 certificate's CN equals the AA's hostname, but the CA root
1798 bundle restricts the accepdl signers to those permitted by
1799 the SHAR. The parameter can be omitted to skip such signer
1803 <h4><a name="4.d."></a>4.d. Protecting Webpages</h4>
1806 <p>Protection of webpages is primarily achieved through
1807 "mapping" attributes provided by an AA to a localized
1808 vocabulary for authorization rules. Each attribute can be
1809 mapped using the <span class="fixedwidth">ShibMapAttribute</span> command to an HTTP
1810 header name where it can subsequently be accessed by
1811 applications, and optionally to an <span class="fixedwidth">alias</span> that can be
1812 used in a <span class="fixedwidth">Require</span> command to search for a matching
1813 value. This mapping command must be in <span class="fixedwidth">httpd.conf</span>,
1814 while the rest of the commands described here appear in
1815 content-specific configuration or <span class="fixedwidth">.htaccess</span>
1818 <p>Any of the typical ways of protecting content may be used
1819 (.htaccess, Directory, Location, Files, etc.). There are two
1820 ways to trigger Shibboleth authentication: specifying an
1821 <span class="fixedwidth">AuthType</span> of <span class="fixedwidth">shibboleth</span> to use Shibboleth
1822 directly, or specifying <span class="fixedwidth">ShibBasicHijack On</span> to
1823 process existing .htaccess files using Shibboleth instead.
1824 Support for authorization consists of mod_auth-style require
1825 directives, as well as support for mod_auth group files.</p>
1827 <p>A complete list of the directives and their values is
1831 <dd class="attribute">
1832 <span class="fixedwidth">AuthType <string></span>
1836 <p>Use <span class="fixedwidth">shibboleth</span> for direct invocation, or
1837 <span class="fixedwidth">Basic</span> plus the <span class="fixedwidth">ShibBasicHijack On</span>
1838 option described below.</p>
1841 <dd class="attribute">
1842 <span class="fixedwidth">ShibSSLOnly<on/off></span>
1846 <p>Controls whether Shibboleth will reject non-SSL
1847 requests from clients. Defaults to <span class="fixedwidth">off</span>.</p>
1850 <dd class="attribute">
1851 <span class="fixedwidth">ShibBasicHijack <on/off></span>
1855 <p>Controls whether Shibboleth should or should not
1856 ignore requests for <span class="fixedwidth">AuthType Basic</span>. Defaults
1857 to <span class="fixedwidth">off</span>.</p>
1860 <dd class="attribute">
1861 <span class="fixedwidth">ShibAuthTimeout <seconds></span>
1865 <p>Sets the maximum number of seconds without any
1866 user activity that a session will remain alive. After
1867 <span class="fixedwidth">seconds</span> seconds without activity, the
1868 session is considered dead. Omission or <span class="fixedwidth">0</span>
1869 results in an arbitrary session timeout.</p>
1872 <dd class="attribute">
1873 <span class="fixedwidth">ShibExportAssertion <on/off></span>
1877 <p>Controls whether the SAML attribute assertion
1878 provided by the AA is exported in a base64-encoded
1879 HTTP header, <span class="fixedwidth">Shib-Attributes</span>. Defaults to
1880 <span class="fixedwidth">off</span>.</p>
1883 <dd class="attribute">
1884 <span class="fixedwidth">ShibAuthLifetime <seconds></span>
1888 <p>Sets the maximum lifetime in seconds that a user
1889 session can survive. Omission or zero results in
1890 arbitrary session lifetime.</p>
1893 <dd class="attribute">
1894 <span class="fixedwidth">AuthGroupFile <pathname></span>
1898 <p>Same as mod_auth; collects EPPN's into a named
1899 group for access control. Note that mod_auth will not
1900 support group files when mod_shibrm is loaded, since
1901 they share the same command.</p>
1906 "http://httpd.apache.org/docs/mod/core.html#require">This
1907 is implemented</a> by placing a <span class="fixedwidth">.htaccess</span>
1908 file that references an <span class="fixedwidth">AuthGroupFile</span> stored
1909 at <span class="fixedwidth">/path</span>:</p>
1912 <span class="fixedwidth">authgroupfile /path<br>
1913 require group workgroup</span>
1916 <p>Note that an <a href=
1917 "http://httpd.apache.org/docs/mod/mod_auth.html#authgroupfile">
1918 AuthGroupFile</a> used by Shibboleth would resemble
1919 <span class="fixedwidth">workgroup: joe@example.edu, jane@demo.edu,
1920 jim@sample.edu</span>.</p>
1924 <dd class="attribute">
1925 <span class="fixedwidth">Require <string></span>
1929 <p>Enforce authorization using one of the following methods.
1930 <b>Please note that <span
1931 class="fixedwidth">valid-user</span> is not a valid access
1932 rule because there it is not clear what <span
1933 class="fixedwidth">valid-user</span> would signify in the
1934 context of Shibboleth</b>.</p>
1940 <span class="fixedwidth">valid-user</span>
1943 <p>Any Shibboleth user from a trusted origin site
1948 <span class="fixedwidth">user</span>
1951 <p>A space-delimited list of EPPN values,
1953 <span class="fixedwidth">urn:mace:eduPerson:1.0:eduPersonPrincipalName</span>
1954 attribute has been mapped to the
1955 <span class="fixedwidth">REMOTE_USER</span> header (as per the earlier
1956 example configuration commands).</p>
1961 <span class="fixedwidth">group</span>
1964 <p>A space-delimited list of group names defined
1965 within <span class="fixedwidth">AuthGroupFile</span> files, again
1966 provided that the mapping to <span class="fixedwidth">REMOTE_USER</span>
1972 <span class="fixedwidth"><alias></span>
1975 <p>An arbitrary rule tag that matches an alias
1976 defined in a <span class="fixedwidth">ShibMapAttribute</span> server
1977 command. The rule value is a space- delimited
1978 list of attribute values, whose format depends on
1979 the attribute in question (e.g. an affiliation
1980 rule might look like <span class="fixedwidth">require affiliation
1981 staff@osu.edu faculty@mit.edu</span>).</p>
1986 <p>Additionally, for <span class="fixedwidth">user</span> and
1987 <span class="fixedwidth"><alias></span>-based rules, if a tilde character
1988 is placed immediately following <span class="fixedwidth">user</span> or
1989 <span class="fixedwidth"><alias></span>, the expressions that follow are
1990 treated as regular expressions.</p>
1992 <p>For example, the regular expression AAP <span
1993 class="fixedwidth">require affiliation ~
1994 ^member@.+\.edu$</span> would evaluate to allowing
1995 anyone with an <span
1996 class="fixedwidth">eduPersonScopedAffiliation</span> of
1997 <span class="fixedwidth">member</span> from a .edu
2005 <h4><a name="4.e."></a>4.e. Designing AAP's</h4>
2008 <p>Shibboleth allows a user and a site to release a varying
2009 set of attributes to a destination site, and does not impose
2010 restrictions on the kinds of attribute information provided
2011 by an AA. Target implementations must also be prepared to
2012 examine the attributes they receive and filter them based on
2013 policies about what information to permit an origin site to
2014 assert about its users.</p>
2016 <p>Attribute acceptance is the process of filtering attribute
2017 values before passing them on to a resource manager, such as
2018 the <span class="fixedwidth">mod_shibrm</span> module. Data blocked by AAP filters
2019 will not be passed to the CGI environment or used when
2020 enforcing <span class="fixedwidth">.htaccess</span> rules.
2021 Note that the attribute assertion exported to the
2022 <span class="fixedwidth">Shib-Attributes</span> header is pre-filtered.</p>
2024 <p>The Shibboleth distribution <span class="fixedwidth">scoped</span> and
2025 <span class="fixedwidth">simple</span> filtering policies for different kinds of
2028 <p><b>An essential part of the Shibboleth trust fabric is ensuring
2029 that sites only assert attributes for domains for which they are
2030 considered authoritative by the target. Typically, this means
2031 that Brown University will be trusted to assert attributes only
2032 scoped to <span class="fixedwidth">*brown.edu</span>. Unless
2033 there are very specific circumstances requiring this restriction
2034 be removed, it is strongly encouraged that it be included in any
2035 and all AAP's.</b></p>
2039 <p>Scoped attributes are a special kind of attribute whose
2040 values are a combination of a <span class="fixedwidth">value</span> and a
2041 <span class="fixedwidth">scope</span>, or <span class="fixedwidth">context</span> for the value. An
2042 example is <span class="fixedwidth">eduPersonScopedAffiliation</span>, which adds a
2043 scope to the defined set of <span class="fixedwidth">eduPersonAffiliation</span>
2044 values, such as <span class="fixedwidth">student</span>, <span class="fixedwidth">member</span>, or
2045 <span class="fixedwidth">faculty</span>. Scopes are expressed as DNS domains and
2048 <p>Any <span class="fixedwidth">scoped</span> attribute can be
2049 scoped only to the origin site's permitted domains. These
2050 domains are listed in the sites file that provides trust
2051 information to the system. Domains can be explicit or
2052 regular expressions, and can be changed by a target to meet
2053 its needs if a local version of the file is created. Thus,
2054 attribute acceptance processing for <span class="fixedwidth">scoped</span>
2055 attributes is based on the sites file.</p>
2060 <p>Simple attributes are attributes whose value is expressed
2061 in XML as a Text node; that is, the value is just a string.
2062 Multiple values are permitted.
2063 <span class="fixedwidth">eduPersonEntitlement</span>, in which the values are URIs,
2064 is one example of a simple attribute.</p>
2065 <p>In this release, simple attribute acceptance is
2066 controlled with an external policy file written in XML. The
2067 schema for the file is described by the
2068 <span class="fixedwidth">eduPerson.xsd</span> schema, and an example file is
2069 included, <span class="fixedwidth">AAP.xml</span>. If the <span class="fixedwidth">aap-uri</span>
2070 parameter in the <span class="fixedwidth">shibboleth.ini</span> file is left out,
2071 then no policy is applied, and no filtering is done.
2072 Otherwise, the rules encoded in the file are used.</p>
2073 <p>The policy is a default-deny algorithm that requires
2074 permissible attributes and values be listed explicitly. That
2075 is, an empty file permits nothing. Each attribute to be
2076 permitted must be listed in the file by name in an
2077 <span class="fixedwidth"><AttributeRule></span>. Each such rule is a
2078 collection of <span class="fixedwidth"><SiteRule></span> elements along with
2079 an optional <span class="fixedwidth"><AnySite></span> default rule. In turn
2080 each site rule is a set of <span class="fixedwidth"><Value></span> rules that
2081 specify matches to permit, either literal or regular
2085 <p>A syntax summary follows:</p>
2088 <p><span class="fixedwidth"><AttributeAcceptancePolicy</span></p>
2089 <blockquote>The top level element in the
2092 <p><span class="fixedwidth"><AttributeRule Name="attribute
2093 URI"></span></p>
2094 <blockquote>Specifies a rule for an attribute, named with
2095 its URI.</blockquote>
2096 <p><span class="fixedwidth"><AnySite></span></p>
2097 <blockquote>Specifies a rule that always applies to the
2098 attribute, regardless of the asserting AA.</blockquote>
2100 <p><span class="fixedwidth"><SiteRule
2101 Name="site.domain.name"></span></p>
2102 <blockquote>A rule that applies to the origin site AA
2103 corresponding to the domain name.</blockquote>
2105 <p><span class="fixedwidth"><Value Type="type"></span></p>
2106 <blockquote>Specifies a value to permit, either directly
2107 using <span class="fixedwidth">type</span> <span class="fixedwidth">literal</span>, or using a set of
2108 matching expressions as <span class="fixedwidth">type</span> <span class="fixedwidth">regexp</span>.
2109 <span class="fixedwidth">literal</span> is the default if <span class="fixedwidth">Type</span> is not
2110 specified.</blockquote>
2114 <p>The regular expression syntax is a subset of the usual
2115 Perl and Unix syntaxes that is described in the XML Schema
2116 specification by the W3C. Most typical expressions should
2117 work. Be sure to anchor them using <span class="fixedwidth">^</span> and <span class="fixedwidth">$</span>
2118 to avoid unintentional matches midstring.</p>
2120 <p>Note that the AAP rules described in this section are not
2121 part of the Shibboleth architecture and are simply one
2122 possible set of approaches implemented in the
2123 <span class="fixedwidth">eduPerson</span> attribute plugin. The OpenSAML API permits
2124 attribute classes to derive from <span class="fixedwidth">SAMLAttribute</span> and
2125 override the accept() method to implement
2126 application-specific AAP requirements. The eduPerson source
2127 files can be used as an example of how to build highly
2128 customized rules.</p>
2131 <h4><a name="4.f."></a>4.f. Using Attributes in
2135 <p>Apart from the simple RM functionality provided, attribute
2136 information may be made available directly to applications
2137 via the standard practice of creating custom HTTP request
2138 headers before passing control to the application.
2139 Applications should make no assumption about the presence of
2140 specific attributes for their use unless they have intimate
2141 knowledge of the attribute release policies in place.</p>
2143 <p>The <span class="fixedwidth">ShibMapAttribute</span> directive controls this
2144 interface, and maps a Shibboleth attribute (identified by an
2145 unambiguous URI) to a header name, such as
2146 <span class="fixedwidth">Shib-EP-Affiliation</span>. Using that example, any values
2147 of the mapped attribute will be placed in that header,
2148 delimited by spaces. An application that uses a CGI-like
2149 syntax to access the header will find the values in the
2150 <span class="fixedwidth">HTTP_SHIB_EP_AFFILIATION</span> variable. Using the
2151 command, any attribute can be placed in any header, to drive
2152 legacy applications that expect information in a particular
2155 <p>The <span class="fixedwidth">REMOTE_USER</span> variable is a special case that
2156 is generally populated automatically by the web server based
2157 on an internal piece of data that represents the user's
2158 <span class="fixedwidth">username</span>. Unlike many authentication modules,
2159 Shibboleth does not guarantee that <span class="fixedwidth">REMOTE_USER</span> will
2160 have any value. If it does, it is set solely based on a
2161 <span class="fixedwidth">ShibMapAttribute</span> command. For most purposes, the
2162 <span class="fixedwidth">urn:mace:eduPerson:1.0:eduPersonPrincipalName</span>
2163 attribute should be mapped to <span class="fixedwidth">REMOTE_USER</span>. Even so,
2164 EPPN may not be provided by the AA, and <span class="fixedwidth">REMOTE_USER</span>
2165 might still be empty.</p>
2167 <p>Finally, the <span class="fixedwidth">ShibExportAssertion</span> flag instructs
2168 the module to place the entire XML message containing the
2169 SAML attribute information from the AA into a base64-encoded
2170 header called <span class="fixedwidth">Shib-Attributes</span>. This is a raw
2171 interface that provides an application with the entire AA
2172 response, and is not a filtered view based on any attribute
2173 acceptance rules or even based on what attributes are
2174 recognized by the target. What was sent is what you see.</p>
2177 <h4><a name="4.g."></a>4.g. <span
2178 class="fixedwidth">siterefresh</span></h4>
2181 <p>Shibboleth provides a simple tool called <span
2182 class="fixedwidth">siterefresh</span> in the <span
2183 class="fixedwidth">/opt/shibboleth/bin</span> folder of the
2184 distribution to maintain metadata files referenced by <span
2185 class="fixedwidth">shibboleth.ini</span>. It will return 0 on
2186 success and a negative number on failure and log errors to <span
2187 class="fixedwidth">stderr</span>. If the data in the new metadata
2188 file is bad or the signature is invalid, the existing copy is
2189 kept. The SHAR and SHIRE stat the file each time the data is
2190 used, allowing them to detect and utilize updates in real-time
2193 <p><span class="fixedwidth">siterefresh</span> takes the following
2194 command-line parameters:</p>
2197 <dd class="attribute">
2198 <span class="fixedwidth">--url <URL></span>
2202 <p>Specifies the <span class="fixedwidth">URL</span> of the
2203 remote metadata file to update the local file.</p>
2206 <dd class="attribute">
2207 <span class="fixedwidth">--out <pathname></span>
2211 <p>Specifies the local file to write the new metadata to.</p>
2214 <dd class="attributeopt">
2215 <span class="fixedwidth">--cert <pathname></span>
2218 <dd class="valueopt">
2219 <p>Specifies the location of a certificate stored in <span
2220 class="fixedwidth">PEM</span> format used to validate the
2221 signature of the metadata file. Since much of Shibboleth's
2222 trust flows from this metadata file, this option is highly
2226 <dd class="attributeopt">
2227 <span class="fixedwidth">--schema <pathname></span>
2230 <dd class="valueopt">
2231 <p>Optionally defines a base path for schemas. Defaults to
2233 class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>.</p>
2237 <p>A complete command issued to <span
2238 class="fixedwidth">siterefresh</span> would take the form:</p>
2240 <blockquote><span class="fixedwidth">
2241 /opt/shibboleth/bin/siterefresh --url
2242 http://wayf.internet2.edu/InQueue/sites.xml --out sites.xml
2243 --cert internet2.pem
2244 </span></blockquote>
2246 <p>It is recommended that a similar command be added to a <span
2247 class="fixedwidth">crontab</span> to keep the file refreshed.</p>
2255 <h3><a name="5."></a>5. Troubleshooting</h3>
2257 <p>This section provides basic information about testing
2258 Shibboleth targets. This information is not intended to be
2259 comprehensive, but instead rudimentary guidelines for basic
2260 configuration tests and problems. For more detailed information
2261 or answers to specific problems not addressed in this section,
2262 please mail <a href=
2263 "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>
2264 with a thorough description of errors and configurations
2267 <h4><a name="5.a."></a>5.a. Basic Testing</h4>
2270 <p>The target may be tested by generating a folder with very
2271 basic access controls on it, and accessing it using a web
2272 browser. Place a simple webpage such as <span class="fixedwidth">index.html</span>
2273 in <span class="fixedwidth">/secure/</span>. Then, add the following lines to
2274 <span class="fixedwidth">httpd.conf</span>, which should be removed when testing is
2278 <span class="fixedwidth"># Configure a test directory<br>
2279 <Location /secure><br>
2280 AuthType shibboleth<br>
2281 require valid-user<br>
2283 # Per-directory SHIRE Configuration<br>
2284 #ShibBasicHijack On<br>
2285 #ShibSSLOnly On<br>
2286 #ShibAuthLifetime 60<br>
2287 #ShibAuthTimeout 600<br>
2289 # RM Configuration<br>
2290 #AuthGroupFile /foo<br>
2291 #ShibExportAssertion On<br>
2292 </Location><br>
2296 <p><b>For information regarding specific error messages that
2297 may be generated if the target does not work successfully,
2298 please refer to section <a href="#4.b.">4.b</a>, or write <a
2300 "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.</b></p>
2303 <h4><a name="5.b."></a>5.b. Common Problems</h4>
2306 <p>A knowledge base is being developed in the <a
2307 href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.
2308 html">Shibboleth Deployer's FAQ</a>. Please mail <a href=
2309 "mailto:mace-shib-users@internet2.edu">mace-shib-users@
2310 internet2.edu</a> with any additional questions or problems
2311 encountered that are not answered by this basic guide.</p>