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