Various corrections, removing obsolete info.
[java-idp.git] / doc / DEPLOY-GUIDE-TARGET.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3 <html>
4   <head>
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">
9
10 html
11 {       
12 background-color: #FFFFFF;
13 color: #000000;
14 margin: .5em;
15 }
16 a:visited
17 {
18 color: #999999;
19 }
20 a:link
21 {
22 color: #990000;
23 }
24 a:active
25 {
26 color: #440000;
27 }
28 dl
29 {
30 background-color: #DDDDDD;
31 background-image: none;
32 margin: 5px;
33 padding: 0px;
34 border-style: solid;
35 border-bottom-width: 2px;
36 border-top-width: 2px;
37 border-left-width: 2px;
38 border-right-width: 2px;
39 }
40 dt
41 {
42 background-color: #DDDDDD;
43 background-image: none;
44 margin: 1px;
45 padding: 1px;
46 }
47 dd
48 {
49 background-color: #DDDDDD;
50 background-image: none;
51 margin: 0px;
52 padding: 1px;
53 }
54 .attribute
55 {
56 font-size: 115%;
57 font-color: #000000;
58 text-align: left;
59 background-color: #DDDDDD;
60 border: 1px black inset;
61 background-image: none;
62 margin: 0px;
63 padding: 2px;
64 }
65 .value
66 {
67 font-color: #000000;
68 text-align: left;
69 background-color: #EEEEEE;
70 background-image: none;
71 padding-top: 0em;
72 padding-bottom: 0.5em;
73 padding-right: 1em;
74 padding-left: 5em;
75 border-style: solid;
76 border-bottom-width: none;
77 border-top-width: none;
78 border-left-width: 1px;
79 border-right-width: 1px;
80 }
81 .attributeopt
82 {
83 font-size: 115%;
84 font-color: #000000;
85 text-align: left;
86 background-color: #BCBCEE;
87 border: 1px black inset;
88 background-image: none;
89 margin: 0px;
90 padding: 2px;
91 }
92 .valueopt
93 {
94 font-color: #000000;
95 text-align: left;
96 background-color: #DDDDFF;
97 background-image: none;
98 padding-top: 0em;
99 padding-bottom: 0.5em;
100 padding-right: 1em;
101 padding-left: 5em;
102 border-style: solid;
103 border-bottom-width: none;
104 border-top-width: none;
105 border-left-width: 1px;
106 border-right-width: 1px;
107 }
108 .attributelong
109 {
110 font-size: 85%;
111 font-color: #000000;
112 text-align: left;
113 background-color: #DDDDDD;
114 border: 1px black inset;
115 background-image: none;
116 margin: 0px;
117 padding: 2px;
118 }
119 .attributeoptlong
120 {
121 font-size: 85%;
122 font-color: #000000;
123 text-align: left;
124 background-color: #BCBCEE;
125 border: 1px black inset;
126 background-image: none;
127 margin: 0px;
128 padding: 2px;
129 }
130 .demo
131 {
132 background-color: #EEEEEE;
133 padding: 3px;
134 }
135 .fixedwidth
136 {
137 font-family: monospace;
138 font-size: 90%;
139 font-color: #121212;
140 }
141
142   </style>
143   </head>
144
145   <body link="red" vlink="red" alink="black" bgcolor="white">
146     <center>
147       <h2>Shibboleth Target Deployment Guide</h2>
148     </center>
149     
150     Shibboleth Target Deployment Guide<br>
151     draft-internet2-mace-shibboleth-shib-target-deploy-33.html<br>
152     Nate Klingenstein<br>
153     9 June, 2003<br>
154     Comments should be directed to <a href=
155     "mailto:ndk@internet2.edu">ndk@internet2.edu</a>.<br>
156
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>
160
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>
164
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>
172
173     <p>Functionality which has been added since the previous
174     version (v0.8) includes:</p>
175
176     <ul>
177       <li>
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>
182       </li>
183
184       <li>
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>
190       </li>
191
192       <li>
193         <p>Attribute acceptance policies have been greatly enhanced,
194         with filtering of attribute values by sites supported.</p>
195       </li>
196
197       <li>
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
205         decisions.</p>
206       </li>
207
208       <li>
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>
214       </li>
215
216       <li>
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
221         evaluations.</p>
222       </li>
223
224       <li>
225         <p>Local time string values are now used in log files.</p>
226       </li>
227     </ul>
228
229     <p>Before starting, please sign up for all applicable <a href=
230     "http://shibboleth.internet2.edu/shib-misc.html#mailinglist">
231     mailing lists</a>. Announcements pertinent to Shibboleth
232     deployments and developments and resources for deployment
233     assistance can be found here.</p>
234
235     <p>Please send any questions, concerns, or eventual confusion
236     to <a href=
237     "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.
238     This should include, but not be limited to, questions about the
239     documentation, undocumented problems, installation or
240     operational issues, and anything else that arises. Please
241     ensure that you have the <a href=
242     "http://shibboleth.internet2.edu/release/shib-download.html">appropriate
243     tarball</a> for your operating system.</p>
244     <br>
245     <hr>
246     <br>
247     <br>
248
249
250     <h3><a name="TOC"></a>Shibboleth Target -- Table of
251     Contents</h3>
252     <br>
253
254
255     <ol type="1">
256       <li>
257         <h4><a href="#1."><font color="black">Shibboleth
258         Overview</font></a></h4>
259
260         <ol type="a">
261           <li><a href="#1.a."><font color=
262           "black">Origin</font></a></li>
263
264           <li><a href="#1.b."><font color=
265           "black">Target</font></a></li>
266
267           <li><a href="#1.c."><font color=
268           "black">WAYF</font></a></li>
269
270           <li><a href="#1.d."><font color=
271           "black">Federations</font></a></li>
272         </ol>
273       </li>
274
275       <li>
276         <h4><a href="#2."><font color=
277         "black">Planning</font></a></h4>
278
279         <ol type="a">
280           <li><a href="#2.a."><font color=
281           "black">Requirements</font></a></li>
282
283           <li><a href="#2.b."><font color="black">Join a
284           Federation</font></a></li>
285
286           <li><a href="#2.c."><font color="black">Security
287           Considerations</font></a></li>
288
289           <li><a href="#2.d."><font color="black">Server
290           Certs</font></a></li>
291
292           <li><a href="#2.e."><font color="black">Attribute Release
293           Policies</font></a></li>
294
295           <li><a href="#2.f."><font color="black">Designate
296           Contacts</font></a></li>
297
298           <li><a href="#2.g."><font color="black">Browser
299           Requirements</font></a></li>
300
301           <li><a href="#2.h."><font color=
302           "black">Clocks</font></a></li>
303
304           <li><a href="#2.i."><font color="black">Other
305           Considerations</font></a></li>
306         </ol>
307       </li>
308
309       <li>
310         <h4><a href="#3."><font color=
311         "black">Installation</font></a></h4>
312
313         <ol type="a">
314           <li><a href="#3.a."><font color="black">Software
315           Requirements</font></a></li>
316
317           <li><a href="#3.b."><font color="black">Deploy the
318           Shibboleth Package</font></a></li>
319
320           <li><a href="#3.c."><font color="black">Configure
321           Apache</font></a></li>
322         </ol>
323       </li>
324
325       <li>
326         <h4><a href="#4."><font color="black">Getting
327         Running</font></a></h4>
328
329         <ol type="a">
330           <li><a href="#4.a."><font color="black">Configuring
331           <span class="fixedwidth">shibboleth.ini</span></font></a></li>
332
333           <li><a href="#4.b."><font color="black">Dynamic Error
334           Page Generation</font></a></li>
335
336           <li><a href="#4.c."><font color="black">Key Generation
337           and Certificate Installation</font></a></li>
338
339           <li><a href="#4.d."><font color="black">Protecting
340           Webpages</font></a></li>
341
342           <li><a href="#4.e."><font color="black">Designing
343           AAP's</font></a></li>
344
345           <li><a href="#4.f."><font color="black">Using Attributes
346           in Applications</font></a></li>
347
348           <li><a href="#4.g."><font color="black"><span
349           class="fixedwidth">siterefresh</span></font></a></li>
350         </ol>
351       </li>
352
353       <li>
354         <h4><a href="#5."><font color=
355         "black">Troubleshooting</font></a></h4>
356
357         <ol type="a">
358           <li><a href="#5.a."><font color="black">Basic
359           Testing</font></a></li>
360
361           <li><a href="#5.b."><font color="black">Common
362           Problems</font></a></li>
363         </ol>
364       </li>
365     </ol>
366     <br>
367     <hr>
368     <br>
369      
370
371     <h3><a name="1."></a>1. Shibboleth Overview</h3>
372
373     <p>Shibboleth is a system designed to exchange attributes
374     across realms for the primary purpose of authorization. It
375     provides a secure framework for one organization to transmit
376     attributes about a web-browsing individual across security
377     domains to another institution. In the primary usage case, when
378     a user attempts to access a resource at a remote domain, the
379     user's own home security domain can send certain information
380     about that user to the target site in a trusted exchange. These
381     attributes can then be used by the resource to help determine
382     whether to grant the user access to the resource. The user may
383     have the ability to decide whether to release specific
384     attributes to certain sites by specifying personal Attribute
385     Release Policies (ARP's), effectively preserving privacy while
386     still granting access based on trusted information.</p>
387
388     <p>When a user first tries to access a resource protected by
389     Shibboleth, they are redirected to a service which asks the
390     user to specify the organization from which they want to
391     authenticate. If the user has not yet locally authenticated to
392     a WebISO service, the user will then be redirected to their
393     home institution's authentication system. After the user
394     authenticates, the Shibboleth components at the local
395     institution will generate a temporary reference to the user,
396     known as a handle, for the individual and send this to the
397     target site. The target site can then use the handle to ask for
398     attributes about this individual. Based on these attributes,
399     the target can decide whether or not to grant access to the
400     resource. The user may then be allowed to access the requested
401     materials.</p>
402
403     <p>There are several controls on privacy in Shibboleth, and
404     mechanisms are provided to allow users to determine exactly
405     which information about them is released. A user's actual
406     identity isn't necessary for many access control decisions, so
407     privacy often is needlessly compromised. Instead, the resource
408     often utilizes other attributes such as faculty member or member
409     of a certain class. While these are commonly determined using
410     the identity of the user, Shibboleth provides a way to mutually
411     refer to the same principal without revealing that principal's
412     identity. Because the user is initially known to the target site
413     only by a randomly generated temporary handle, if sufficient,
414     the target site might know no more about the user than that the
415     user is a member of the origin organization. This handle should
416     never be used to decide whether or not to grant access, and is
417     intended only as a temporary reference for requesting
418     attributes.</p>
419
420     <h4><a name="1.a."></a>1.a. Origin</h4>
421
422     <blockquote>
423       <p>There are four primary components to the origin side in
424       Shibboleth: the Attribute Authority (AA), the Handle Service
425       (HS), the directory service, and the local sign-on system
426       (SSO). The AA and HS are provided with Shibboleth, and an
427       open-source WebISO solution Pubcookie is also supplied; the
428       directory is provided by the origin site. Shibboleth is able
429       to interface with a directory exporting an LDAP interface or a
430       SQL database containing user attributes, and is designed such
431       that programming interfaces to other repositories should be
432       readily implemented. Shibboleth relies on standard web server
433       mechanisms to trigger local authentication. A .htaccess file
434       can be easily used to trigger either the local WebISO system
435       or the web server's own Basic Auth mechanism, which will
436       likely utilize an enterprise authentication system, such as
437       Kerberos.</p>
438
439       <p>From the origin site's point of view, the first contact
440       will be the redirection of a user to the handle service,
441       which will then consult the SSO system to determine whether
442       the user has already been authenticated. If not, then the
443       browser user will be asked to authenticate, and then sent
444       back to the target URL with a handle bundled in an attribute
445       assertion. Next, a request from the Shibboleth Attribute
446       Requester (SHAR) will arrive at the AA which will include the
447       previously mentioned handle. The AA then consults the ARP's
448       for the directory entry corresponding to the handle, queries
449       the directory for these attributes, and releases to the SHAR
450       all attributes the SHAR is entitled to know about that
451       user.</p>
452     </blockquote>
453
454     <h4><a name="1.b."></a>1.b. Target</h4>
455
456     <blockquote>
457       <p>There are three primary components to the target side in
458       Shibboleth: the Shibboleth Indexical Reference Establisher
459       (SHIRE), the Shibboleth Attribute Requester (SHAR), and the
460       resource manager (RM). An implementation of each of these is
461       included in the standard Shibboleth distribution. These
462       components are intended to run on the same web server.</p>
463
464       <p>From the target's point of view, a browser will hit the RM
465       with a request for a Shibboleth-protected resource. The RM
466       then allows the SHIRE to step in, which will use the WAYF to
467       acquire the name of a handle service to ask about the user.
468       The handle service (HS) will then reply with a SAML
469       authentication assertion containing a handle, which the SHIRE
470       then hands off to the SHAR. The SHAR uses the handle and the
471       supplied address of the corresponding attribute authority
472       (AA) to request all attributes it is allowed to know about
473       the handle. The SHAR performs some basic validation and
474       analysis based on attribute acceptance policies (AAP's).
475       These attributes are then handed off to the RM, which is
476       responsible for using these attributes to decide whether to
477       grant access.</p>
478     </blockquote>
479
480     <h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
481
482     <blockquote>
483       <p>The WAYF service can be either outsourced and operated by a
484       federation or deployed as part of the SHIRE. It is responsible for
485       allowing a user to associate themself with an institution of their
486       specification, then redirecting the user to the known address for
487       the handle service of that institution.</p>
488     </blockquote>
489
490     <h4><a name="1.d."></a>1.d. Federations</h4>
491
492     <blockquote>
493       <p>A federation provides part of the underlying trust required for
494       function of the Shibboleth architecture. A federation in the
495       context of Shibboleth is a group of organizations(universities,
496       corporations, content providers, etc.) who agree to exchange
497       attributes using the SAML/Shibboleth protocols and abide by a
498       common set of policies and practices. In so doing, they must
499       implicitly or explicitly agree to a common set of guidelines.
500       Joining a federation is not explicitly necessary for operation of
501       Shibboleth, but it dramatically expands the number of targets and
502       origins that can interact without defining bilateral agreements
503       between all these parties.</p>
504
505       <p>A federation can be created in a variety of formats and trust
506       models, but to support Shibboleth, it must provide a certain set
507       of services to federation members. It needs to supply a registry
508       to process applications to the federation and distribute
509       membership information to the origin and target sites. This must
510       include distribution of the PKI components necessary for trust
511       between origins and targets. There also needs to be a set of
512       agreements and best practices defined by the federation governing
513       the exchange, use, and population of attributes before and after
514       transit, and there should be a way to find information on local
515       authentication and authorization practices for federation
516       members.</p>
517     </blockquote>
518     <br>
519     <br>
520     <br>
521     <hr>
522     <br>
523      
524
525     <h3><a name="2."></a>2. Planning</h3>
526
527     <p>There are several essential elements that must be present in
528     the environment to ensure Shibboleth functions well, both
529     political and technical. Shibboleth currently runs on a
530     specific range of platforms and web server environments. The
531     SHAR and SHIRE are implemented entirely in C/C++. These are the
532     recommendations and requirements for a successful implementation
533     of a Shibboleth target.</p>
534
535     <h4><a name="2.a."></a>2.a. Requirements</h4>
536
537     <blockquote>
538       <p>Shibboleth currently only supports Linux and Solaris. At
539       present, Shibboleth consists of Apache plugins and a separate SHAR
540       process. The plugins use the ONC RPC mechanism to communicate with
541       the SHAR. The target's web servers must be running <a href=
542       "http://http://www.apache.org/dist/httpd/">Apache</a> 1.3.26+, but
543       not Apache 2. More precise technical details are discussed in <a
544       href="#3.a.">3.a</a>.</p>
545     </blockquote>
546
547     <h4><a name="2.b."></a>2.b. Join a Federation</h4>
548
549     <blockquote>
550       <p>While it is not necessary for a target or origin to join a
551       federation, doing so greatly facilitates the implementation of
552       multilateral trust relationships. Each federation will have a
553       different application process.</p>
554
555       <p>For more information on federations, refer to <a href=
556       "#1.d.">1.d</a> or the Shibboleth v1.0 architectural
557       document.</p>
558     </blockquote>
559
560     <h4><a name="2.c."></a>2.c. Security Considerations</h4>
561
562     <blockquote>
563       <p>Shibboleth's protocols and software have been extensively
564       engineered to provide protection against many attacks.
565       However, the most secure protocol can be compromised if it is
566       placed in an insecure environment. To ensure Shibboleth is as
567       secure as possible, there are several recommended security
568       precautions which should be in place at local sites.</p>
569
570       <ol type="i">
571         <li>
572           <p>SSL use is optional for target sites. Federation guidelines
573           should be considered when determining whether to
574           implement SSL, and, in general, SSL should be used for
575           interactions with client machines to provide the
576           necessary authentication and encryption to ensure
577           protection from man-in-the-middle attacks. It is strongly
578           suggested that all password traffic or similarly
579           sensitive data should be SSL-protected. Assessment of the
580           risk tradeoff against possible performance degradation
581           should be performed for all applications.</p>
582         </li>
583
584         <li>
585           <p>Many other attacks can be made on the several
586           redirection steps that Shibboleth takes to complete
587           attribute transfer. The best protection against this is
588           safeguarding the WAYF service and ensuring that rogue
589           targets and origins are not used, generally by
590           development of the trust model underneath Shibboleth.
591           Shibboleth also leverages DNS for security, which is not
592           uncommon, but attacks concerning bad domain information
593           should be considered.</p>
594         </li>
595
596         <li>
597           <p>Information regarding origin users is generally
598           provided by the authoritative enterprise directory, and
599           the acceptance of requests from target applications can
600           be carefully restricted to ensure that all requests the
601           SHAR performs are authorized and all information the
602           origin provides is accurate. Use of plaintext passwords
603           is strongly advised against.</p>
604         </li>
605
606         <li>
607           <p>Server platforms should be properly secured,
608           commensurate with the level that would be expected for a
609           campus' other security services, and cookie stores on
610           client machines should be well protected.</p>
611         </li>
612       </ol>
613     </blockquote>
614
615     <h4><a name="2.d."></a>2.d. Server Certs</h4>
616
617     <blockquote>
618       <p>In the Shibboleth architecture, the SHAR, HS, and AA must
619       all have various client and/or server certificates for use in
620       signing assertions and creating SSL channels. These should be
621       issued by a commonly accepted CA, which may be stipulated by
622       your federation.  After understanding the CA's acceptible to your
623       federations, consult chapter <a href="#4.c.">4.c</a> for
624       information on certificate and key generation.</p>
625     </blockquote>
626
627     <h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
628
629     <blockquote>
630       <p>The Attribute Authority maintains a set of rules called
631       Attribute Release Policies (ARP's) that define which
632       attributes are released to which targets. When a browser user
633       tries to access a resource, the SHAR asks the origin site AA
634       to release all the attributes it is allowed to know. The SHAR
635       provides its own name and an optional URL on behalf of which
636       the attribute request is made which can further refine the
637       information the SHAR is allowed to know. The AA processes this
638       request using all applicable ARP's, determines which
639       attributes and values it will release, and then obtains the
640       values actually associated with the browser user. The AA sends
641       these attributes and values back to the SHAR.</p>
642
643       <p>Targets should work together with expected origin sites to
644       ensure that the sets of attributes that both sites expect to
645       correspond using are congruent.</p>
646     </blockquote>
647
648     <h4><a name="2.f."></a>2.f. Designate Contacts</h4>
649
650     <blockquote>
651       <p>Since Shibboleth deals both with daily technical and
652       operational issues and also with contractual issues, a set of
653       contacts should be set up to support the user base and to
654       facilitate interactions with other Shibboleth sites and federation
655       members. It is recommended that at least technical and
656       administrative contacts be designated. Names, titles, e-mail
657       addresses, and phone numbers may all be useful information to
658       provide.</p>
659     </blockquote>
660
661     <h4><a name="2.g."></a>2.g. Browser Requirements</h4>
662
663     <blockquote>
664       <p>A primary Shibboleth design consideration was to require
665       very little or no modification to client machines. The only
666       requirement is that a browser is used which supports cookies,
667       redirection and SSL. Browser users will have to perform an
668       additional click to submit the authentication assertion if
669       JavaScript is not functional.</p>
670     </blockquote>
671
672     <h4><a name="2.h."></a>2.h. Clocks</h4>
673
674     <blockquote>
675       <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should
676       be run on all web servers. Shibboleth employs a short handle
677       issuance time to protect against replay attacks. Because of
678       this, any significant degree of clock skew can hinder the
679       ability of users to access sites successfully.</p>
680     </blockquote>
681
682     <h4><a name="2.h."></a>2.i. Other Considerations</h4>
683
684     <blockquote>
685       <p>Especially for higher education, there are a handful of
686       laws enacted which may have important ramifications on the
687       disclosure of personal information and attributes. Since
688       Shibboleth does not necessarily need to transmit identity, it
689       is an ideal solution for many higher education situations.
690       Nevertheless, all parties within the United States of America
691       are strongly advised to consult the <a href=
692       "http://www.ed.gov/offices/OM/fpco/ferpa/">Family Educational
693       Rights and Privacy Act of 1974(FERPA)</a>, and all other
694       relevant state and federal legislation before deploying
695       Shibboleth.</p>
696     </blockquote>
697     <br>
698     <br>
699     <hr>
700     <br>
701      
702
703     <h3><a name="3."></a>3. Installation</h3>
704
705     <h4><a name="3.a."></a>3.a. Software Requirements</h4>
706
707     <p>The Shibboleth project makes binary packages available for
708     Solaris and Linux that are precompiled against recent releases
709     of various required libraries such as OpenSSL. It is highly
710     advisable to build from source when using Shibboleth in a
711     production environment in order to permit patching or updating
712     of packages as security holes and bugs are fixed. Building from
713     source is necessary to give you complete control over your
714     deployment platform. The binary packages represent a snapshot in
715     time only. To build from source, see the <span class="fixedwidth">INSTALL.txt</span>
716     files in the root of the OpenSAML and Shibboleth source
717     distributions.</p>
718
719     <blockquote>
720       <b>Operating System:</b>
721
722       <ul type="circle">
723         <li>
724           RedHat 7.2-7.3:
725
726           <ul type="disc">
727             <li>
728               <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
729
730               <blockquote>
731                 <p>Apache must be compiled with mod_so for DSO
732                 module support, and must include SSL
733                 support (preferably using <span class="fixedwidth">mod_ssl</span>), and
734                 EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
735                 provides). Shibboleth can coexist with
736                 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
737                 into the server for use elsewhere, but Shibboleth
738                 does not need or use it.  The most recent Red Hat
739                 RPM (1.3.23-14 as of this writing) is sufficient.
740                 </p>
741               </blockquote>
742               
743               <blockquote>
744                 <p>On Linux, Shibboleth requires that Apache and
745                 Apache-SSL be built with <span
746                 class="fixedwidth">libpthread</span>, or loading the
747                 <span class="fixedwidth">mod_shibrm</span> or <span
748                 class="fixedwidth">mod_shire</span> modules will
749                 cause Apache to stop.  While RedHat's Apache is
750                 compatible, Debian's Apache must be rebuilt with
751                 <span class="fixedwidth">libpthread</span>:</p>
752                 <blockquote>
753                   <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
754                   $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
755                 </blockquote>
756               </blockquote>
757             </li>
758
759             <li><a href=
760             "http://shibboleth.internet2.edu/release/shib-download.html">
761             Shibboleth v1.0 Target for RedHat</a></li>
762
763             <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
764             revision <span class="fixedwidth">i</span> or newer</a></li>
765
766             <li>
767               libstdc++3-3.0.4-1.i386.rpm and
768               libgcc-3.0.4-1.i386.rpm
769
770               <blockquote>
771                 <p>Shibboleth binaries are currently built with <a href=
772                 "http://www.gnu.org/software/gcc/gcc.html">GCC
773                 3.04</a>, and require these specific library
774                 versions. They are available as RPMs and are
775                 available in the RedHat 7.2 updates directory on
776                 any <a href=
777                 "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
778                 RedHat mirror</a>. They can be installed alongside
779                 earlier and later GCC libraries.</p>
780               </blockquote>
781             </li>
782
783             <li><b>Portions of the <span
784             class="fixedwidth">libphp4</span> Apache plugin are written
785             in C++, as is Shibboleth.  There is a known conflict between
786             the PHP extensions <span
787             class="fixedwidth">libpspell.so</span> and <span
788             class="fixedwidth">libsablot.so</span> which will manifest
789             itself as segmentation faults when starting Apache.  If a
790             site wants to use <span class="fixedwidth">libphp4.so</span>
791             and Shibboleth at once, then one of the following may be
792             done:</b>
793               <ol>
794                 <li>
795                 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
796                 </li>
797                 <li>
798                 Rebuild these two modules using
799                 the same version of GCC that was used to compile Shibboleth.
800                 </li>
801               </ol>
802             </li>
803           </ul>
804         </li>
805         <br>
806         <li>
807           Solaris 2.8:
808
809           <ul type="disc">
810             <li><a href=
811             "ftp://ftp.openssl.org/source/openssl-0.9.7a.tar.gz">
812             openssl-0.9.7a</a>
813
814               <blockquote>
815                 <p>The shared library version of OpenSSL is required
816                 by Shibboleth.  The static libraries may be installed as
817                 well if necessary for other applications, but cannot be
818                 used within mod_ssl or any other Apache modules.</p>
819               </blockquote>
820             </li>
821
822             <li>
823               <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
824
825               <blockquote>
826                 <p>Apache must be compiled with mod_so for DSO
827                 module support, and must include SSL
828                 support (preferably using <span class="fixedwidth">mod_ssl</span>) and EAPI
829                 support (which <span class="fixedwidth">mod_ssl</span> requires and
830                 provides). Shibboleth can coexist with
831                 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
832                 into the server for use elsewhere, but Shibboleth
833                 does not need or use it.</p>
834                 
835                 <p><span class="fixedwidth">mod_ssl</span>'s
836                 loadable module, <span class="fixedwidth">libssl.so</span>, must be
837                 compiled against <span class="fixedwidth">OpenSSL
838                 0.9.7a</span>'s shared libraries.  Other versions or
839                 a statically linked build of <span
840                 class="fixedwidth">libssl.so</span> will cause
841                 failures such as bus errors when used with
842                 Shibboleth.</p>
843
844                 <p>To check how OpenSSL was built, run the <span
845                 class="fixedwidth">ldd</span> command against <span
846                 class="fixedwidth">libssl.so</span> in the Apache
847                 <span class="fixedwidth">/libexec/</span> folder and
848                 check the output for references to <span
849                 class="fixedwidth">libssl.so.0.9.7a</span>. If you
850                 see an earlier version mentioned, or no mention of
851                 it at all, then <span class="fixedwidth">OpenSSL
852                 0.9.7a</span> must be rebuilt with shared libraries
853                 from source.</p>
854               </blockquote>
855             </li>
856
857             <li><a href=
858             "ftp://ftp.sunfreeware.com/pub/freeware/sparc/8/libgcc-3.2.2-sol8-sparc-local.gz">
859             libgcc v3.2.2+ and libstdc++ v3.2.2+</a></li>
860
861             <li><a href=
862             "http://shibboleth.internet2.edu/release/shib-download.html">
863             Shibboleth v1.0 Target for Solaris</a></li>
864
865             <li><b>Portions of the <span
866             class="fixedwidth">libphp4</span> Apache plugin are written
867             in C++, as is Shibboleth.  There is a known conflict with
868             the PHP extensions <span
869             class="fixedwidth">libpspell.so</span> and <span
870             class="fixedwidth">libsablot.so</span> which will manifest
871             itself as segmentation faults when starting Apache.  If a
872             site wants to use <span class="fixedwidth">libphp4.so</span>
873             and Shibboleth at once, then one of the following may be
874             done:</b>
875               <ol>
876                 <li>
877                 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
878                 </li>
879                 <li>
880                 Rebuild these two modules using the same version of GCC
881                 that was used to compile Shibboleth.
882                 </li>
883               </ol>
884             </li>
885           </ul>
886         </li>
887         <br>
888         <li>
889           RedHat 8:
890            <blockquote>
891             <p>RedHat 8 ships with Apache 2, which is not supported by
892             Shibboleth.  To run Shibboleth under this OS, <a
893             href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
894             must be installed.</p>
895           </blockquote>
896               <blockquote>
897                 <p>Apache must be compiled with mod_so for DSO
898                 module support, and must include SSL
899                 support (preferably using <span class="fixedwidth">mod_ssl</span>), and
900                 EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
901                 provides). Shibboleth can coexist with
902                 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
903                 into the server for use elsewhere, but Shibboleth
904                 does not need or use it.  The most recent Red Hat
905                 RPM (1.3.23-14 as of this writing) is sufficient.
906                 </p>
907               </blockquote>
908               
909               <blockquote>
910                 <p>On Linux, Shibboleth requires that Apache and
911                 Apache-SSL be built with <span
912                 class="fixedwidth">libpthread</span>, or loading the
913                 <span class="fixedwidth">mod_shibrm</span> or <span
914                 class="fixedwidth">mod_shire</span> modules will
915                 cause Apache to stop.  While RedHat's Apache is
916                 compatible, Debian's Apache must be rebuilt with
917                 <span class="fixedwidth">libpthread</span>:</p>
918                 <blockquote>
919                   <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
920                   $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
921                 </blockquote>
922               </blockquote>
923
924          <ul type=disc>
925
926             <li><a href=
927             "http://shibboleth.internet2.edu/release/shib-download.html">
928             Shibboleth 1.0 Target for RedHat</a></li>
929
930             <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
931             revision <span class="fixedwidth">i</span> or newer</a></li>
932
933             <li>
934               libstdc++3-3.0.4-1.i386.rpm and
935               libgcc-3.0.4-1.i386.rpm
936
937               <blockquote>
938                 <p>Shibboleth binaries are currently built with <a href=
939                 "http://www.gnu.org/software/gcc/gcc.html">GCC
940                 3.04</a>, and require these specific library
941                 versions. They are available as RPMs and are
942                 available in the RedHat 7.2 updates directory on
943                 any <a href=
944                 "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
945                 RedHat mirror</a>. They can be installed alongside
946                 earlier and later GCC libraries.</p>
947               </blockquote>
948             </li>
949
950             <li><b>Portions of the <span
951             class="fixedwidth">libphp4</span> Apache plugin are written
952             in C++, as is Shibboleth.  There is a known conflict with
953             the PHP extensions <span
954             class="fixedwidth">libpspell.so</span> and <span
955             class="fixedwidth">libsablot.so</span> which will manifest
956             itself as segmentation faults when starting Apache.  If a
957             site wants to use <span class="fixedwidth">libphp4.so</span>
958             and Shibboleth at once, then one of the following may be
959             done:</b>
960               <ol>
961                 <li>
962                 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
963                 </li>
964                 <li>
965                 Rebuild these two modules using
966             the same version of GCC that was used to compile Shibboleth.
967                 </li>
968               </ol>
969             </li>
970           </ul>
971         </li>
972       </ul>
973     </blockquote>
974
975     <h4><a name="3.b."></a>3.b. Deploy the Shibboleth Package</h4>
976
977     <blockquote>
978       <p>For the sake of clarity, this deployment guide assumes
979       that standard directories are used for all installations.
980       These directories may be changed for local implementations,
981       but must be done so consistently.</p>
982
983       <ol type="1">
984         <li>
985           <p>Ensure that you have obtained the proper <a href=
986           "http://shibboleth.internet2.edu/release/shib-download.html">
987           tarball</a> for your operating system.</p>
988         </li>
989
990         <li>
991           <p>The tarballs expand into <span class="fixedwidth">/opt/shibboleth</span>,
992           and should be expanded as <span class="fixedwidth">root</span> from <span class="fixedwidth">/</span>. 
993           You should see the following directory structure:</p>
994
995           <blockquote>
996             <span class="fixedwidth">$ ls -al<br>
997              drwxr-xr-x 10 root root 4096 Oct 24 03:54 .<br>
998             drwxr-xr-x 3 root root 4096 Oct 24 00:37 ..<br>
999             drwxr-xr-x 2 root root 4096 Oct 24 03:54 bin<br>
1000             drwxr-xr-x 2 root root 4096 Oct 24 03:54 doc<br>
1001             drwxr-xr-x 4 root root 4096 Oct 24 03:54 etc<br>
1002             drwxr-xr-x 13 root root 4096 Oct 24 03:54 include<br>
1003             drwxr-xr-x 4 root root 4096 Oct 24 03:55 lib<br>
1004             drwxr-xr-x 2 root root 4096 Oct 24 03:55 libexec<br>
1005             drwxr-xr-x 4 root root 4096 Oct 24 02:02 share<br>
1006             </span>
1007           </blockquote>
1008         </li>
1009       </ol>
1010     </blockquote>
1011
1012     <h4><a name="3.c."></a>3.c. Configure Apache</h4>
1013
1014     <blockquote>
1015       <ol type="1">
1016         <li>
1017           <p>Shibboleth includes configuration directives in the
1018           file <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/apache.config</span>
1019           which must be added to the httpd.conf file used locally.
1020           It is recommended that these directives simply be added
1021           to the end of the existing <span class="fixedwidth">httpd.conf</span> file
1022           rather than trying to merge it in-line;
1023           <a href="#3.c.2.">step 2</a> describes the necessary
1024           modifications to the Apache startup script. The default
1025           configuration will often work, but if customization is
1026           necessary, these options may be modified:</p>
1027
1028           <dl>
1029             
1030               <dd class="attribute">
1031                   <span class="fixedwidth">LoadModule &lt;module&gt;
1032                   &lt;pathname&gt;</span>
1033               </dd>
1034
1035               <dd class="value">
1036                   <p>Specifies the title and location of the
1037                   <span class="fixedwidth">shibrm_module</span> resource manager and
1038                   <span class="fixedwidth">shire_module</span> SHIRE modules. These are
1039                   installed by default at
1040                   <span class="fixedwidth">/opt/shibboleth/libexec/mod_shibrm.so</span>
1041                   and
1042                   <span class="fixedwidth">/opt/shibboleth/libexec/mod_shire.so</span></p>
1043               </dd>
1044
1045               <dd class="attribute">
1046                   <span class="fixedwidth">SHIREConfig &lt;pathname&gt;</span>
1047               </dd>
1048
1049               <dd class="value">
1050                   <p>Specifies the <span class="fixedwidth">pathname</span> of the SHIRE's
1051                   configuration file. Defaults to
1052                   <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span>.</p>
1053               </dd>
1054
1055               <dd class="attribute"><span class="fixedwidth">SHIREURL &lt;url&gt;<br>
1056               &lt;Location &lt;url&gt;&gt;<br>
1057               &nbsp;&nbsp;SetHandler &lt;method&gt;<br>
1058               &lt;/Location&gt;</span></dd>
1059
1060               <dd class="value">
1061                   <p>Specifies the <span class="fixedwidth">URL</span> and the
1062                   <span class="fixedwidth">method</span> the target uses to handle
1063                   requests for Shibboleth-protected resources.
1064                   Currently, <span class="fixedwidth">shib-shire-post</span> is the only
1065                   available handler <span class="fixedwidth">method</span>.
1066                   <span class="fixedwidth">SHIREURL</span> is used by Shibboleth when
1067                   re-directing the user to the WAYF and
1068                   <span class="fixedwidth">&lt;Location&gt;</span> by Apache; for this
1069                   reason, both <span class="fixedwidth">URL</span> specifications must
1070                   match. Note that the configuration file itself
1071                   contains &lt;&gt;'s, and <span class="fixedwidth">Location</span> should
1072                   not be replaced.</p>
1073
1074                   <p>The referenced <span class="fixedwidth">URL</span> can be either a
1075                   partial path or an absolute URL. The partial path
1076                   allows each virtual server to use its own
1077                   hostname and port in the SHIRE for session cookie
1078                   purposes, while the absolute URL forces HTTP
1079                   virtual servers to use HTTPS for the SHIRE. Use
1080                   of a full <span class="fixedwidth">https://</span> URL is advised.</p>
1081               </dd>
1082
1083               <dd class="attribute">
1084                   <span class="fixedwidth">ShibMapAttribute &lt;attribute-uri&gt;
1085                   &lt;HTTP-header&gt; [alias]</span>
1086               </dd>
1087
1088               <dd class="value">
1089                   <p>Registers attributes to be recognized and maps
1090                   them to an authorization <span class="fixedwidth">alias</span> for use
1091                   in <span class="fixedwidth">.htaccess</span> files or Location Blocks
1092                   with <span class="fixedwidth">require</span> directives.
1093                   <span class="fixedwidth">REMOTE_USER</span> is a special case, suggested
1094                   for use with <span class="fixedwidth">eduPersonPrincipalName</span>, and
1095                   is automatically checked by a <span class="fixedwidth">require
1096                   user</span> rule.</p>
1097               </dd>
1098           </dl>
1099           
1100         </li>
1101
1102         <li>
1103           <a name="3.c.2."></a>
1104
1105           <p>These modifications must be made to the Apache startup
1106           script:</p>
1107
1108           <p>Add the following environment variables:</p>
1109
1110           <blockquote>
1111             <span class="fixedwidth">
1112             SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.ini;
1113             export SHIBCONFIG</span>
1114           </blockquote>
1115           
1116           <p>If the OpenSSL libraries are not in the system's search
1117           path, they should be added to <span class="fixedwidth">LD_LIBRARY_PATH</span> as
1118           well.</p>
1119
1120           <p>If the SHIBCONFIG environment variable is not
1121           specified, Shibboleth will use
1122           <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span> by
1123           default.</p>
1124         </li>
1125
1126         <li>
1127           <p>The SHAR must be started before Apache. Among other
1128           methods, this can be done either by creating a separate
1129           SHAR startup script or by modifying Apache's RC script to
1130           start/stop the <span class="fixedwidth">SHAR</span> <b>before</b>
1131           <span class="fixedwidth">httpd</span>. It is suggested that Apache's script be
1132           modified by adding:</p>
1133
1134           <blockquote>
1135             <span class="fixedwidth">/opt/shibboleth/bin/shar -f &amp;</span>
1136           </blockquote>
1137
1138           <p>Sample <span class="fixedwidth">init.d</span> scripts may be included with
1139           future releases. Ensure that the environment variables
1140           referenced in <a href="#3.c.2">3.c.2</a> are in
1141           place.</p>
1142           
1143         </li>
1144
1145         <li>
1146           <p>The options in <span class="fixedwidth">shibboleth.ini</span> must be
1147           configured as documented in <a href="#4.a.">4.a</a>.
1148           Apache content will then need to be modified for
1149           Shibboleth authentication. This is discussed in <a href=
1150           "#4.d.">4.d</a>. It is recommended that the target then
1151           be tested as detailed in section <a href=
1152           "#5.a.">5.a</a>.</p>
1153         </li>
1154       </ol>
1155     </blockquote>
1156     <br>
1157     <hr>
1158     <br>
1159      
1160
1161     <h3><a name="4."></a>4. Getting Running</h3>
1162
1163     <h4><a name="4.a."></a>4.a. Configuring
1164     <span class="fixedwidth">shibboleth.ini</span></h4>
1165
1166     <blockquote>
1167       <p>Most of the configuration for the SHAR, SHIRE, and RM is stored
1168       in the file <span class="fixedwidth">shibboleth.ini</span>. This
1169       file is split into several pre-defined sections. The first
1170       sections, <span class="fixedwidth">general</span>, <span
1171       class="fixedwidth">shire</span>, and <span
1172       class="fixedwidth">shar</span>, define the operational parameters
1173       for the <span class="fixedwidth">SHIRE</span> and <span
1174       class="fixedwidth">SHAR</span>. The <span
1175       class="fixedwidth">general</span> section holds global tags, used
1176       by all pieces. The <span class="fixedwidth">shire</span> and <span
1177       class="fixedwidth">shar</span> sections can override the <span
1178       class="fixedwidth">general</span> tags with SHIRE- or
1179       SHAR-specific configuration. For example, if the SHAR is looking
1180       for a tag, it will look first in the <span
1181       class="fixedwidth">shar</span> section; if it does not find the
1182       tag there, it will proceed to look in the <span
1183       class="fixedwidth">general</span> section. The following
1184       sections, <span class="fixedwidth">metadata_shire</span>, <span
1185       class="fixedwidth">metadata_shar</span>, <span
1186       class="fixedwidth">attributes</span>, and <span
1187       class="fixedwidth">policies</span>, define the trust framework
1188       within the SHIRE and SHAR operate.  Example configuration files
1189       are bundled with the Shibboleth distribution.</p>
1190
1191       <p>There is also information that must be configured in
1192       <span class="fixedwidth">/usr/local/apache/conf/httpd.conf</span>; for more
1193       information, refer to <a href="#3.c.2.">3.c</a>.</p>
1194
1195       <p>Information in the logger files referenced by
1196       <span class="fixedwidth">shibboleth.ini</span> may require additional configuration.
1197       It is recommended that after initial installation is
1198       completed, the log level in both files be changed to either
1199       <span class="fixedwidth">INFO</span> or <span class="fixedwidth">WARN</span>.</p>
1200       
1201       <p>Fields that are purple are optional; grey fields are
1202       mandatory.</p>
1203       
1204       <p><span class="fixedwidth">[general]</span>:</p>
1205
1206       <dl>
1207           <dd class="attribute">
1208               <span class="fixedwidth">logger = &lt;pathname&gt;</span>
1209           </dd>
1210
1211           <dd class="value">
1212               <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
1213               configuration file for most Shibboleth events. This
1214               element may also be optionally specified for each of
1215               the components individually. Default logging settings (using local log files)
1216               should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
1217               daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1218               <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
1219               to <span class="fixedwidth">enable logging from remote machines.</span> The
1220               logging level is also defined in the logger configuration.
1221               The configuration format and log levels are similar to that of the
1222               <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
1223               property format.</p>
1224           </dd>
1225
1226           <dd class="attribute">
1227               <span class="fixedwidth">schemadir = &lt;pathname&gt;</span>
1228           </dd>
1229
1230           <dd class="value">
1231               <p>Specifies the directory in which the XML schema
1232               files are located; defaults to
1233               <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>.</p>
1234           </dd>
1235
1236           <dd class="attribute">
1237               <span class="fixedwidth">sharsocket = &lt;pathname&gt;</span>
1238           </dd>
1239
1240           <dd class="value">
1241               <p>Specifies the location of the socket the SHAR uses to
1242               form connections. Note that if you change this, the SHAR and Apache
1243               should both be restarted immediately, since new Apache child processes will
1244               use the changed value as soon as they start up.</p>
1245           </dd>
1246       </dl>
1247
1248       <p>The next segment of the <span class="fixedwidth">[general]</span> configuration
1249       section defines server-specific tags in sections defined by
1250       the server name for use by the SHIRE and RM. For example, if
1251       you have a web server at www.example.edu, you can define a
1252       section <span class="fixedwidth">[www.example.edu]</span> and override global tags
1253       with tags for that server only.</p>
1254
1255       <p>The following table lists the server-specific tags. It is
1256       broken into mandatory tags, and optional tags. Tags in the <span
1257       class="fixedwidth">[general]</span> section correspond to all
1258       servers; to override specific tags on a per-server basis, use
1259       <span class="fixedwidth">[&lt;FQDN&gt;]</span> as the header for a
1260       section.</p>
1261
1262       <span class="fixedwidth">[&lt;general&gt;]</span>: 
1263
1264       <dl>
1265
1266           <dd class="attributeopt">
1267               <span class="fixedwidth">normalizeRequest = &lt;true/false&gt;</span>
1268           </dd>
1269
1270           <dd class="valueopt">
1271               <p>If true, all redirects generated by
1272               <span class="fixedwidth">mod_shire</span> will be created using the virtual
1273               server name assigned to the server containing this
1274               command. If <span class="fixedwidth">false</span>, the browser's supplied
1275               URL is used to compute the redirect back.</p>
1276           </dd>
1277
1278           <dd class="attributeopt">
1279               <span class="fixedwidth">checkIPAddress = &lt;true/false&gt;</span>
1280           </dd>
1281
1282           <dd class="valueopt">
1283               <p>If <span class="fixedwidth">true</span>, Shibboleth will check client
1284               addresses for impersonation protection. In most
1285               circumstances, this should be enabled to prevent
1286               certain attacks concerning stolen cookies. Defaults
1287               to <span class="fixedwidth">false</span>.</p>
1288           </dd>
1289
1290           <dd class="attributeopt">
1291               <span class="fixedwidth">supportContact = &lt;e-mail&gt;</span>
1292           </dd>
1293
1294           <dd class="valueopt">
1295               <p>Specifies the e-mail address used in the
1296               generation of error pages.</p>
1297           </dd>
1298
1299           <dd class="attributeopt">
1300               <span class="fixedwidth">logoLocation = &lt;pathname&gt;</span>
1301           </dd>
1302
1303           <dd class="valueopt">
1304               <p>Specifies the location of the logo used in the
1305               generation of error pages. This logo can be in any
1306               format that the web browser will understand.</p>
1307           </dd>
1308
1309           <dd class="attribute">
1310               <span class="fixedwidth">wayfURL = &lt;url&gt;</span>
1311           </dd>
1312
1313           <dd class="value">
1314               <p>Specifies the URL of the WAYF service the user is
1315               redirected to. Federations will generally provide this URL
1316               or provide information on how to locally host WAYF's with
1317               a distributed hosts file.</p>
1318           </dd>
1319
1320           <dd class="attribute">
1321               <span class="fixedwidth">cookieName = &lt;string&gt;</span>
1322           </dd>
1323
1324           <dd class="value">
1325               <p>Defines the name to be used for session cookies.</p>
1326           </dd>
1327
1328           <dd class="attribute">
1329               <span class="fixedwidth">shireSSLOnly = &lt;true/false&gt;</span>
1330           </dd>
1331
1332           <dd class="value">
1333               <p>If <span class="fixedwidth">true</span>, the SHIRE will reject HTTP
1334               connections that are not SSL-protected. This guards the initial session
1335               sign-on from the browser, but does not preclude non-SSL content. Use of
1336               SSL is strongly recommended; see section <a href=
1337               "#2.c.">2.c</a> for more information.</p>
1338           </dd>
1339
1340           <dd class="attribute">
1341               <span class="fixedwidth">shireError = &lt;pathname&gt;</span>
1342           </dd>
1343
1344           <dd class="value">
1345               <p>Specifies the location of the template for the
1346               error page generated when there is an error
1347               re-directing the user to the WAYF or processing a
1348               SHIRE POST.</p>
1349           </dd>
1350
1351           <dd class="attribute">
1352               <span class="fixedwidth">rmError = &lt;pathname&gt;</span>
1353           </dd>
1354
1355           <dd class="value">
1356               <p>Specifies the location of the template for the
1357               error page generated if internal errors occur in the
1358               RM.</p>
1359           </dd>
1360
1361           <dd class="attribute">
1362               <span class="fixedwidth">accessError = &lt;pathname&gt;</span>
1363           </dd>
1364
1365           <dd class="value">
1366               <p>Specifies the location of the template for the
1367               page displayed to users when access to a protected
1368               resource is denied by the RM.</p>
1369           </dd>
1370       </dl>
1371
1372       <span class="fixedwidth">[shire]</span>: 
1373
1374       <dl>
1375           <dd class="attribute">
1376               <span class="fixedwidth">logger = &lt;pathname&gt;</span>
1377           </dd>
1378
1379           <dd class="value">
1380               <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
1381               configuration file for most Shibboleth events. This
1382               element may also be optionally specified for each of
1383               the components individually. Default logging settings (using local log files)
1384               should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
1385               daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1386               <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
1387               to <span class="fixedwidth">enable logging from remote machines.</span> The
1388               logging level is also defined in the logger configuration.
1389               The configuration format and log levels are similar to that of the
1390               <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
1391               property format.</p>
1392           </dd>
1393
1394           <dd class="attributeopt">
1395               <span class="fixedwidth">aap-uri = &lt;uri&gt;</span>
1396           </dd>
1397
1398           <dd class="valueopt">
1399               <p>Specifies the URI of an attribute acceptance policy XML
1400               file. Attributes must be listed in the <span
1401               class="fixedwidth">aap-uri</span> file if they are to be
1402               visible to the Apache server. Unlisted or rejected attributes are
1403               filtered out and hidden from the web server (but also see the
1404               <b>ShibExportAssertion</b> Apache command).
1405               For more information, refer to section <a href="#4.e.">4.e</a>.</p>
1406           </dd>
1407
1408           <dd class="attributeopt">
1409               <span class="fixedwidth">metadata = &lt;tag&gt;</span>
1410           </dd>
1411
1412           <dd class="valueopt">
1413               <p>Specifies the tag that defines the section of <span
1414               class="fixedwidth">shibboleth.ini</span> the SHIRE should
1415               use to acquire its metadata. The SHIRE does not need trust
1416               metadata, and so generally it will only need sites data to
1417               enforce attribute policies like scope limitations(e.g. MIT
1418               not asserting @brown.edu attributes.)</p>
1419           </dd>
1420       </dl>
1421
1422       <span class="fixedwidth">[shar]</span>: 
1423       <dl>
1424       
1425           <dd class="attribute">
1426               <span class="fixedwidth">logger = &lt;pathname&gt;</span>
1427           </dd>
1428
1429           <dd class="value">
1430               <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
1431               configuration file for most Shibboleth events. This
1432               element may also be optionally specified for each of
1433               the components individually. Default logging settings (using local log files)
1434               should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
1435               daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1436               <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
1437               to <span class="fixedwidth">enable logging from remote machines.</span> The
1438               logging level is also defined in the logger configuration.
1439               The configuration format and log levels are similar to that of the
1440               <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
1441               property format.</p>
1442           </dd>
1443
1444           <dd class="attributeopt">
1445               <span class="fixedwidth">metadata = &lt;tag&gt;</span>
1446           </dd>
1447
1448           <dd class="valueopt">
1449               <p>Specifies the tag that defines the section of <span
1450               class="fixedwidth">shibboleth.ini</span> the SHAR should
1451               use to acquire its site and trust metadata.</p>
1452           </dd>
1453
1454           <dd class="attributeopt">
1455               <span class="fixedwidth">certFile = &lt;pathname&gt;</span>
1456           </dd>
1457
1458           <dd class="valueopt">
1459               <p>Specifies the location of the PEM-format certificate used by
1460               the SHAR to communicate in authenticated fashion with
1461               origin site Attribute Authorities.</p>
1462           </dd>
1463
1464           <dd class="attributeopt">
1465               <span class="fixedwidth">keyFile = &lt;pathname&gt;</span>
1466           </dd>
1467
1468           <dd class="valueopt">
1469               <p>Specifies the location of the PEM-format private key used by
1470               the SHAR to communicate in authenticated fashion with
1471               origin site Attribute Authorities.</p>
1472           </dd>
1473
1474           <dd class="attributeopt">
1475               <span class="fixedwidth">keyPass = &lt;password&gt;</span>
1476           </dd>
1477
1478           <dd class="valueopt">
1479               <p>Specifies the <span class="fixedwidth">password</span> used to access the
1480               <span class="fixedwidth">keyFile</span>, if any.</p>
1481           </dd>
1482
1483           <dd class="attribute">
1484               <span class="fixedwidth">calist = &lt;pathname&gt;</span>
1485           </dd>
1486
1487           <dd class="value">
1488               <p>Specifies a single file of PEM-format certificates containing
1489               the root CAs the SHAR will consider to be valid signers of AA server
1490               certificates. Currently applies globally to all communication with AAs.</p>
1491           </dd>
1492
1493           <dd class="attribute">
1494               <span class="fixedwidth">AATimeout = &lt;seconds&gt;</span>
1495           </dd>
1496
1497           <dd class="value">
1498               <p>Specifies the number of seconds that the SHAR will wait
1499               for attributes to be sent from an AA. Defaults to <span
1500               class="fixedwidth">60</span>.</p>
1501           </dd>
1502
1503           <dd class="attribute">
1504               <span class="fixedwidth">AAConnectTimeout = &lt;seconds&gt;</span>
1505           </dd>
1506
1507           <dd class="value">
1508               <p>Specifies the number of seconds that the SHAR will wait
1509               for a connection to be established with an AA. 
1510               Defaults to <span class="fixedwidth">30</span>.</p>
1511           </dd>
1512
1513           <dd class="attribute">
1514               <span class="fixedwidth">cacheType = &lt;method&gt;</span>
1515           </dd>
1516
1517           <dd class="value">
1518               <p>Specifies the method used by the SHAR to cache received
1519               attributes.  The default is <span
1520               class="fixedwidth">memory</span>, which indicates that
1521               the SHAR should store received attributes in its memory. 
1522               Another option is <span class="fixedwidth">mysql</span>,
1523               which will use the MySQL Credential Cache. The steps to using this are described
1524               in the MySQL Credential Cache guide.</p>
1525           </dd>
1526
1527           <dd class="attribute">
1528               <span class="fixedwidth">cacheClean = &lt;seconds&gt;</span>
1529           </dd>
1530
1531           <dd class="value">
1532               <p>Specifies the duration in seconds between cleanups of
1533               the SHAR's cached but expired attributes. Defaults to <span
1534               class="fixedwidth">300</span>, or 5 minutes.</p>
1535           </dd>
1536
1537           <dd class="attribute">
1538               <span class="fixedwidth">cacheTimeout = &lt;seconds&gt;</span>
1539           </dd>
1540
1541           <dd class="value">
1542               <p>Specifies the duration in <span
1543               class="fixedwidth">seconds</span> that must elapse
1544               between user accesses before that user's session is
1545               destroyed, including the associated handle and all
1546               cached attributes.  Defaults to <span
1547               class="fixedwidth">28800</span> seconds, or 8 hours.</p>
1548           </dd>
1549       </dl>
1550
1551       <p><span class="fixedwidth">[metadata]</span> sections must be
1552       created and named in accordance with the value of the <span
1553       class="fixedwidth">metadata</span> parameter in the <span
1554       class="fixedwidth">[shire]</span> and <span
1555       class="fixedwidth">[shar]</span> sections.  Metadata sections may
1556       be shared or defined for each component. Two providers are
1557       supported by Shibboleth, but additional providers may be
1558       specified with name/value pairs consisting of <span
1559       class="fixedwidth">&lt;metadata provider type&gt;=&lt;source&gt;</span>.</p>
1560
1561       <p><span class="fixedwidth">[&lt;metadata&gt;]</span>:</p>
1562
1563       <dl>
1564           <dd class="attributelong">
1565               <span class="fixedwidth">edu.internet2.middleware.shibboleth.metadata.XML = &lt;pathname&gt;</span>
1566           </dd>
1567
1568           <dd class="value">
1569               <p>Specifies the location of the file to load site
1570               metadata from.  This will often be a <span
1571               class="fixedwidth">sites.xml</span> file stored locally,
1572               and may be used by both the SHIRE and SHAR.</p>
1573               
1574               <p>Shibboleth provides a simple utility called <span
1575               class="fixedwidth">siterefresh</span> for updating the
1576               metadata file as described in section <a
1577               href="#4.g.">4.g</a>.</p>
1578           </dd>
1579
1580           <dd class="attributelong">
1581               <span class="fixedwidth">edu.internet2.middleware.shibboleth.trust.XML = &lt;pathname&gt;</span>
1582           </dd>
1583
1584           <dd class="value">
1585               <p>Specifies the location of the trust database of
1586               certificates and/or CA roots used by the SHAR during
1587               session initiation. The SHIRE module generally does not need trust
1588               data.</p>
1589           </dd>
1590       </dl>
1591
1592       <p>In order for an attribute to be used by Shibboleth, it must be
1593       recognized as valid by the SHAR and implemented with any specific
1594       rules for how to understand and express its value based on the XML
1595       from the AA. Additional string-valued attributes may be added to
1596       the SHAR using the <span class="fixedwidth">[attributes]</span>
1597       section.</p>
1598
1599       <p><span class="fixedwidth">[attributes]</span>:</p>
1600
1601       <dl>
1602           <dd class="attribute">
1603               <span class="fixedwidth">&lt;attribute_URI&gt;=&lt;type&gt;</span>
1604           </dd>
1605
1606           <dd class="value">
1607               <p>Attribute names are URI's that are assigned by the
1608               parties standardizing the attribute.  Frequently, a
1609               federation or standard object class may define these URI's. 
1610               The attribute type may be either <span
1611               class="fixedwidth">scoped</span> or <span
1612               class="fixedwidth">simple</span>, which defines how
1613               the attribute is processed as described in section <a
1614               href="#4.e.">4.e</a>.</p>
1615           </dd>
1616       </dl>
1617
1618       <p>The <span class="fixedwidth">[policies]</span> section contains the policy URI
1619       values that control acceptance of assertions from origin
1620       sites.  This may eventually have multiple elements associated
1621       it for targets that are members of multiple federations.</p>
1622       
1623       <p><span class="fixedwidth">[policies]</span>:</p>
1624
1625       <dl>
1626           <dd class="attribute">
1627               <span class="fixedwidth">&lt;federation&gt; = &lt;URI&gt;</span>
1628           </dd>
1629
1630           <dd class="value">
1631               <p>The name of the <span
1632               class="fixedwidth">federation</span> and its
1633               associated policy <span class="fixedwidth">URI</span>.
1634               These URI's will be provided by federations.</p>
1635               
1636               <p>This set of URI values is matched against the SAML
1637               <span class="fixedwidth">Audience</span> fields of
1638               assertions received from HS's and AA's.  One of the
1639               URI's specified by the origin in <span
1640               class="fixedwidth">edu.internet2.middleware.shibboleth.audiences</span>
1641               must match one of these URIs or the
1642               assertion will not be accepted by design.</p>
1643           </dd>
1644       </dl>
1645
1646       <p>Additional sections for individual servers may be defined with
1647       either parameters overriding those found in <span
1648       class="fixedwidth">[general]</span>, or the following additional
1649       parameters:</p>
1650
1651       <p><span class="fixedwidth">[&lt;FQDN&gt;]</span>:</p>
1652
1653       <dl>
1654           <dd class="attributeopt">
1655               <span class="fixedwidth">requestAttributes = &lt;attr1&gt; &lt;attr2&gt;
1656               &lt;attr3&gt;...</span>
1657           </dd>
1658
1659           <dd class="valueopt">
1660               <p>Specifies a space-delimited list of attributes named by
1661               URI that the SHAR will request of an AA.  If the parameter
1662               does not exist or is null, then the SHAR will receive all
1663               attributes the AA is willing to release to it.</p>
1664           </dd>
1665       </dl>
1666
1667     </blockquote>
1668
1669     <h4><a name="4.b."></a>4.b. Dynamic Error Page Generation</h4>
1670
1671     <blockquote>
1672       <p>Shibboleth supports the dynamic generation of information
1673       in error pages referenced by <span class="fixedwidth">shibboleth.ini</span>. The
1674       Shib Target employs a special Markup Language Processor to
1675       insert special tags into the generated HTML. The parser will
1676       read the error file looking for any tag that looks like:</p>
1677
1678       <blockquote>
1679         <span class="fixedwidth">&lt;shibmlp tag-name /&gt;</span>
1680       </blockquote>
1681
1682       <p>Shibboleth will replace <span class="fixedwidth">tag-name</span> with the
1683       appropriate markup tag from the table below:</p>
1684
1685       <dl>
1686           <dd class="attribute"><span class="fixedwidth">supportContact</span></dd>
1687
1688           <dd class="value">The value of the <span class="fixedwidth">supportContact</span> for this
1689           server.</dd>
1690
1691           <dd class="attribute"><span class="fixedwidth">logoLocation</span></dd>
1692
1693           <dd class="value">The value of the <span
1694           class="fixedwidth">logoLocation</span> for this server.  This
1695           is used to fill in the template error page only; if a custom
1696           error page is created, then the image may be linked to
1697           statically by the page itself.</dd>
1698
1699           <dd class="attribute"><span class="fixedwidth">requestURL</span></dd>
1700
1701           <dd class="value">The user's requested URL.</dd>
1702
1703           <dd class="attribute"><span class="fixedwidth">errorType</span></dd>
1704
1705           <dd class="value">The type of error.</dd>
1706
1707           <dd class="attribute"><span class="fixedwidth">errorText</span></dd>
1708
1709           <dd class="value">The actual error message.</dd>
1710
1711           <dd class="attribute"><span class="fixedwidth">errorDesc</span></dd>
1712
1713           <dd class="value">A textual description of the error intended for human
1714           consumption.</dd>
1715           
1716           <dd class="attribute"><span class="fixedwidth">originContactName</span></dd>
1717
1718           <dd class="value">The contact name for the origin site provided by that
1719           site's metadata.</dd>
1720
1721           <dd class="attribute"><span class="fixedwidth">originContactEmail</span></dd>
1722
1723           <dd class="value">The contact email address for the origin site provided by that
1724           site's metadata.</dd>
1725
1726           <dd class="attribute"><span class="fixedwidth">originErrorURL</span></dd>
1727
1728           <dd class="value">The URL of an error handling page for the origin site
1729           provided by that site's metadata.</dd>
1730       </dl>
1731
1732       <p>This configuration is only for Apache servers, and is only
1733       used by resources protected by Shibboleth.  See section <a
1734       href= "#4.d.">4.d</a>.</p>
1735       
1736       <p>Sample error templates for different kinds of errors are
1737       included in the Shibboleth distribution, and can be triggered
1738       by anything that will cause Shibboleth to be unable to make an
1739       authorization decision, including a bad sites file, certificate chain,
1740       or skewed clock.</p>
1741       
1742       <p><b>You should edit these templates, provide or remove style sheets and
1743       images, and otherwise customize these templates to suit the user experience
1744       you want your users to have when errors occur.</b></p>
1745
1746     </blockquote>
1747
1748     <h4><a name="4.c."></a>4.c. Key Generation and Certificate
1749     Installation</h4>
1750
1751     <blockquote>
1752       <p>The only target component that must have a private key and
1753       certificate is the SHAR. While the target server itself should support
1754       SSL in most cases, it is mandatory for the SHAR to
1755       authenticate when contacting an AA, and it must therefore be
1756       given a key and an SSL client certificate. It is permissible
1757       for the SHAR to use the same keypair and certificate used by
1758       the target server itself, provided the certificate is signed
1759       by a CA accepted by the community of sites.</p>
1760       
1761       <p>The certificate and key should be placed based on whether
1762       they will also be used for Apache's server cert. If they will
1763       be used as a server certificate as well, they should probably
1764       be in the Apache tree in the usual <span class="fixedwidth">mod_ssl</span> spot, and
1765       the SHAR can read them from there. If the SHAR is not running
1766       as <span class="fixedwidth">root</span>, permissions might need to be changed to
1767       allow this access. If the certificate and key will only be
1768       used for the SHAR, they can be put in the same folder with the
1769       <span class="fixedwidth">shibboleth.ini</span> file.</p>
1770
1771       <p>The SHAR is assigned a key and a certificate using
1772       shibboleth.ini's <span class="fixedwidth">certFile</span>,
1773       <span class="fixedwidth">keyFile</span> and
1774       <span class="fixedwidth">keyPass</span>, described in <a href="#4.a.">4.a</a>. These
1775       files must currently be in PEM format. OpenSSL commands to
1776       generate a new keypair and a certificate request are shown
1777       here, assuming RSA keys are to be used:</p>
1778
1779       <blockquote>
1780         <span class="fixedwidth">$ openssl genrsa -des3 -out ssl.key 2048<br>
1781         $ openssl req -new -key ssl.key -out ssl.csr</span>
1782       </blockquote>
1783
1784       <p>The signed certificate file returned by the CA should be
1785       usable directly, or can be converted to PEM format using the
1786       <span class="fixedwidth">openssl x509</span> command.</p>
1787
1788       <p>The key and certificate files can be placed anywhere,
1789       though in or beneath the <span class="fixedwidth">/usr/local/apache/conf</span>
1790       directory is a good choice. The Apache child processes,
1791       often running as <span class="fixedwidth">nobody</span>, must be able to read them
1792       while the server is running, which may require permission
1793       changes.</p>
1794
1795       <p>This particularly applies when sharing the key and
1796       certificate used by mod_ssl, which are only readable by root
1797       by default. The password, if any, must be placed in the conf
1798       file, since the module cannot prompt for it as the initial
1799       startup of mod_ssl can. The issues surrounding how to
1800       securely obtain a key while running as <span class="fixedwidth">nobody</span>
1801       may be addressed in a later release. Since the password will be
1802       stored in clear text in a frequently examined file, it is
1803       suggested to use a password not used elsewhere.</p>
1804
1805       <p>Finally, the <span class="fixedwidth">calist</span> command provides the SHAR
1806       with a set of CA roots to trust when validating AA server
1807       certificates. In all cases, the SHAR verifies that the
1808       certificate's Subject CN equals the AA's hostname, but the CA root
1809       bundle restricts the accepted signers to those permitted by
1810       the SHAR. The parameter can be omitted to skip such validation.</p>
1811     </blockquote>
1812
1813     <h4><a name="4.d."></a>4.d. Protecting Webpages</h4>
1814
1815     <blockquote>
1816       <p>Protection of webpages is primarily achieved through
1817       "mapping" attributes provided by an AA to a localized
1818       vocabulary for authorization rules. Each attribute can be
1819       mapped using the <span class="fixedwidth">ShibMapAttribute</span> command to an HTTP
1820       header name where it can subsequently be accessed by
1821       applications, and optionally to an <span class="fixedwidth">alias</span> that can be
1822       used in a <span class="fixedwidth">Require</span> command to search for a matching
1823       value. This mapping command must be in <span class="fixedwidth">httpd.conf</span>,
1824       while the rest of the commands described here appear in
1825       content-specific configuration or <span class="fixedwidth">.htaccess</span>
1826       files.</p>
1827
1828       <p>Any of the typical ways of protecting content may be used
1829       (.htaccess, Directory, Location, Files, etc.). There are two
1830       ways to trigger Shibboleth authentication: specifying an
1831       <span class="fixedwidth">AuthType</span> of <span class="fixedwidth">shibboleth</span> to use Shibboleth
1832       directly, or specifying <span class="fixedwidth">ShibBasicHijack On</span> to
1833       process existing .htaccess files using Shibboleth instead.
1834       Support for authorization consists of mod_auth-style require
1835       directives, as well as support for mod_auth group files.</p>
1836
1837       <p>A complete list of the directives and their values is
1838       below:</p>
1839
1840       <dl>
1841           <dd class="attribute">
1842               <span class="fixedwidth">AuthType &lt;string&gt;</span>
1843           </dd>
1844
1845           <dd class="value">
1846               <p>Use <span class="fixedwidth">shibboleth</span> for direct invocation, or
1847               <span class="fixedwidth">Basic</span> plus the <span class="fixedwidth">ShibBasicHijack On</span>
1848               option described below.</p>
1849           </dd>
1850
1851           <dd class="attribute">
1852               <span class="fixedwidth">ShibSSLOnly&lt;on/off&gt;</span>
1853           </dd>
1854
1855           <dd class="value">
1856               <p>Controls whether Shibboleth will reject non-SSL
1857               requests from clients. Defaults to <span class="fixedwidth">off</span>.</p>
1858           </dd>
1859
1860           <dd class="attribute">
1861               <span class="fixedwidth">ShibBasicHijack &lt;on/off&gt;</span>
1862           </dd>
1863
1864           <dd class="value">
1865               <p>Controls whether Shibboleth should or should not
1866               ignore requests for <span class="fixedwidth">AuthType Basic</span>. Defaults
1867               to <span class="fixedwidth">off</span>.</p>
1868           </dd>
1869
1870           <dd class="attribute">
1871               <span class="fixedwidth">ShibExportAssertion &lt;on/off&gt;</span>
1872           </dd>
1873
1874           <dd class="value">
1875               <p>Controls whether the SAML attribute assertion
1876               provided by the AA is exported in a base64-encoded
1877               HTTP header, <span class="fixedwidth">Shib-Attributes</span>. Defaults to
1878               <span class="fixedwidth">off</span>. While this does require parsing the
1879               raw XML, it also permits an application to see attributes that may have
1880               been filtered by an AAP, or to forward the SAML assertion to a third party.</p>
1881           </dd>
1882
1883           <dd class="attribute">
1884               <span class="fixedwidth">ShibAuthLifetime &lt;seconds&gt;</span>
1885           </dd>
1886
1887           <dd class="value">
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>
1891           </dd>
1892
1893           <dd class="attribute">
1894               <span class="fixedwidth">ShibAuthTimeout &lt;seconds&gt;</span>
1895           </dd>
1896
1897           <dd class="value">
1898               <p>Sets the maximum number of seconds without any
1899               user activity that a session will remain alive. After
1900               <span class="fixedwidth">seconds</span> seconds without activity, the
1901               session is considered dead. Omission or <span class="fixedwidth">0</span>
1902               results in an arbitrary session timeout.</p>
1903           </dd>
1904
1905           <dd class="attribute">
1906               <span class="fixedwidth">AuthGroupFile &lt;pathname&gt;</span>
1907           </dd>
1908
1909           <dd class="value">
1910               <p>Same as mod_auth; collects EPPN's into a named
1911               group for access control. Note that mod_auth will not
1912               support group files when mod_shibrm is loaded, since
1913               they share the same command.</p>
1914             
1915
1916             <blockquote>
1917               <p><a href=
1918               "http://httpd.apache.org/docs/mod/core.html#require">This
1919               is implemented</a> by placing a <span class="fixedwidth">.htaccess</span>
1920               file that references an <span class="fixedwidth">AuthGroupFile</span> stored
1921               at <span class="fixedwidth">/path</span>:</p>
1922
1923               <blockquote>
1924                 <span class="fixedwidth">authgroupfile /path<br>
1925                 require group workgroup</span>
1926               </blockquote>
1927
1928               <p>Note that an <a href=
1929               "http://httpd.apache.org/docs/mod/mod_auth.html#authgroupfile">
1930               AuthGroupFile</a> used by Shibboleth would resemble
1931               <span class="fixedwidth">workgroup: joe@example.edu, jane@demo.edu,
1932               jim@sample.edu</span>.</p>
1933             </blockquote>
1934           </dd>
1935
1936           <dd class="attribute">
1937               <span class="fixedwidth">Require &lt;string&gt;</span>
1938           </dd>
1939
1940           <dd class="value">
1941             <p>Enforce authorization using one of the following methods.</p>
1942
1943             <ul type="circle">
1944
1945               <li>
1946                 <span class="fixedwidth">valid-user</span>
1947
1948                 <blockquote>
1949                   <p>Any Shibboleth user from a trusted origin site is accepted,
1950                   even if no actual attributes are received. This is a very minimal
1951                   kind of policy, but is useful for testing or for deferring real
1952                   policy to an application.</p>
1953                 </blockquote>
1954               </li>
1955
1956                 <span class="fixedwidth">user</span>
1957
1958                 <blockquote>
1959                   <p>A space-delimited list of EPPN values, provided that the
1960                   <span class="fixedwidth">urn:mace:dir:attribute-def:eduPersonPrincipalName</span>
1961                   attribute has been mapped to the
1962                   <span class="fixedwidth">REMOTE_USER</span> header (as per the earlier
1963                   example configuration commands). Actually, any attribute can be mapped to
1964                   REMOTE_USER, even if this doesn't always make sense.</p>
1965                 </blockquote>
1966               </li>
1967
1968               <li>
1969                 <span class="fixedwidth">group</span>
1970
1971                 <blockquote>
1972                   <p>A space-delimited list of group names defined
1973                   within <span class="fixedwidth">AuthGroupFile</span> files, again
1974                   provided that a mapping to <span class="fixedwidth">REMOTE_USER</span>
1975                   exists.</p>
1976                 </blockquote>
1977               </li>
1978
1979               <li>
1980                 <span class="fixedwidth">&lt;alias&gt;</span>
1981
1982                 <blockquote>
1983                   <p>An arbitrary rule tag that matches an alias
1984                   defined in a <span class="fixedwidth">ShibMapAttribute</span> server
1985                   command. The rule value is a space-delimited
1986                   list of attribute values, whose format depends on
1987                   the attribute in question (e.g. an affiliation
1988                   rule might look like <span class="fixedwidth">require affiliation
1989                   staff@osu.edu faculty@mit.edu</span>).</p>
1990                 </blockquote>
1991               </li>
1992             </ul>
1993             
1994             <p>Additionally, for <span class="fixedwidth">user</span> and
1995             <span class="fixedwidth">&lt;alias&gt;</span>-based rules, if a tilde character
1996             is placed immediately following <span class="fixedwidth">user</span> or
1997             <span class="fixedwidth">&lt;alias&gt;</span>, the expressions that follow are
1998             treated as regular expressions.</p>
1999             
2000             <p>For example, the regular expression AAP <span
2001             class="fixedwidth">require affiliation ~
2002             ^member@.+\.edu$</span> would evaluate to allowing
2003             anyone with an <span
2004             class="fixedwidth">eduPersonScopedAffiliation</span> of
2005             <span class="fixedwidth">member</span> from a .edu
2006             domain.</p>
2007
2008           </dd>
2009         </dl>
2010       <br>
2011     </blockquote>
2012
2013     <h4><a name="4.e."></a>4.e. Designing AAP's</h4>
2014
2015     <blockquote>
2016       <p>Shibboleth allows a user and a site to release a varying
2017       set of attributes to a destination site, and does not impose
2018       restrictions on the kinds of attribute information provided
2019       by an AA. Target implementations must also be prepared to
2020       examine the attributes they receive and filter them based on
2021       policies about what information to permit an origin site to
2022       assert about its users.</p>
2023
2024       <p>Attribute acceptance is the process of filtering attribute
2025       values before passing them on to a resource manager, such as
2026       the <span class="fixedwidth">mod_shibrm</span> module. Data blocked by AAP filters
2027       will not be passed to the CGI environment or used when
2028       enforcing <span class="fixedwidth">.htaccess</span> rules.
2029       Note that the attribute assertion exported to the
2030       <span class="fixedwidth">Shib-Attributes</span> header is unfiltered.</p>
2031
2032       <p>The Shibboleth distribution supports <span class="fixedwidth">scoped</span> and
2033       <span class="fixedwidth">simple</span> filtering policies for different kinds of
2034       attributes.</p>
2035       
2036       <p><b>An essential part of the Shibboleth trust fabric is ensuring
2037       that sites only assert attributes for domains for which they are
2038       considered authoritative by the target. Typically, this means
2039       that Brown University will be trusted to assert attributes only
2040       scoped to <span class="fixedwidth">brown.edu</span>. Unless
2041       there are very specific circumstances requiring this restriction
2042       be removed, it is strongly encouraged that such policies be in place.</b></p>
2043
2044       <h4>Scoped:</h4>
2045       <blockquote>
2046         <p>Scoped attributes are a special kind of attribute whose
2047         values are a combination of a <span class="fixedwidth">value</span> and a
2048         <span class="fixedwidth">scope</span>, or <span class="fixedwidth">context</span> for the value. An
2049         example is <span class="fixedwidth">eduPersonScopedAffiliation</span>, which adds a
2050         scope to the defined set of <span class="fixedwidth">eduPersonAffiliation</span>
2051         values, such as <span class="fixedwidth">student</span>, <span class="fixedwidth">member</span>, or
2052         <span class="fixedwidth">faculty</span>. Scopes are expressed as DNS domains and
2053         subdomains.</p>
2054
2055         <p>Any <span class="fixedwidth">scoped</span> attribute can be
2056         scoped only to the origin site's permitted domains. These
2057         domains are listed in the sites file that provides trust
2058         information to the system. Domains can be explicit or
2059         regular expressions, and can be changed by a target to meet
2060         its needs if a local version of the file is created. Thus,
2061         attribute acceptance processing for <span class="fixedwidth">scoped</span>
2062         attributes is based on the sites file, in addition to the mechanism described
2063         below for <span class="fixedwidth">simple</span> attributes.</p>
2064       </blockquote>
2065
2066       <h4>Simple:</h4>
2067       <blockquote>
2068         <p>Simple attributes are attributes whose value is expressed
2069         in XML as a Text node; that is, the value is just a string.
2070         Multiple values are permitted.
2071         <span class="fixedwidth">eduPersonEntitlement</span>, in which the values are URIs,
2072         is one example of a simple attribute.</p>
2073         <p>In this release, simple (and scoped) attribute acceptance is
2074         controlled with an external policy file written in XML. The
2075         schema for the file is described by the
2076         <span class="fixedwidth">shibboleth.xsd</span> schema, and an example file is
2077         included, <span class="fixedwidth">AAP.xml</span>. If the <span class="fixedwidth">aap-uri</span>
2078         parameter in the <span class="fixedwidth">shibboleth.ini</span> file is left out,
2079         then no policy is applied, and no filtering is done.
2080         Otherwise, the rules encoded in the file are used.</p>
2081         <p>The policy is a default-deny algorithm that requires
2082         permissible attributes and values be listed explicitly. That
2083         is, an empty file permits nothing. Each attribute to be
2084         permitted must be listed in the file by name in an
2085         <span class="fixedwidth">&lt;AttributeRule&gt;</span>. Each such rule is a
2086         collection of <span class="fixedwidth">&lt;SiteRule&gt;</span> elements along with
2087         an optional <span class="fixedwidth">&lt;AnySite&gt;</span> default rule. In turn
2088         each site rule is a set of <span class="fixedwidth">&lt;Value&gt;</span> rules that
2089         specify matches to permit, either literal or regular
2090         expressions.</p>
2091       </blockquote>
2092
2093       <p>A syntax summary follows:</p>
2094       <blockquote>
2095
2096         <p><span class="fixedwidth">&lt;AttributeAcceptancePolicy</span></p>
2097           <blockquote>The top level element in the
2098           file.</blockquote>
2099
2100         <p><span class="fixedwidth">&lt;AttributeRule Name=&quot;attribute
2101         URI&quot;&gt;</span></p>
2102           <blockquote>Specifies a rule for an attribute, named with
2103           its URI.</blockquote>
2104
2105         <p><span class="fixedwidth">&lt;AnySite&gt;</span></p>
2106           <blockquote>Specifies a rule that always applies to the
2107           attribute, regardless of the asserting AA.</blockquote>
2108
2109         <p><span class="fixedwidth">&lt;SiteRule
2110         Name=&quot;site.domain.name&quot;&gt;</span></p>
2111           <blockquote>A rule that applies to the origin site AA
2112           corresponding to the domain name.</blockquote>
2113
2114         <p><span class="fixedwidth">&lt;AnyValue&gt;</span></p>
2115           <blockquote>Specifies a rule that always applies to the
2116           attribute and site, regardless of the value(s).</blockquote>
2117
2118         <p><span class="fixedwidth">&lt;Value Type=&quot;type&quot;&gt;</span></p>
2119           <blockquote>Specifies a value to permit, either directly
2120           using <span class="fixedwidth">type</span> <span class="fixedwidth">literal</span>, or using a set of
2121           matching expressions as <span class="fixedwidth">type</span> <span class="fixedwidth">regexp</span>.
2122           <span class="fixedwidth">literal</span> is the default if <span class="fixedwidth">Type</span> is not
2123           specified.</blockquote>
2124
2125        </blockquote>
2126
2127        <p>The regular expression syntax is a subset of the usual
2128        Perl and Unix syntaxes that is described in the XML Schema
2129        specification by the W3C. Most typical expressions should
2130        work. Be sure to anchor them using <span class="fixedwidth">^</span> and <span class="fixedwidth">$</span>
2131        to avoid unintentional matches midstring.</p>
2132
2133        <p>Note that the AAP rules described in this section are not
2134        part of the Shibboleth architecture and are simply one
2135        possible set of approaches provided by this implementation.</p>
2136     </blockquote>
2137
2138     <h4><a name="4.f."></a>4.f. Using Attributes in
2139     Applications</h4>
2140
2141     <blockquote>
2142       <p>Apart from the simple RM functionality provided, attribute
2143       information may be made available directly to applications
2144       via the standard practice of creating custom HTTP request
2145       headers before passing control to the application.
2146       Applications should make no assumption about the presence of
2147       specific attributes for their use unless they have intimate
2148       knowledge of the attribute release policies in place.</p>
2149
2150       <p>The <span class="fixedwidth">ShibMapAttribute</span> directive controls this
2151       interface, and maps a Shibboleth attribute (identified by an
2152       unambiguous URI) to a header name, such as
2153       <span class="fixedwidth">Shib-EP-Affiliation</span>. Using that example, any values
2154       of the mapped attribute will be placed in that header,
2155       delimited by spaces. An application that uses a CGI-like
2156       syntax to access the header will find the values in the
2157       <span class="fixedwidth">HTTP_SHIB_EP_AFFILIATION</span> variable. Using the
2158       command, any attribute can be placed in any header, to drive
2159       legacy applications that expect information in a particular
2160       header.</p>
2161
2162       <p>The <span class="fixedwidth">REMOTE_USER</span> variable is a special case that
2163       is generally populated automatically by the web server based
2164       on an internal piece of data that represents the user's
2165       <span class="fixedwidth">username</span>. Unlike many authentication modules,
2166       Shibboleth does not guarantee that <span class="fixedwidth">REMOTE_USER</span> will
2167       have any value. If it does, it is set solely based on a
2168       <span class="fixedwidth">ShibMapAttribute</span> command. For many purposes, the
2169       <span class="fixedwidth">urn:mace:dir:attribute-def:eduPersonPrincipalName</span>
2170       attribute should be mapped to <span class="fixedwidth">REMOTE_USER</span>. Even so,
2171       EPPN may not be provided by the AA, and <span class="fixedwidth">REMOTE_USER</span>
2172       might still be empty.</p>
2173       
2174       <p>The <span class="fixedwidth">Shib-Origin-Site</span> variable will contain the
2175       unique name/identifier of the origin site of the user. Some applications may use this
2176       to lookup additional policy or application data. It normally takes the form of a URI
2177       but could be any string.</p>
2178
2179       <p>Finally, the <span class="fixedwidth">ShibExportAssertion</span> flag instructs
2180       the module to place the entire XML message containing the
2181       SAML attribute information from the AA into a base64-encoded
2182       header called <span class="fixedwidth">Shib-Attributes</span>. This is a raw
2183       interface that provides an application with the entire AA
2184       response, and is not a filtered view based on any attribute
2185       acceptance rules or even based on what attributes are
2186       recognized by the target. What was sent is what you see.</p>
2187     </blockquote>
2188
2189     <h4><a name="4.g."></a>4.g. <span
2190     class="fixedwidth">siterefresh</span></h4>
2191
2192     <blockquote>
2193       <p>Shibboleth provides a simple tool called <span
2194       class="fixedwidth">siterefresh</span> in the <span
2195       class="fixedwidth">/opt/shibboleth/bin</span> folder of the
2196       distribution to maintain metadata files referenced by <span
2197       class="fixedwidth">shibboleth.ini</span>.  It will return 0 on
2198       success and a negative number on failure and log errors to <span
2199       class="fixedwidth">stderr</span>.  If the data in the new metadata
2200       file is bad or the signature is invalid, the existing copy is
2201       kept.  The SHAR and SHIRE stat the file each time the data is
2202       used, allowing them to detect and utilize updates in real-time
2203       operation.</p>
2204
2205       <p><span class="fixedwidth">siterefresh</span> takes the following
2206       command-line parameters:</p>
2207
2208       <dl>
2209         <dd class="attribute">
2210           <span class="fixedwidth">--url &lt;URL&gt;</span>
2211         </dd>
2212
2213         <dd class="value">
2214           <p>Specifies the <span class="fixedwidth">URL</span> of the
2215           remote metadata file to update the local file.</p>
2216         </dd>
2217
2218         <dd class="attribute">
2219           <span class="fixedwidth">--out &lt;pathname&gt;</span>
2220         </dd>
2221
2222         <dd class="value">
2223           <p>Specifies the local file to write the new metadata to.</p>
2224         </dd>
2225
2226         <dd class="attributeopt">
2227           <span class="fixedwidth">--cert &lt;pathname&gt;</span>
2228         </dd>
2229
2230         <dd class="valueopt">
2231           <p>Specifies the location of a certificate stored in <span
2232           class="fixedwidth">PEM</span> format used to validate the
2233           signature of the metadata file.  Since much of Shibboleth's
2234           trust flows from this metadata file, this option is highly
2235           recommended.</p>
2236         </dd>
2237
2238         <dd class="attributeopt">
2239           <span class="fixedwidth">--schema &lt;pathname&gt;</span>
2240         </dd>
2241
2242         <dd class="valueopt">
2243           <p>Optionally defines a base path for schemas.  Defaults to
2244           <span
2245           class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>.</p>
2246         </dd>
2247        </dl>
2248
2249        <p>A complete command issued to <span
2250        class="fixedwidth">siterefresh</span> would take the form:</p>
2251      
2252        <blockquote><span class="fixedwidth">
2253          /opt/shibboleth/bin/siterefresh --out sites.xml --cert internet2.pem \<br>
2254                 --url http://wayf.internet2.edu/InQueue/sites.xml
2255        </span></blockquote>
2256      
2257        <p>It is recommended that similar commands be added to a <span
2258        class="fixedwidth">crontab</span> to keep the sites and trust files refreshed.</p>
2259     </blockquote>
2260
2261
2262     <br>
2263     <hr>
2264     <br>
2265
2266     <h3><a name="5."></a>5. Troubleshooting</h3>
2267
2268     <p>This section provides basic information about testing
2269     Shibboleth targets. This information is not intended to be
2270     comprehensive, but instead rudimentary guidelines for basic
2271     configuration tests and problems. For more detailed information
2272     or answers to specific problems not addressed in this section,
2273     please mail <a href=
2274     "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>
2275     with a thorough description of errors and configurations
2276     used.</p>
2277
2278     <h4><a name="5.a."></a>5.a. Basic Testing</h4>
2279
2280     <blockquote>
2281       <p>The target may be tested by generating a folder with very
2282       basic access controls on it, and accessing it using a web
2283       browser. Place a simple webpage such as <span class="fixedwidth">index.html</span>
2284       in <span class="fixedwidth">/secure/</span>. Then, add the following lines to
2285       <span class="fixedwidth">httpd.conf</span>, which should be removed when testing is
2286       over:</p>
2287
2288       <blockquote>
2289         <span class="fixedwidth"># Configure a test directory<br>
2290         &lt;Location /secure&gt;<br>
2291         &nbsp;&nbsp;AuthType shibboleth<br>
2292         &nbsp;&nbsp;require valid-user<br>
2293         <br>
2294         &nbsp;&nbsp;# Per-directory SHIRE Configuration<br>
2295         &nbsp;&nbsp;#ShibBasicHijack On<br>
2296         &nbsp;&nbsp;#ShibSSLOnly On<br>
2297         &nbsp;&nbsp;#ShibAuthLifetime 60<br>
2298         &nbsp;&nbsp;#ShibAuthTimeout 600<br>
2299         <br>
2300         &nbsp;&nbsp;# RM Configuration<br>
2301         &nbsp;&nbsp;#AuthGroupFile /foo<br>
2302         &nbsp;&nbsp;#ShibExportAssertion On<br>
2303         &lt;/Location&gt;<br>
2304         </span>
2305       </blockquote>
2306
2307       <p><b>For information regarding specific error messages that
2308       may be generated if the target does not work successfully,
2309       please refer to section <a href="#4.b.">4.b</a>, or write <a
2310       href=
2311       "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.</b></p>
2312     </blockquote>
2313
2314     <h4><a name="5.b."></a>5.b. Common Problems</h4>
2315
2316     <blockquote>
2317       <p>A knowledge base is being developed in the <a
2318       href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.
2319       html">Shibboleth Deployer's FAQ</a>.  Please mail <a href=
2320       "mailto:mace-shib-users@internet2.edu">mace-shib-users@
2321       internet2.edu</a> with any additional questions or problems
2322       encountered that are not answered by this basic guide.</p>
2323     </blockquote>
2324   </body>
2325 </html>