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