ee8a04061640e4956e10b798f40a920037bfe346
[java-idp.git] / doc / DEPLOY-GUIDE-ORIGIN.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3 <html>
4   <head>
5     <meta name="generator" content=
6     "HTML Tidy for Mac OS X (vers 1st January 2002), see www.w3.org">
7
8     <title>Shibboleth Origin Deployment Guide</title>
9     <meta http-equiv="Content-Type" content=
10     "text/html; charset=utf-8">
11     <style type="text/css">
12
13 html
14 {       
15 background-color: #FFFFFF;
16 color: #000000;
17 margin: .5em;
18 }
19 a:visited
20 {
21 color: #999999;
22 }
23 a:link
24 {
25 color: #990000;
26 }
27 a:active
28 {
29 color: #440000;
30 }
31 dl
32 {
33 background-color: #DDDDDD;
34 background-image: none;
35 margin: 5px;
36 padding: 0px;
37 border-style: solid;
38 border-bottom-width: 2px;
39 border-top-width: 2px;
40 border-left-width: 2px;
41 border-right-width: 2px;
42 }
43 dt
44 {
45 background-color: #DDDDDD;
46 background-image: none;
47 margin: 1px;
48 padding: 1px;
49 }
50 dd
51 {
52 background-color: #DDDDDD;
53 background-image: none;
54 margin: 0px;
55 padding: 1px;
56 }
57 .attribute
58 {
59 font-size: 115%;
60 font-color: #000000;
61 text-align: left;
62 background-color: #DDDDDD;
63 border: 1px black inset;
64 background-image: none;
65 margin: 0px;
66 padding: 2px;
67 }
68 .value
69 {
70 font-color: #000000;
71 text-align: left;
72 background-color: #EEEEEE;
73 background-image: none;
74 padding-top: 0em;
75 padding-bottom: 0.5em;
76 padding-right: 1em;
77 padding-left: 5em;
78 border-style: solid;
79 border-bottom-width: none;
80 border-top-width: none;
81 border-left-width: 1px;
82 border-right-width: 1px;
83 }
84 .attributeopt
85 {
86 font-size: 115%;
87 font-color: #000000;
88 text-align: left;
89 background-color: #BCBCEE;
90 border: 1px black inset;
91 background-image: none;
92 margin: 0px;
93 padding: 2px;
94 }
95 .valueopt
96 {
97 font-color: #000000;
98 text-align: left;
99 background-color: #DDDDFF;
100 background-image: none;
101 padding-top: 0em;
102 padding-bottom: 0.5em;
103 padding-right: 1em;
104 padding-left: 5em;
105 border-style: solid;
106 border-bottom-width: none;
107 border-top-width: none;
108 border-left-width: 1px;
109 border-right-width: 1px;
110 }
111 .attributelong
112 {
113 font-size: 85%;
114 font-color: #000000;
115 text-align: left;
116 background-color: #DDDDDD;
117 border: 1px black inset;
118 background-image: none;
119 margin: 0px;
120 padding: 2px;
121 }
122 .attributeoptlong
123 {
124 font-size: 85%;
125 font-color: #000000;
126 text-align: left;
127 background-color: #BCBCEE;
128 border: 1px black inset;
129 background-image: none;
130 margin: 0px;
131 padding: 2px;
132 }
133 .demo
134 {
135 background-color: #EEEEEE;
136 padding: 3px;
137 }
138 .fixedwidth
139 {
140 font-family: monospace;
141 font-size: 90%;
142 font-color: #121212;
143 }
144
145   </style>
146   </head>
147
148   <body link="red" vlink="red" alink="black" bgcolor="white">
149     <center>
150       <h2>Shibboleth Origin Deployment Guide</h2>
151     </center>
152     Shibboleth Origin Deployment Guide<br>
153     draft-internet2-mace-shibboleth-shib-origin-deploy-30.html<br>
154     Nate Klingenstein<br>
155     12 June, 2003<br>
156     Comments should be directed to <a href=
157     "mailto:ndk@internet2.edu">ndk@internet2.edu</a>.<br>
158      
159     <h3>This version of the deploy guide is for Shibboleth v1.0.  For
160     documentation related to prior versions of Shibboleth, please
161     consult the appropriate branch in the Shibboleth
162     CVS.</h3>
163
164     <h3>Federations have been abstracted out from the Shibboleth
165     documentation.  For further information on using Shibboleth in a
166     federation, refer to the federation guide.</h3>
167
168     <p>Shibboleth v1.0 is stable and secure enough to deploy in
169     production scenarios.  While attempts have been made to include all
170     functionality that would represent a break of interoperability with
171     previous versions in v1.0, be aware that future versions of
172     Shibboleth are likely to be developed and may include further
173     implementation of the architectural document, functional
174     enhancements, and user interface improvements.</p>
175
176         <h4>Major New Features - 1.0</h4>
177         This new release contains many improvements and enhancements, including: 
178         
179         <h5>Federation Support</h5> 
180         <ol>
181                 <li>
182                 Federation and trust support has been substantially extended. Federation 
183                 structures are now defined. The set of metadata collected and managed 
184                 by each Federation is more fully defined. The configuration values 
185                 assigned by a Federation are now identified. <br>
186                 </li>
187                 <li>
188                 There is some support for targets to be members of multiple federations; 
189                 this support will continue to evolve. When a browser user arrives, 
190                 a target will determine which federation their origin belongs to, 
191                 and then use the trust fabric associated with that Federation. <br>
192                 </li>
193                 <li>
194                 Better support for flexible and bilateral trust agreements. A key 
195                 specific to an origin site can be used to vallidate its signature. 
196                 <br>
197                 </li>
198
199                 <li>
200                 This version contains a significantly more mature security implementation, 
201                 and should meet the security requirements of typical sites. <p></p>
202                 </li>
203         </ol>
204
205         <h5>Origin</h5> 
206         <ol>
207
208                 <li> The Attribute Authority has a powerful new attribute resolver. 
209                 Simple scenarios (using a string attribute stored in ldap) can be 
210                 accomplished by merely editing a configuration file. Java classes 
211                 may still be written for more complex evaluations (eg retrieving information 
212                 from multiple disparate repositories, and computing the SAML attribute 
213                 using business rules). This should greatly simplify the process of 
214                 configuring the AA to support additional general attributes.<br>
215                 </li>
216         </ol>
217
218         <h5>Target</h5> 
219         <ol>
220                 <li> Significantly more flexibility in configuring targets to ensure 
221                 robustness. Failover and redundant configurations are now supported. 
222                 <br>
223                 <ol>
224                         <li>The SHAR may now optionally store its session and attribute 
225                         cache in a back-end database in addition to the previously available 
226                         in-memory option. This would allow a site to run an apache server 
227                         farm, with multiple SHARs, supporting the same set of sessions. 
228                         </li>
229                         <li>Federation supplied files (sites.xml and trust.xml) are now 
230                         refreshed in a much more robust manner. <br>
231                         </li>
232
233                 </ol>
234                 </li>
235                 <li>Attribute acceptance policies have been greatly enhanced, and now 
236                 supports filtering of attribute values by sites. <br>
237                 </li>
238                 <li>The SHAR can be configured to request specific attributes from the 
239                 Origin. <br>
240                 </li>
241         </ol>
242         <h5>Miscellaneous</h5> 
243         <ol>
244                 <li>Origin sites can configure a value to describe the type of authentication 
245                 mechanism used at the origin site(e.g. password, Kerberos, PKI, etc.). 
246                 This value is made available on the target side as Shib-Authentication-Method. 
247                 <br>
248                 </li>
249                 <li>Various improvements to error handling. Origin sites are now able 
250                 to supply an &quot;error URL&quot; and contact information to a federation. 
251                 When a target encounters an error, it can include this information 
252                 in the error page. <br>
253
254                 </li>
255                 <li>Local time string values are now used in log files. <br>
256                 </li>
257                 <li>Internationalization support has been extended.</li>
258         </ol>
259
260     <p>Before starting, please sign up for all applicable <a href=
261     "http://shibboleth.internet2.edu/shib-misc.html#mailinglist">
262     mailing lists</a>. Announcements pertinent to Shibboleth
263     deployments and developments and resources for deployment
264     assistance can be found here.</p>
265
266     <p>Please send any questions, concerns, or eventual confusion
267     to <a href=
268     "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.
269     This should include, but not be limited to, questions about the
270     documentation, undocumented problems, installation or
271     operational issues, and anything else that arises. Please
272     ensure that you have the <a href=
273     "http://shibboleth.internet2.edu/release/shib-download.html">appropriate
274     .tarball</a> for your operating system.</p>
275     <br>
276     <hr>
277     <br>
278     <br>
279      
280
281     <h3><a name="TOC"></a>Shibboleth Origin -- Table of
282     Contents</h3>
283     <br>
284      
285
286     <ol type="1">
287       <li>
288         <h4><a href="#1."><font color="black">Shibboleth
289         Overview</font></a></h4>
290
291         <ol type="a">
292           <li><a href="#1.a."><font color=
293           "black">Origin</font></a></li>
294
295           <li><a href="#1.b."><font color=
296           "black">Target</font></a></li>
297
298           <li><a href="#1.c."><font color=
299           "black">WAYF</font></a></li>
300
301           <li><a href="#1.d."><font color=
302           "black">Federations</font></a></li>
303         </ol>
304       </li>
305
306       <li>
307         <h4><a href="#2."><font color=
308         "black">Planning</font></a></h4>
309
310         <ol type="a">
311           <li><a href="#2.a."><font color=
312           "black">Requirements</font></a></li>
313
314           <li><a href="#2.b."><font color="black">Join a
315           Federation</font></a></li>
316
317           <li><a href="#2.c."><font color="black">Security
318           Considerations</font></a></li>
319
320           <li><a href="#2.d."><font color="black">Server
321           Certs</font></a></li>
322
323           <li><a href="#2.e."><font color="black">Attribute Release
324           Policies</font></a></li>
325
326           <li><a href="#2.f."><font color="black">Designate
327           Contacts</font></a></li>
328
329           <li><a href="#2.g."><font color="black">Browser
330           Requirements</font></a></li>
331
332           <li><a href="#2.h."><font color=
333           "black">Clocks</font></a></li>
334
335           <li><a href="#2.i."><font color="black">Other
336           Considerations</font></a></li>
337         </ol>
338       </li>
339
340       <li>
341         <h4><a href="#3."><font color=
342         "black">Installation</font></a></h4>
343
344         <ol type="a">
345           <li><a href="#3.a."><font color="black">Software
346           Requirements</font></a></li>
347
348           <li><a href="#3.b."><font color="black">Deploy HS and
349           AA</font></a></li>
350
351         </ol>
352       </li>
353
354       <li>
355         <h4><a href="#4."><font color="black">Getting
356         Running</font></a></h4>
357
358         <ol type="a">
359           <li><a href="#4.a."><font color="black">Basic
360           Configuration</font></a></li>
361
362           <li>
363             <a href="#4.b."><font color="black">Key Generation and
364             Certificate Installation</font></a> 
365
366           </li>
367
368           <li><a href="#4.c."><font color="black">Linking the
369           Authentication System to the HS</font></a>
370           
371             <ol type="i">
372               <li><a href="#4.c.i."><font color="black">Enabling client
373               certificate authentication</font> <font color="#5555EE">(optional)</font></a></li>
374             </ol>
375           </li>
376
377           <li><a href="#4.d."><font color="black">Establishing
378           default ARP's for the origin community</font></a></li>
379
380                   <li><a href="#4.e."><font color="black">Modifying the 
381                   default Attribute Resolver configuration</font></a></li>
382
383         </ol>
384       </li>
385
386       <li>
387         <h4><a href="#5."><font color="black">Advanced
388         Configuration</font></a></h4>
389
390         <ol type="a">
391           <li>
392             <a href="#5.a."><font color="black">ARP
393             Overview</font></a> 
394
395             <ol type="i">
396               <li><a href="#5.a.i."><font color="black">ARP
397               Processing</font></a></li>
398
399               <li><a href="#5.a.ii."><font color="black">ARP
400               Syntax</font></a></li>
401             </ol>
402               <li><a href="#5.b."><font color="black">Sharing
403               certificate/key pairs between Apache and Java
404               keystores</font> <font color="#5555EE">(optional)</font></a></li>
405           <li><a href="#5.c."><font color="black">The Attribute Resolver</font></a></li>
406           <li><a href="#5.d."><font color="black">Local Error Page</font></a></li>
407         </ol>
408       </li>
409
410       <li>
411         <h4><a href="#6."><font color=
412         "black">Troubleshooting</font></a></h4>
413
414         <ol type="a">
415           <li><a href="#6.a."><font color="black">Basic
416           Testing</font></a></li>
417
418           <li><a href="#6.b."><font color=
419           "black">Logging</font></a></li>
420
421           <li><a href="#6.c."><font color="black">Common
422           Problems</font></a></li>
423         </ol>
424       </li>
425     </ol>
426     <br>
427     <hr>
428     <br>
429      
430
431     <h3><a name="1."></a>1. Shibboleth Overview</h3>
432
433     <p>Shibboleth is a system designed to exchange attributes
434     across realms for the primary purpose of authorization. It
435     provides a secure framework for one organization to transmit
436     attributes about a web-browsing individual across security
437     domains to another institution. In the primary usage case, when
438     a user attempts to access a resource at a remote domain, the
439     user's own home security domain can send certain information
440     about that user to the target site in a trusted exchange. These
441     attributes can then be used by the resource to help determine
442     whether to grant the user access to the resource. The user may
443     have the ability to decide whether to release specific
444     attributes to certain sites by specifying personal Attribute
445     Release Policies (ARP's), effectively preserving privacy while
446     still granting access based on trusted information.</p>
447
448     <p>When a user first tries to access a resource protected by
449     Shibboleth, they are redirected to a service which asks the
450     user to specify the organization from which they want to
451     authenticate. If the user has not yet locally authenticated to
452     a WebISO service, the user will then be redirected to their
453     home institution's authentication system. After the user
454     authenticates, the Shibboleth components at the local
455     institution will generate a temporary reference to the user,
456     known as a handle, for the individual and send this to the
457     target site. The target site can then use the handle to ask for
458     attributes about this individual. Based on these attributes,
459     the target can decide whether or not to grant access to the
460     resource. The user may then be allowed to access the requested
461     materials.</p>
462
463     <p>There are several controls on privacy in Shibboleth, and
464     mechanisms are provided to allow users to determine exactly
465     which information about them is released. A user's actual
466     identity isn't necessary for many access control decisions, so
467     privacy often is needlessly compromised. Instead, the resource
468     often utilizes other attributes such as faculty member or member
469     of a certain class. While these are commonly determined using
470     the identity of the user, Shibboleth provides a way to mutually
471     refer to the same principal without revealing that principal's
472     identity. Because the user is initially known to the target site
473     only by a randomly generated temporary handle, if sufficient,
474     the target site might know no more about the user than that the
475     user is a member of the origin organization. This handle should
476     never be used to decide whether or not to grant access, and is
477     intended only as a temporary reference for requesting
478     attributes.</p>
479
480     <h4><a name="1.a."></a>1.a. Origin</h4>
481
482     <blockquote>
483       <p>There are four primary components to the origin side in
484       Shibboleth: the Attribute Authority (AA), the Handle Service
485       (HS), the directory service, and the local sign-on system
486       (SSO). The AA and HS are provided with Shibboleth, and an
487       open-source WebISO solution Pubcookie can be obtained from
488       www.pubcookie.org; the directory is provided by the origin
489       site. Shibboleth is able to interface with a directory
490       exporting an LDAP interface containing user attributes, and is
491       designed such that programming interfaces to other
492       repositories should be readily implemented. Shibboleth relies
493       on standard web server mechanisms to trigger local
494       authentication. A .htaccess file can be easily used to trigger
495       either the local WebISO system or the web server's own Basic
496       Auth mechanism, which will likely utilize an enterprise
497       authentication system, such as Kerberos.</p>
498
499       <p>From the origin site's point of view, the first contact
500       will be the redirection of a user to the handle service,
501       which will then consult the SSO system to determine whether
502       the user has already been authenticated. If not, then the
503       browser user will be asked to authenticate, and then sent
504       back to the target URL with a handle bundled in an attribute
505       assertion. Next, a request from the Shibboleth Attribute
506       Requester (SHAR) will arrive at the AA which will include the
507       previously mentioned handle. The AA then consults the ARP's
508       for the directory entry corresponding to the handle, queries
509       the directory for these attributes, and releases to the SHAR
510       all attributes the SHAR is entitled to know about that
511       user.</p>
512     </blockquote>
513
514     <h4><a name="1.b."></a>1.b. Target</h4>
515
516     <blockquote>
517       <p>There are three primary components to the target side in
518       Shibboleth: the Shibboleth Indexical Reference Establisher
519       (SHIRE), the Shibboleth Attribute Requester (SHAR), and the
520       resource manager (RM). An implementation of each of these is
521       included in the standard Shibboleth distribution. These
522       components are intended to run on the same web server.</p>
523
524       <p>From the target's point of view, a browser will hit the RM
525       with a request for a Shibboleth-protected resource. The RM
526       then allows the SHIRE to step in, which will use the WAYF to
527       acquire the name of a handle service to ask about the user.
528       The handle service (HS) will then reply with a SAML
529       authentication assertion containing a handle, which the SHIRE
530       then hands off to the SHAR. The SHAR uses the handle and the
531       supplied address of the corresponding attribute authority
532       (AA) to request all attributes it is allowed to know about
533       the handle. The SHAR performs some basic validation and
534       analysis based on attribute acceptance policies (AAP's).
535       These attributes are then handed off to the RM, which is
536       responsible for using these attributes to decide whether to
537       grant access.</p>
538     </blockquote>
539
540     <h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
541
542     <blockquote>
543       <p>The WAYF service can be either outsourced and operated by
544       a federation or deployed as part of the SHIRE. It is responsible
545       for allowing a user to associate themself with an institution
546       of their specification, then redirecting the user to the
547       known address for the handle service of that institution.</p>
548     </blockquote>
549
550     <h4><a name="1.d."></a>1.d. Federations</h4>
551
552     <blockquote>
553       <p>A Shibboleth federation provides part of the underlying trust
554       required for function of the Shibboleth architecture. A federation
555       is a group of organizations(universities, corporations,
556       content providers, etc.) who agree to exchange attributes
557       using the SAML/Shibboleth protocols and abide by a common set
558       of policies and practices. In so doing, they must implicitly
559       or explicitly agree to a common set of guidelines. Joining a
560       federation is not explicitly necessary for operation of Shibboleth,
561       but it dramatically expands the number of targets and origins
562       that can interact without defining bilateral agreements
563       between all these parties.</p>
564
565       <p>A federation can be created in a variety of formats and trust
566       models, but must provide a certain set of services to federation
567       members. It needs to supply a registry to process
568       applications to the federation and distribute membership
569       information to the origin and target sites. This must include
570       distribution of the PKI components necessary for trust
571       between origins and targets. There also needs to be a set of
572       agreements and best practices defined by the federation governing
573       the exchange, use, and population of attributes before and
574       after transit, and there should be a way to find information
575       on local authentication and authorization practices for federation
576       members.</p>
577     </blockquote>
578     <br>
579     <br>
580     <br>
581     <hr>
582     <br>
583      
584
585     <h3><a name="2."></a>2. Planning</h3>
586
587     <p>There are several essential elements that must be present in
588     the environment to ensure Shibboleth functions well, both
589     political and technical. Shibboleth is entirely written in
590     Java on the origin side. These are the recommendations and
591     requirements for a successful implementation of a Shibboleth
592     origin.</p>
593
594     <h4><a name="2.a."></a>2.a. Requirements</h4>
595
596     <ul>
597       <li>
598         <p>A common institutional directory service should be
599         operational; Shibboleth comes with LDAP capabilities
600         built in, and the Attribute Authority has a Java API which
601         will allow specification of interfaces with legacy
602         directories. This is discussed further in <a href=
603         "#4.d.">section 4.d</a>.</p>
604       </li>
605
606       <li>
607         <p>A method to authenticate browser users must be in place,
608         preferably in the form of an enterprise authentication
609         service. Some form of an SSO or a WebISO service is not
610         explicitly necessary for Shibboleth; however, it is highly
611         recommended. Implementation details of this are discussed in
612         <a href="#4.c.">section 4.c</a>.</p>
613       </li>
614
615       <li>
616         <p>Shibboleth is known to work on Linux and Solaris, but
617         should function on any platform that has a Tomcat
618         implementation.</p>
619       </li>
620
621       <li>
622         <p>It is recommended that a web server must be deployed that
623         can host Java servlets and Tomcat, although not explicitly
624         necessary, as Tomcat can still host an origin without it.</p>
625       </li>
626     </ul>
627
628     <h4><a name="2.b."></a>2.b. Join a Federation</h4>
629
630     <blockquote>
631       <p>While it is not necessary for a target or origin to join a
632       federation, doing so greatly facilitates the implementation of
633       multilateral trust relationships. Each federation will have a
634       different application process. When an origin is accepted into a
635       federation, its information is added to the sites file used by the
636       WAYF and target sites.</p>
637       
638       <p><b>It may be necessary to join multiple federations
639       depending on the sites with whom you wish to exchange
640       attributes and the terms under which these interactions will
641       take place.  An origin site exists within the context of a
642       single federation, while a single target may accept assertions
643       issued by multiple federations if they are all recognized by
644       the SHAR.  If an organization wishes to be a member of
645       multiple federations, it must run a separate origin site for
646       each federation, including a separate AA and HS.</b></p>
647
648       <p>Attribute release and acceptance policies, the use and
649       caching of attributes, and definition of commonly traded
650       attributes are examples of specifications a federation may
651       make.  For more information on federations, please refer to
652       the Deployer's Guide to Federations and the Shibboleth v1.0
653       architectural document.</p>
654     </blockquote>
655
656     <h4><a name="2.c."></a>2.c. Security Considerations</h4>
657
658     <blockquote>
659       <p>Shibboleth's protocols and software have been extensively
660       engineered to provide protection against many attacks.
661       However, the most secure protocol can be compromised if it is
662       placed in an insecure environment. To ensure Shibboleth is as
663       secure as possible, there are several recommended security
664       precautions which should be in place at local sites.</p>
665
666       <ol type="i">
667         <li>
668           <p>SSL use is optional for origin sites. Federation guidelines
669           should be considered when determining whether to
670           implement SSL, and, in general, SSL should be used for
671           interactions with client machines to provide the
672           necessary authentication and encryption to ensure
673           protection from man-in-the-middle attacks. It is strongly
674           suggested that all password traffic or similarly
675           sensitive data should be SSL-protected. Assessment of the
676           risk tradeoff against possible performance degradation
677           should be performed for all applications.</p>
678         </li>
679
680         <li>
681           <p>Many other attacks can be made on the several
682           redirection steps that Shibboleth takes to complete
683           attribute transfer. The best protection against this is
684           safeguarding the WAYF service and ensuring that rogue
685           targets and origins are not used, generally by
686           development of the trust model underneath Shibboleth.
687           Shibboleth also leverages DNS for security, which is not
688           uncommon, but attacks concerning bad domain information
689           should be considered.</p>
690         </li>
691
692         <li>
693           <p>Information regarding origin users is generally
694           provided by the authoritative enterprise directory, and
695           the acceptance of requests from target applications can
696           be carefully restricted to ensure that all requests the
697           SHAR performs are authorized and all information the
698           origin provides is accurate. Proper security measures
699           should also be in place on directory access and
700           population(see <a href=
701           "http://www.georgetown.edu/giia/internet2/ldap-recipe/#AccessControl">
702           Access Control</a> in the <a href=
703           "http://www.georgetown.edu/giia/internet2/ldap-recipe/">LDAP
704           recipe</a> for more information). Use of plaintext
705           passwords is strongly advised against.</p>
706         </li>
707
708         <li>
709           <p>Server platforms should be properly secured,
710           commensurate with the level that would be expected for a
711           campus' other security services, and cookie stores on
712           client machines should be well protected.</p>
713         </li>
714       </ol>
715     </blockquote>
716
717     <h4><a name="2.d."></a>2.d. Server Certs</h4>
718
719     <blockquote>
720       <p>In the Shibboleth architecture, the SHIRE, SHAR, HS, and AA
721       must all have various client and/or server certificates for use in
722       signing assertions and creating SSL channels. These should be
723       issued by a commonly accepted CA, which may be stipulated by some
724       Federation rules. Different federations may require the use of
725       different CA's.</p>
726     </blockquote>
727
728     <h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
729
730     <blockquote>
731       <p>The Attribute Authority maintains a set of policies called
732       Attribute Release Policies (or ARP's) that govern the sharing
733       of user attributes with Shibboleth target sites. When a user
734       attempts to access a Shibboleth-protected resource, that
735       resource's SHAR queries the user's AA for all attributes to
736       which it is entitled. The SHAR provides its own name and the
737       URL of the resource on behalf of which it is making the
738       request.  The AA finds the attributes associated with the
739       browser user, determines an "Effective ARP" for this user, and
740       then sends to the SHAR only the attributes/values allowed in
741       this policy.</p>
742
743       <p>An ARP may be thought of as a sort of filter for outbound
744       attributes; it cannot create attributes or data that aren't
745       originally present, but it can limit the attributes released
746       and the values those attributes may have when released. It
747       does not change the information in the data sources in any
748       way.</p>
749
750       <p>Each ARP is comprised of one or more rules that specify
751       which attributes and values may be released to a target or set
752       of targets.  The assignment of rules to various targets is
753       quite flexible and includes mechanisms for specifying: that a
754       rule should affect all targets (default rule), exact SHAR
755       names for which a rule is applicable, regular expressions
756       against which SHAR names should be matched to determine if a
757       rule is applicable, URL trees for which a rule is
758       applicable.</p>
759
760       <p>For each request, an Effective ARP is determined by
761       locating all ARP's applicable to the designated user and
762       extracting each rule that matches the querying SHAR and
763       resource.  Attributes and values that are specified for
764       release are included in the effective ARP, while those
765       specified for denial are blocked from release.  See section <a
766       href="#5.a.i.">5.a.i</a> for details on how ARP's are
767       processed.</p>
768
769       
770       <p>Various ARP's may be combined in forming the Effective ARP.
771       For instance, the Site ARP is administratively maintained and
772       applies to all users for which the AA is answerable. User
773       ARP's apply to a specific user only, and can be maintained
774       either administratively or by the users themselves.  All ARP's
775       are specified using the same syntax and semantics.</p>
776     </blockquote>
777
778     <h4><a name="2.f."></a>2.f. Designate Contacts</h4>
779
780     <blockquote>
781       <p>Since Shibboleth deals both with daily technical and
782       operational issues and also with contractual issues, a set of
783       contacts should be set up to support the user base and to
784       facilitate interactions with other Shibboleth sites and federation
785       members. It is recommended that at least technical and
786       administrative contacts be designated.</p>
787     </blockquote>
788
789     <h4><a name="2.g."></a>2.g. Browser Requirements</h4>
790
791     <blockquote>
792       <p>A primary Shibboleth design consideration was to require
793       very little or no modification to client machines. The only
794       requirement is that a browser is used which supports cookies,
795       redirection and SSL. Browser users will have to perform an
796       additional click to submit the authentication assertion if
797       JavaScript is not functional.</p>
798     </blockquote>
799
800     <h4><a name="2.h."></a>2.h. Clocks</h4>
801
802     <blockquote>
803       <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should
804       be run on all web servers. Shibboleth employs a short handle
805       issuance time to protect against replay attacks. Because of
806       this, any significant degree of clock skew can hinder the
807       ability of users to access sites successfully.</p>
808     </blockquote>
809
810     <h4><a name="2.i."></a>2.i. Other Considerations</h4>
811
812     <blockquote>
813       <p>Especially for higher education, there are a handful of
814       laws enacted which may have important ramifications on the
815       disclosure of personal information and attributes. Since
816       Shibboleth does not necessarily need to transmit identity, it
817       is an ideal solution for many higher education situations.
818       Nevertheless, all parties within the United States of America
819       are strongly advised to consult the <a href=
820       "http://www.ed.gov/offices/OM/fpco/ferpa/">Family Educational
821       Rights and Privacy Act of 1974(FERPA)</a>, and all other
822       relevant state and federal legislation before deploying
823       Shibboleth.</p>
824     </blockquote>
825     <br>
826     <br>
827     <hr>
828     <br>
829      
830
831     <h3><a name="3."></a>3. Installation</h3>
832
833     <h4><a name="3.a."></a>3.a. Software Requirements</h4>
834
835     <p><b>The following requirements are primarily recommendations
836     based on the most common ways to run Shibboleth.  However, the
837     origin should be able to run under any servlet container
838     supporting <span class="fixedwidth">Servlet API v2.3</span> and <span class="fixedwidth">JSP specification
839     1.2</span>.</b></p>
840
841     <blockquote>
842       <ul type="circle">
843         <li><a href=
844         "http://http://www.apache.org/dist/httpd/">Apache
845         1.3.26+ (&lt;2.0)</a></li>
846
847         <li><a href="http://jakarta.apache.org/tomcat/">Tomcat
848         4.1.18-24 LE Java server</a></li>
849
850         <li>
851           <a href="http://java.sun.com/j2se/">Sun J2SE v 1.4.1_01 SDK</a>
852
853           <blockquote>
854             <p>Other versions of the JRE are not supported and are
855             known to cause errors when working with
856             certificates.</p>
857           </blockquote>
858         </li>
859
860         <li>
861           mod_jk
862
863           <blockquote>
864             <p>You may need to build mod_jk against Apache, which
865             will generally require GCC or a platform-specific C
866             compiler.</p>
867           </blockquote>
868         </li>
869
870         <li>
871           An enterprise authentication mechanism
872
873           <blockquote>
874             <p>Ideally, this will be a WebISO or SSO system such as
875             <a href= "http://pubcookie.org/">Pubcookie</a>. The
876             minimal requirement is for the web server to be able to
877             authenticate browser users and supply their identity to
878             the Handle Server.</p>
879           </blockquote>
880         </li>
881
882         <li>
883           An enterprise directory service
884
885           <blockquote>
886             <p>Shibboleth currently supports retrieving user
887             attribute information from an <a href=
888             "http://www.openldap.org">LDAP</a> directory. For
889             testing purposes, Shibboleth also supports a minimal
890             echo responder which will always return two pre-defined
891             attributes.</p>
892           </blockquote>
893         </li>
894       </ul>
895     </blockquote>
896
897     <h4><a name="3.b."></a>3.b. Deploy HS and AA</h4>
898
899     <blockquote>
900       <ol type="1">
901         <li>
902           <p>Ensure you have already obtained the proper <a href=
903           "http://shibboleth.internet2.edu/release/shib-download.html">.tarball</a>.</p>
904         </li>
905
906         <li>
907           <p>The archive will expand into a <span class="fixedwidth">shibboleth-origin-1.0/</span>
908           directory(<span class="fixedwidth">/usr/local/</span> recommended).</p>
909         </li>
910
911         <li>
912           <p>Run the following command to move the Java files into
913           Tomcat's tree:</p>
914
915           <blockquote>
916             <span class="fixedwidth">cp /usr/local/shibboleth-origin-1.0/dist/shibboleth.war
917             /usr/local/tomcat/webapps/</span>
918           </blockquote>
919         </li>
920
921         <li>
922           <p>Tomcat 4.1.x requires that several Java jarfiles used
923           by Shibboleth be located in a special "endorsed" folder to
924           override obsolete classes that Sun includes with their JVM.
925           To deal with this problem use the following command, adjusting
926           paths as needed:</p>
927           <blockquote>
928             <span class="fixedwidth">$ cp /usr/local/shibboleth-origin-1.0/endorsed/*.jar /usr/local/tomcat/common/endorsed</span>
929           </blockquote>
930          <p>Different versions of Tomcat or other Java servers may have
931          other locations in which to place these files or deal with this
932          problem. Refer to your application server's documentation to
933          find out how to properly endorse classes, if necessary.</p>
934         </li>
935
936         <li>
937           <p>Restart Tomcat, which will automatically detect that
938           there has been a new .war file added. This file will by
939           default be expanded into
940           <span class="fixedwidth">/usr/local/tomcat/webapps/shibboleth</span>.</p>
941         </li>
942
943         <li>
944           <p>Apache must be told to map the URL's for the
945           Shibboleth HS and AA to Tomcat. Two popular ways of doing
946           this are to include the following text directly in
947           <span class="fixedwidth">httpd.conf</span>, or to place <span class="fixedwidth">Include
948           conf/mod_jk.conf</span> in <span class="fixedwidth">httpd.conf</span>, and place
949           the following lines in
950           <span class="fixedwidth">/etc/httpd/conf/mod_jk.conf</span>:</p>
951
952           <blockquote>
953             <span class="fixedwidth">--------- begin ---------<br>
954             &lt;IfModule !mod_jk.c&gt;<br>
955             &nbsp;LoadModule jk_module libexec/mod_jk.so<br>
956             &lt;/IfModule&gt;<br>
957             <br>
958             JkWorkersFile
959             "/usr/local/tomcat/conf/jk/workers.properties"<br>
960             JkLogFile "/usr/local/apache/logs/mod_jk.log"<br>
961             <br>
962             JkLogLevel emerg<br>
963             <br>
964             JkMount /shibboleth/* ajp13<br>
965             <br>
966             --------- end ---------</span>
967           </blockquote>
968         </li>
969
970         <li>
971           <p>Tomcat's <span class="fixedwidth">/conf/server.xml</span>
972           ships by default with the Coyote/JK2 connector enabled, which
973           fails with Shibboleth due to the lack of support for <span
974           class="fixedwidth">REMOTE_USER</span>.  This connector must be
975           commented out.  Then, uncomment and modify the traditional AJP
976           1.3 connector as follows:</p>
977
978           <ol type="A">
979             <li>
980               <p>Add <span class="fixedwidth">address="127.0.0.1"</span> inside the
981               <span class="fixedwidth">&lt;Ajp13Connector&gt;</span> configuration
982               element to prevent off-host access.</p>
983             </li>
984
985             <li>
986               <p>Add <span class="fixedwidth">tomcatAuthentication="false"</span> to the
987               <span class="fixedwidth">&lt;Ajp13Connector&gt;</span> configuration element
988               to ensure that the user's identity is passed from
989               Apache to the servlet environment.</p>
990             </li>
991           </ol>
992         </li>
993       </ol>
994     </blockquote>
995     <br>
996     <hr>
997     <br>
998      
999
1000     <h3><a name="4."></a>4. Getting Running</h3>
1001
1002     <h4><a name="4.a."></a>4.a. Basic Configuration</h4>
1003
1004     <blockquote>
1005       <p>The main configuration file for Shibboleth's origin side is
1006       located in
1007       <span class="fixedwidth">/webapps/shibboleth/WEB-INF/classes/conf/origin.properties.</span>. This file contains configuration information
1008       for the origin side in several sections.  The configuration
1009       must be consistent with values elsewhere in the deployment,
1010       such as the <a href="#4.c.">HS' certificate</a> and with
1011       directory access bindings, etc., or access errors may occur.</p>
1012       
1013       <p>All pathnames are relative, and have an effective root
1014       path of
1015       <span class="fixedwidth">$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/</span>.  To
1016       specify files outside of the webapp, specify a full URI, such
1017       as <span class="fixedwidth">file:///usr/local/shibboleth/</span>.</p>
1018       
1019       <p>Fields that are purple are optional; grey fields are
1020       mandatory.</p>
1021
1022       
1023           <p>These are the variables that may be specified for each
1024       component of <span class="fixedwidth">origin.properties</span>:</p>
1025
1026       <br>
1027       <p>General Configuration:</p>
1028
1029       <dl>
1030           <dd class="attributelong">
1031               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.issuer
1032               = &lt;domain name&gt;</span>
1033           </dd>
1034
1035           <dd class="value">
1036               <p>Specifies the DNS name the HS should use for
1037               itself in issuing assertions.</p>
1038           </dd>
1039
1040           <dd class="attributelong">
1041               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName
1042               = &lt;URI&gt;</span>
1043           </dd>
1044
1045           <dd class="value">
1046               <p>Specifies the the <span
1047               class="fixedwidth">URI</span> to use as the name of
1048               the origin site as a whole.  This field is primarily
1049               meant to be populated in the context of the federation
1050               in which the origin site resides, is intended to be
1051               globally unique, and will typically be assigned by the
1052               federation.</p>
1053           </dd>
1054
1055           <dd class="attributelong">
1056               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl
1057               = &lt;url&gt;</span>
1058           </dd>
1059
1060           <dd class="value">
1061               <p>Specifies the <span class="fixedwidth">URL</span>
1062               at which the HS' corresponding AA may be
1063               contacted.</p>
1064           </dd>
1065
1066           <dd class="attributeoptlong">
1067               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.username
1068               = &lt;var&gt;</span>
1069           </dd>
1070
1071           <dd class="valueopt">
1072               <p>Specifies the HTTP request header that should be used
1073               to acquire the user's principal name from the
1074               authentication service.  Defaults to <span
1075               class="fixedwidth">REMOTE_USER</span>.</p>
1076           </dd>
1077
1078           <dd class="attributeoptlong">
1079               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.authMethod
1080               = &lt;uri&gt;</span>
1081           </dd>
1082
1083           <dd class="valueopt">
1084               <p>Specifes the URI used to populate <span
1085               class="fixedwidth">AuthenticationMethod</span> in the SAML
1086               attribute assertion.  This corresponds to the method used
1087               to authenticate users by the authentication service used
1088               by the HS.  Some common authentication methods and
1089               corresponding URI's are listed below; for a complete list,
1090               please consult section 7.1 of the SAML 1.1 core
1091               specifications or your federation's guidelines.</p>
1092               <table border=2 cellpadding=0 cellspacing=0>
1093                 <tr>
1094                   <td><span class="fixedwidth">urn:oasis:names:tc:SAML:1.0:am:password</span></td>
1095                   <td>The authentication was performed using a password.</td>
1096                 </tr>
1097                 <tr>
1098                   <td><span class="fixedwidth">urn:ietf:rfc:1510</span></td>
1099                   <td>The authentication was performed using Kerberos.</td>
1100                 </tr>
1101                 <tr>
1102                   <td><span class="fixedwidth">urn:oasis:names:tc:SAML:1.0:am:X509-PKI</span></td>
1103                   <td>The authentication was performed using a
1104                   certificate and key issued to the end user.  More
1105                   specific forms of PKI authentication such as SPKI and
1106                   XKMS are also assigned URN's in the SAML specs.</td>
1107                 </tr>
1108               </table>
1109           </dd>
1110       </dl>
1111
1112       <br>
1113       <p>Assertion Signing:</p>
1114
1115       <dl>
1116           <dd class="attributelong">
1117               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath
1118               = &lt;pathname&gt;</span>
1119           </dd>
1120
1121           <dd class="value">
1122               <p>Specifies the location of the Java keystore
1123               containing the x.509 certificate and matching private
1124               key to be used by the HS.</p>
1125           </dd>
1126
1127           <dd class="attributelong">
1128               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword
1129               = &lt;password&gt;</span>
1130           </dd>
1131
1132           <dd class="value">
1133               <p>Specifies the password to the referenced
1134               keystore.</p>
1135           </dd>
1136
1137           <dd class="attributelong">
1138               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias
1139               = &lt;alias&gt;</span>
1140           </dd>
1141
1142           <dd class="value">
1143               <p>Specifies the alias used for accessing the private
1144               key.</p>
1145           </dd>
1146
1147           <dd class="attributelong">
1148               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword
1149               = &lt;password&gt;</span>
1150           </dd>
1151
1152           <dd class="value">
1153               <p>Specifies the password used to retrieve the private key.</p>
1154           </dd>
1155
1156           <dd class="attributeoptlong">
1157               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias
1158               = &lt;alias&gt;</span>
1159           </dd>
1160
1161           <dd class="valueopt">
1162               <p>Specifies the alias for the certificate
1163               corresponding to the private key used by the HS. 
1164               Defaults to the private key's alias.</p>
1165           </dd>
1166       </dl>
1167       <br>
1168       
1169       <p>General AA Configuration:</p>
1170
1171       <dl>
1172           <dd class="attributelong">
1173               <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.AAServlet.authorityName
1174               = &lt;domain name&gt;</span>
1175           </dd>
1176
1177           <dd class="value">
1178               <p>Specifies the name of the AA, which is typically
1179               the domain name of the server running it.</p>
1180           </dd>
1181
1182           <dd class="attributelong">
1183               <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.AAServlet.passThruErrors
1184               = &lt;true/false&gt;</span>
1185           </dd>
1186
1187           <dd class="value">
1188               <p>Specifies whether the AA should pass on internal errors
1189               to the SHAR for debugging purposes.  Defaults to <span
1190               class="fixedwidth">false</span>.</p>
1191           </dd>
1192       </dl>
1193
1194       <p>AA Attribute Resolution:</p>
1195
1196         <dl>
1197           <dd class="attributelong">
1198               <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.attrresolv.AttributeResolver.ResolverConfig
1199               = &lt;pathname&gt;</span>
1200           </dd>
1201
1202           <dd class="value">
1203               <p>Specifies the location of the configuration file
1204               for the resolver the AA uses to build attributes. 
1205               Defaults to <span
1206               class="fixedwidth">/conf/resolver.xml</span>.  For
1207               information on how to configure and use the attribute
1208               resolver, consult section <a href="4.e.">4.e</a>.</p>
1209           </dd>
1210         </dl>
1211
1212       <p>ARP Configuration:</p>
1213
1214       <dl>
1215           <dd class="attributelong">
1216               <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.ArpRepository.implementation
1217               = &lt;string&gt;</span>
1218           </dd>
1219
1220           <dd class="value">
1221               <p>References the type of ARP repository implemented. 
1222               Shibboleth provides a built-in ARP repository
1223               specified by
1224               <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.
1225               provider.FileSystemArpRepository</span>.</p>
1226               
1227               <p>Note that the set of principals that an ARP applies
1228               to is not expressed by the ARP itself, but rather the
1229               implementation of the ARP repository.  For example, if
1230               the ARP repository were implemented in LDAP, the ARP's
1231               that apply to a user would be attributes of that
1232               user's personal LDAP entry, and the site ARP would be
1233               an attribute of an entry representing the site.  While
1234               not performed by the built-in ARP repository, a
1235               repository implementation might also implement group
1236               ARP's; for example, in an LDAP directory, the user
1237               entry might have some group membership attributes that
1238               refer to group entries, and those group entries would
1239               have ARP attributes, and all those ARP's would be
1240               applicable.</p>
1241           </dd>
1242
1243           <dd class="attributelong">
1244               <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path
1245               = &lt;pathname&gt;</span>
1246           </dd>
1247
1248           <dd class="value">
1249               <p>Specifies the relative or absolute path to the
1250               folder containing the ARP files.</p>
1251           </dd>
1252
1253           <dd class="attributeoptlong">
1254               <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.ArpTTL
1255               = &lt;seconds&gt;</span>
1256           </dd>
1257
1258           <dd class="valueopt">
1259               <p>Specifies the duration in <span
1260               class="fixedwidth">seconds</span> that ARP's may be
1261               cached by the AA.  Defaults to <span
1262               class="fixedwidth">0</span>, or no caching.</p>
1263           </dd>
1264       </dl>
1265     
1266       <p>Handle Repository Configuration:</p>
1267
1268       <dl>
1269           <dd class="attributeoptlong">
1270               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleRepository.implementation
1271               = &lt;string&gt;</span>
1272           </dd>
1273
1274           <dd class="valueopt">
1275               <p>Specifies the method by which the HS and AA share
1276               handles.  These are by default passed by memory(which
1277               can be specified explicitly using
1278               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.
1279               MemoryHandleRepository</span>), and may also be passed
1280               using symmetric encryption with
1281               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository</span>.</p>
1282           </dd>
1283       </dl>
1284
1285       <p>edu.internet2.middleware.shibboleth.hs.provider.
1286       MemoryHandleRepository <font color="#5555EE">(specify
1287       if
1288       <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleRepository.
1289       implementation</span> is <span class="fixedwidth">MemoryHandleRepository</span>)</font></p>
1290
1291       <blockquote>
1292         <dl>
1293             <dd class="attributeoptlong">
1294 <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.BaseHandleRepository.handleTTL
1295             = &lt;seconds&gt;</span>
1296             </dd>
1297
1298             <dd class="valueopt">
1299               <p>Specifies the time in <span
1300               class="fixedwidth">seconds</span> for which issued handles
1301               are valid.  Defaults to <span
1302               class="fixedwidth">1800</span>, or 30 minutes.  The time
1303               should be long enough to allow for clock skew and short
1304               enough to protect against various attacks.  Consult your
1305               federation guidelines for further advice.</p>
1306             </dd>
1307           </dl>
1308       </blockquote>
1309
1310       <p>edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository <font color="#5555EE">(specify
1311       if
1312       <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleRepository.
1313       implementation</span> is <span class="fixedwidth">CryptoHandleRepository</span>)</font></p>
1314
1315       <p>In order to use the crypto repository implementation, you must
1316       have a <span class="fixedwidth">DESede</span> secret key in a
1317       keystore of type <span class="fixedwidth">JCEKS</span>.  The
1318       origin distribution includes a program that will automatically
1319       generate such a key.  In order to invoke it, run <span
1320       class="fixedwidth">./ant genSecret</span>, which will create a
1321       keystore in <span
1322       class="fixedwidth">$SHIB_HOME/src/conf/handle.jks</span> that
1323       includes the key, with an alias of <span
1324       class="fixedwidth">handleKey</span> and a password of <span
1325       class="fixedwidth">shibhs</span>.  If <span
1326       class="fixedwidth">./ant dist</span> is run subsequently, this
1327       keystore will be included in the webapp archive that is
1328       created.</p>
1329
1330       <blockquote>
1331         <dl>
1332             <dd class="attributelong">
1333               <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePath
1334             = &lt;pathname&gt;</span>
1335             </dd>
1336
1337             <dd class="value">
1338               <p>Specifies the path to the keystore containing the
1339               key used to encrypt passed principal identifiers.</p>
1340             </dd>
1341   
1342             <dd class="attributelong">
1343 <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePassword 
1344             = &lt;password&gt;</span>
1345             </dd>
1346
1347             <dd class="value">
1348               <p>Specifies the password for the keystore.</p>
1349             </dd>
1350   
1351             <dd class="attributelong">
1352 <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyAlias
1353              = &lt;password&gt;</span>
1354             </dd>
1355
1356             <dd class="value">
1357               <p>Specifies the alias for the appropriate encryption
1358               key within the keystore.</p>
1359             </dd>
1360   
1361             <dd class="attributelong">
1362 <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyPassword
1363             = &lt;password&gt;</span>
1364             </dd>
1365
1366             <dd class="valueopt">
1367               <p>Specifies the password used to retrieve the key.</p>
1368             </dd>
1369   
1370             <dd class="attributeoptlong">
1371 <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.CryptoHandleRepository.handleTTL
1372             = &lt;seconds&gt;</span>
1373             </dd>
1374
1375             <dd class="valueopt">
1376               <p>Specifies the time in <span
1377               class="fixedwidth">seconds</span> for which issued handles
1378               are valid.  Defaults to <span
1379               class="fixedwidth">1800</span>, or 30 minutes.  The time
1380               should be long enough to allow for clock skew and short
1381               enough to protect against various attacks.  Consult your
1382               federation guidelines for further advice.</p>
1383             </dd>
1384   
1385         </dl>
1386       </blockquote>
1387
1388       <p>Federation Configuration:</p>
1389
1390         <dl>
1391           <dd class="attributelong">
1392               <span class="fixedwidth">edu.internet2.middleware.shibboleth.audiences
1393               = &lt;URI's&gt;</span>
1394           </dd>
1395
1396           <dd class="value">
1397               <p>Specifies a list of <span
1398               class="fixedwidth">URI</span>'s that will be used for
1399               the <span class="fixedwidth">Audience</span> field of
1400               the SAML attribute assertion.  All URI's listed will
1401               be sent with any assertion issued by the AA.  These
1402               URI's are defined and provided by and correspond to
1403               federations.</p>
1404
1405               <p>Note that the values of the URI's here <b>must</b>
1406               match one of the policy URI's accepted by the
1407               receiving target in the <span
1408               class="fixedwidth">[policies]</span> section of <span
1409               class="fixedwidth">shibboleth.ini</span> or
1410               interoperation will fail by design.
1411           </dd>
1412         </dl>
1413
1414     </blockquote>
1415     <br>
1416      
1417
1418     <h4><a name="4.b."></a>4.b. Key Generation and Certificate
1419     Installation</h4>
1420
1421     <blockquote>
1422       <p>The SAML messages generated by the HS must be digitally
1423       signed. Each HS must be issued a private and public keypair,
1424       which is stored in a Java keystore. The current
1425       implementation of Shibboleth requires the use of an ordinary
1426       file-based keystore. The keytool program is included with the
1427       Java development and runtime kits. Access parameters to the
1428       keystore will need to be consistent with those specified in
1429       <span class="fixedwidth">origin.properties</span>.</p>
1430
1431       <p>A sample keystore is included in the distribution and can
1432       be found in
1433       <span class="fixedwidth">/usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf/keystore
1434       .jks</span> with a password of <span class="fixedwidth">shibhs</span>.  It is intended
1435       to serve as an example and not as a production keystore.</p>
1436
1437       <p>The following commands will generate a new RSA keypair and
1438       store it in the <span class="fixedwidth">keystore.jks</span> file, with a keyentry
1439       alias of <span class="fixedwidth">hs</span> and new passwords of your choosing:</p>
1440
1441       <blockquote>
1442         <span class="fixedwidth">$ cd
1443         /usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf<br>
1444         $ keytool -storepasswd -keystore keystore.jks -new
1445         &lt;newpassword&gt;<br>
1446         $ keytool -genkey -keystore keystore.jks -alias hs -keyalg
1447         rsa -keysize 2048<br>
1448         </span>
1449       </blockquote>
1450
1451       <p>You will be prompted for passwords during key generation
1452       as needed, to access the keystore and assign the key itself
1453       its own password. You will also be prompted for the
1454       distinguished name components to associate with the key. This
1455       DN will be placed in a self-signed certificate and will be
1456       the name that is associated with your HS by Shibboleth. In
1457       particular, the first component you enter for Name will be
1458       the <span class="fixedwidth">Common Name</span>(when keytool asks for first and last
1459       name, common name is intended), which in most cases should be
1460       the hostname of the HS system. Note that a specific federation of
1461       sites may dictate what type of key algorithm, key size, or
1462       validity period is appropriate.</p>
1463
1464       <p>Once you have a keypair generated, the self-signed certificate
1465       must be replaced with a certificate signed by a CA acceptable to
1466       the federation you will be joining. Shibboleth is generally able to
1467       climb trust chains to reach an intermediate CA's root CA.  Note
1468       that the intermediate CA's signing certificate must still be
1469       signed by a root CA recognized by the federation.</p>
1470
1471       <p>To generate a certificate signing request for a CA, use
1472       the following command:</p>
1473
1474       <blockquote>
1475         <span class="fixedwidth">$ keytool -certreq -keystore keystore.jks -alias hs
1476         -file &lt;csr-file&gt;<br>
1477         </span>
1478       </blockquote>
1479
1480       <p>The contents of <span class="fixedwidth">&lt;csr-file&gt;</span> can then be sent
1481       to a CA for signing. You will receive a signed certificate in
1482       return in a file. To install the new certificate into your
1483       keystore, use the following command:</p>
1484
1485       <blockquote>
1486         <span class="fixedwidth">$ keytool -import -keystore keystore.jks -alias hs
1487         -file &lt;cert-file&gt;</span>
1488       </blockquote>
1489
1490       <p>Note that if the signing CA's certificate is not already
1491       installed in your keystore as a trusted signer, you may need
1492       to download the CA's root certificate and import it into the
1493       keystore file under a different alias, using a command
1494       similar to the above.</p>
1495
1496           <p>For information on sharing certificate/key pairs between Apache 
1497           and Java keystores see section <a href="#5.b.">5.b.</a>.</p>
1498     </blockquote>
1499
1500     <h4><a name="4.c."></a>4.c. Linking the Authentication System
1501     to the HS</h4>
1502
1503     <blockquote>
1504       <p>The interaction between the HS and the local authentication
1505       system is implemented by supplying the HS with the identity of
1506       the browser user. Most often, this will mean protecting the HS
1507       servlet with some form of local authentication that populates
1508       <span class="fixedwidth">REMOTE_USER</span>. Location blocks can be added to
1509       <span class="fixedwidth">httpd.conf</span>, associating the appropriate
1510       authentication mechanism with the URL of the HS servlet. The
1511       following example demonstrates association of a very basic
1512       authentication method with the HS:</p>
1513
1514       <blockquote>
1515         <span class="fixedwidth">&lt;Location /shibboleth/HS&gt;<br>
1516         AuthType Basic<br>
1517         AuthName "Internet2 Handle Service"<br>
1518         AuthUserFile /usr/local/apache/conf/user.db<br>
1519         require valid-user<br>
1520         &lt;/Location&gt;<br>
1521         </span>
1522       </blockquote>
1523
1524       <p>Note that .htaccess files cannot be used for this purpose
1525       because URL's are "virtualized" by Tomcat.</p>
1526
1527       <p>It is recommended that the origin be tested at the end of
1528       this process using the process described in section <a href=
1529       "#6.a.">6.a</a>.</p>
1530     </blockquote>
1531
1532     <h4><a name="4.c.i."></a>4.c.i. Enabling client certificate
1533     authentication <font color="#5555EE">(optional)</font></h4>
1534
1535     <blockquote>
1536       <blockquote>
1537
1538       <p>Shibboleth supports client certificate authentication by
1539       utilization of a filter that relies on the web server to do all
1540       processing to ensure that the certificate is both valid and
1541       appropriate for the application.  An example deployment descriptor
1542       is included with the Shibboleth distribution at <span
1543       class="fixedwidth">$SHIB_HOME/webAppConfig/origin-client-cert.xml</span>.
1544       To enable the filter, add the following to the deployment
1545       descriptor (<span class="fixedwidth">web.xml</span>):</p>
1546
1547       <blockquote>
1548         <span class="fixedwidth">&nbsp;&nbsp;&lt;filter&gt;<br>
1549         &nbsp;&nbsp;&nbsp;&nbsp;&lt;filter-name&gt;<br>
1550         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Client Cert AuthN Filter<br>
1551         &nbsp;&nbsp;&nbsp;&nbsp;&lt;/filter-name&gt;<br>
1552         &nbsp;&nbsp;&nbsp;&nbsp;&lt;filter-class&gt;<br>
1553         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;edu.internet2.middleware.shibboleth.utils.ClientCertTrustFilter<br>
1554         &nbsp;&nbsp;&nbsp;&nbsp;&lt;/filter-class&gt;<br>
1555         &nbsp;&nbsp;&lt;/filter&gt;<br>
1556         <br>
1557         <br>
1558         &nbsp;&nbsp;&lt;filter-mapping&gt;<br>
1559         &nbsp;&nbsp;&nbsp;&nbsp;&lt;filter-name&gt;<br>
1560         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Client Cert AuthN Filter<br>
1561         &nbsp;&nbsp;&nbsp;&nbsp;&lt;/filter-name&gt;<br>
1562         &nbsp;&nbsp;&nbsp;&nbsp;&lt;url-pattern&gt;<br>
1563         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/HS<br>
1564         &nbsp;&nbsp;&nbsp;&nbsp;&lt;/url-pattern&gt;<br>
1565         &nbsp;&nbsp;&lt;/filter-mapping&gt;<br></span>
1566      </blockquote>
1567
1568      <p>By default, the filter pulls the principal name out of the <span
1569      class="fixedwidth">CN</span> of the cert's <span
1570      class="fixedwidth">Subject</span> by using regular expression
1571      grouping.  This may be done using patterns such as:</p>
1572
1573      <blockquote>
1574        <span class="fixedwidth">regex: '.*CN=([^,/]+).*' match group: 1</span>
1575      </blockquote>
1576
1577      <p>The servlet filter will accept two initialization parameters,
1578      <span class="fixedwidth">regex</span> and <span
1579      class="fixedwidth">matchGroup</span> that can be used to extract
1580      the principal name differently.</p>
1581
1582       </blockquote>
1583     </blockquote>
1584
1585     <h4><a name="4.d."></a>4.d. Establishing default ARP's for the
1586     origin community</h4>
1587     
1588     <p><b>For a more basic introduction to ARP's, please refer to
1589     section <a href="#2.e.">2.e</a>.</b></p>
1590
1591     <blockquote>
1592       <p>An ARP determines which attributes are released to a SHAR
1593       when a user tries to access a resource.  It acts as a sort of
1594       filter on user information contained in the authoritative
1595       directory, deciding what can be released to whom, but not
1596       modifying or creating information itself.  ARP's are generally
1597       administered by the site, but Shibboleth will provide for users to
1598       broker control of their own information and privacy by
1599       allowing them to create ARP's pertaining to themselves.</p>
1600
1601       <p>It is recommended that a set of policies be established
1602       between an origin and frequently accessed targets to specify
1603       default releases of expected attributes.  Federation guidelines may
1604       provide more information on population of ARP's.</p>
1605
1606       <p>Currently, there is no direct mechanism for users to create
1607       their own ARP's besides direct XML writing.  In future
1608       versions, a GUI will be provided for simpler management of
1609       ARP's.  Care should be given to balancing giving sufficient
1610       control over information to users and avoiding access
1611       problems.  For example, users may decide to restrict the
1612       release of their personal information to such a degree that
1613       access to a site for a class may become impossible because
1614       Shibboleth cannot release enough information to grant
1615       access.</p>
1616
1617           <p>The Shibboleth distribution contains an example site arp that 
1618           releases the eduPersonScopedAffiliation attribute to all targets.  For 
1619           more precise information regarding how ARP's are processed or 
1620           syntactically formed, please refer to section <a href="#5.a.i.">5.a.i</a>.</p>
1621     </blockquote>
1622
1623         <h4><a name="4.e."></a>4.e. Modifying the default Attribute Resolver configuration</h4>
1624         <blockquote>
1625         <p>The resolver.xml file controls the retrieval of attributes from enterprise repositories, and the process of mapping them to Shibboleth/SAML attributes. For more precise information regarding how attributes are processed or syntactically formed, please refer to section <a href="#5.c.">5.c.</a></p>
1626
1627         <p>In order to make the Shibboleth software operational, however, minor edits must be made to the example version of the resolver.xml file. The file can be found at <span class="fixedwidth">/webapps/shibboleth/WEB-INF/classes/conf/resolver.xml.</span>  Two changes are necessary:</p>
1628
1629         <p>     1. The value of the smartScope attribute should be changed to the Domain Name value submitted to the Federation. It appears on two SimpleAttributeDefinition elements: eduPersonScopedAffiliation and eduPersonPrincipalName.</p>
1630
1631         <p>2. The comment indicators should be removed from around the definitions of those two elements ( &lt;!-- and --&gt; ).</p> 
1632         </blockquote>
1633     <br>
1634     <hr>
1635     <br>
1636
1637     <h3><a name="5."></a>5. Advanced Configuration</h3>
1638
1639     <h4><a name="5.a."></a>5.a. ARP Overview</h4>
1640
1641     <blockquote>
1642       <h5>This section applies primarily to the syntactic and
1643       technical details of ARP's. For basic information on and
1644       explanation of what an ARP is and how it should be managed,
1645       please refer to sections <a href="#2.e.">2.e</a> and <a href=
1646       "#4.d.">4.d</a>.</h5>
1647
1648       <p>Every ARP file contains one ARP.  ARP's may be specified either
1649       as the site ARP or user ARP's.  The site ARP pertains to every
1650       principal for whom the AA retrieves information; a user ARP
1651       applies only to the individual user for whom it is defined.  The
1652       set of principals to whom the ARP applies is defined by the name
1653       of the ARP file: the site ARP is stored in <span
1654       class="fixedwidth">arp.site.xml</span> and user ARP's are stored as
1655       <span class="fixedwidth">arp.user.$PRINCIPALNAME.xml</span>.
1656       Up to two ARP's will apply to a principal: the site ARP, and the
1657       user ARP for that principal.</p>
1658
1659       <p>Each ARP acts as a container that holds a set of ARP rules
1660       that are applicable to the principals that ARP is effective
1661       for.  Each ARP rule specifies a single release policy within
1662       the ARP container pertaining to a specific set of targets.
1663       This set of targets may be specified as a specific SHAR, a
1664       SHAR tree, or a regular expression, and becomes the ARP rule's
1665       target definition. Each ARP rule may contain specifications
1666       regarding the release of any number of attribute values to
1667       requests matching that ARP rule for that user. ARP rules may
1668       be flagged as default, implying that they are always applied
1669       to any user matched by the ARP container.  Note that ARP's may
1670       also be used to restrict specific attribute/value pairs in
1671       addition to restricting or releasing individual attributes.</p>
1672
1673       <p>When a query is received, the AA generates an effective
1674       ARP, which is the fully evaluated set of ARP rules regarding
1675       that SHAR based on all ARP containers applicable to the
1676       principal.  This effective ARP is then applied to attribute
1677       values retrieved from the directory and the appropriate
1678       assertion is constructed.  Default rules are always
1679       included in construction of the effective ARP.</p>
1680
1681       <!-- ##To be included in future releases of the deploy guide.
1682   
1683       <dl>
1684           <dd class="demo">
1685             <img src="arp.gif">
1686           </dd>
1687           <dd class="demo">
1688             <p>In this picture, meant to demonstrate the structure
1689             of ARP's, if all ARP's are taken to mean "Release this
1690             attribute," then attributes 1-4 will be released if that
1691             principal tries to access site A.  ARP #1 could not
1692             restrict the release of attribute 4 to site A.</p>
1693           </dd>
1694       </dl>
1695
1696       -->
1697
1698     </blockquote>
1699
1700     <h4><a name="5.a.i."></a>5.a.i. ARP Processing</h4>
1701
1702     <blockquote>
1703       <blockquote>
1704         <p>When a request arrives from a particular SHAR, the
1705         applicable set of ARP rules are parsed into an effective
1706         ARP.  This parsing is done as follows:</p>
1707         
1708         <ol type=1>
1709           <li>Identify all ARP's that should be applied to a particular
1710           principal.  This is done by isolating the files in the folder
1711           specified by <span
1712           class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path</span> that have the
1713           name either arp.site.xml or arp.user.$PRINCIPALNAME.xml.</li>
1714           <li>Find all ARP rules relevant to the query:
1715           <ol type=i>
1716             <li>Any ARP rules within the identified ARP's designated
1717             as defaults are automatically included in the effective
1718             ARP without performing any matching functions.</li>
1719             <li>For each non-default rule in each identified ARP,
1720             the matching functions specified in the rule's target
1721             definition are performed. A separate matching function
1722             is performed for the requesting SHAR and the resource on
1723             behalf of which the SHAR is making the request.</li>
1724             <li>Each matching function evaluates to <span class="fixedwidth">TRUE</span> if
1725             the match is successful or <span class="fixedwidth">FALSE</span> if it is
1726             unsuccessful. If both functions evaluate to
1727             <span class="fixedwidth">TRUE</span>, the rule is included in the Effective
1728             ARP.</li>
1729           </ol></li>
1730           <li>Construct the Attribute Filter:
1731           <ol type=i>
1732             <li>For each attribute, compile a temporary list of
1733             associated rules that includes all values with a release
1734             qualifier of <span class="fixedwidth">permit</span>.</li>
1735             <li>Subtract from this list all attribute values with
1736             rules specifying a release qualifier of <span class="fixedwidth">deny</span>.
1737             The resulting list represents the allowable release
1738             values for the attribute and is used as a mask for the
1739             values which are returned from the Attribute
1740             Resolver.</li>
1741             <li>If a statement specifies that all values should be
1742             permitted, then specific <span class="fixedwidth">deny</span> qualifiers for
1743             specific values should still be enforced.  If a
1744             statement specifies that all values should be denied,
1745             then <span class="fixedwidth">permit</span> qualifiers for specific values will
1746             be ignored.</li>
1747           </ol></li>
1748           <li>Using the mask and attributes returned from the
1749           Attribute Resolver, an assertion is constructed.</li>
1750         </ol>
1751       </blockquote>
1752     </blockquote>
1753     
1754
1755     <h4><a name="5.a.ii."></a>5.a.ii. ARP Syntax</h4>
1756
1757     <blockquote>
1758       <blockquote>
1759
1760       <p>Each ARP is described by an XML file based on a standard
1761       <span class="fixedwidth">.xsd</span> schema.  It consists of a standard
1762       <span class="fixedwidth">AttributeReleasePolicy</span> element referencing the
1763       appropriate <span class="fixedwidth">xsi:schemaLocation</span> and a self-explanatory
1764       <span class="fixedwidth">Description</span> element followed by any number of
1765       <span class="fixedwidth">Rule</span> elements.  Each <span class="fixedwidth">Rule</span> element must
1766       consist of a <span class="fixedwidth">Target</span> element and one or more
1767       <span class="fixedwidth">Attribute</span> elements.  The <span class="fixedwidth">Target</span> element
1768       specifies the rules by which the target definition is formed. 
1769       The <span class="fixedwidth">Attribute</span> elements specifies the name and values
1770       of the attributes that may be released.</p>
1771
1772       <p>The simplest possible ARP is as follows, which releases
1773       <span class="fixedwidth">eduPersonScopedAffiliation</span> to any target for the
1774       users the ARP applies to:</p>
1775
1776         <blockquote>
1777           <span class="fixedwidth">
1778           &lt;?xml version=&quot;1.0&quot;?&gt;<br>
1779           
1780           &lt;AttributeReleasePolicy
1781           xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
1782           xmlns=&quot;urn:mace:shibboleth:arp:1.0&quot;
1783           xsi:schemaLocation=&quot;urn:mace:shibboleth:arp:1.0
1784           shibboleth-arp-1.0.xsd&quot;&gt;<br>
1785           
1786           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;
1787           &lt;Description&gt;Simplest possible
1788           ARP.&lt;/Description&gt;<br>
1789
1790           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;
1791           &lt;Rule&gt;<br>
1792
1793           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1794           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;Target&gt;<br>
1795
1796           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1797           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1798           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;AnyTarget/&gt;<br>
1799
1800           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1801           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/Target&gt;<br>
1802
1803           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1804           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;Attribute
1805           name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;&gt;<br>
1806
1807           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1808           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1809           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;AnyValue release=
1810           &quot;permit&quot;/&gt;<br>
1811
1812           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1813           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/Attribute
1814           &gt;<br>
1815
1816           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/Rule
1817           &gt;<br>
1818
1819           &lt;/AttributeReleasePolicy&gt;<br>
1820
1821           </span>
1822         </blockquote>
1823       </blockquote>
1824
1825       <p>All ARP's must take the same basic form.  A detailed
1826       description of how each element of the <span class="fixedwidth">Rule</span> element
1827       may be sub-populated follows:</p>
1828
1829       <p>The <span class="fixedwidth">Target</span> element:</p>
1830       
1831       <blockquote>
1832       
1833         <p><span class="fixedwidth">Target</span> may contain either the
1834         <span class="fixedwidth">AnyTarget</span> element, which will cause the
1835         <span class="fixedwidth">Target</span> to always return <span class="fixedwidth">TRUE</span>, or both the
1836         <span class="fixedwidth">Requester</span> element, which provides for matches to be
1837         performed against the SHAR name and the <span class="fixedwidth">Resource</span>
1838         element, which provides for matches to be performed against
1839         the requested URL.</p>    
1840       
1841         <p>There are three matches that may be performed by the AA
1842         in evaluating ARP's by using the <span class="fixedwidth">matchFunction</span>
1843         component of the <span class="fixedwidth">Requester</span> and <span class="fixedwidth">Resource</span>
1844         elements.  The following match patterns may be
1845         specified directly following the <span class="fixedwidth">Requester</span> or
1846         <span class="fixedwidth">Resource</span> elements, such as <span class="fixedwidth">&lt;Requester
1847         matchFunction=&quot;urn:mace:shibboleth:arp:matchFunction:regexMatch&quot;&gt;</span>:</p>
1848
1849         <ul type=disc>
1850           <li>
1851             <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:exactShar
1852             </span></p>
1853             <blockquote>
1854               <p>May be used with the <span class="fixedwidth">Requester</span>
1855               element.</p>
1856               
1857               <p>Evaluates to <span class="fixedwidth">TRUE</span> when the string content
1858               of the <span class="fixedwidth">Requester</span> element matches exactly the
1859               name of the requesting SHAR. Otherwise evaluates to
1860               <span class="fixedwidth">FALSE</span>.  Serves as the default value
1861               associated with <span class="fixedwidth">Requester</span> if none is
1862               specified.</p>
1863             </blockquote>
1864           </li>
1865           <li>
1866             <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:resourceTree
1867             </span></p>
1868             <blockquote>
1869               <p>May be used with the <span class="fixedwidth">Resource</span> element.</p>
1870
1871               <p>Evaluates to <span class="fixedwidth">TRUE</span> when the location of 
1872               the resource either matches exactly or begins with
1873               the string content of the <span class="fixedwidth">Resource</span> element.
1874               Otherwise evaluates to <span class="fixedwidth">FALSE</span>.</p>
1875             </blockquote>
1876           </li>
1877           <li>
1878             <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:regexMatch
1879             </span></p>
1880             <blockquote>
1881               <p>May be used with both the <span class="fixedwidth">Requester</span>
1882               and <span class="fixedwidth">Resource</span> elements.</p>
1883
1884               <p>Evaluates to <span class="fixedwidth">TRUE</span> when the name of the
1885               requesting SHAR or the requested URL tree is a valid
1886               match of the regular expression represented as the
1887               content of the containing element. Otherwise evaluates
1888               to <span class="fixedwidth">FALSE</span>. Regular expressions are evaluated in
1889               accordance with the the <a
1890               href="http://java.sun.com/j2se/1.4/docs/api/java/util/
1891               regex/Pattern.html#sum">Java 1.4 Pattern API</a>.</p>
1892             </blockquote>
1893           </li>
1894         </ul>
1895       
1896     </blockquote>
1897
1898       <p>The <span class="fixedwidth">Attribute</span> element:</p>
1899       
1900       <blockquote>
1901       
1902         <p>The <span class="fixedwidth">Attribute</span> element must always specify the
1903         URN of the attribute whose release parameters it specifies.
1904         Additionally, it must contain either the <span class="fixedwidth">AnyValue</span>
1905         element or one or more <span class="fixedwidth">Value</span> elements.  These
1906         elements, in turn, must specify either <span class="fixedwidth">release</span> =
1907         <span class="fixedwidth">permit</span> or <span class="fixedwidth">deny</span>.  The <span class="fixedwidth">Value</span>
1908         element must then contain one value for which the rule
1909         applies.  Examples:</p>
1910
1911         <blockquote>
1912           <span class="fixedwidth">
1913           &lt;Attribute name=&quot;urn:mace:dir:attribute-def:eduPersonPrincipalName&quot;&gt;<br>
1914           &nbsp;&nbsp;&lt;AnyValue release=&quot;Permit&quot;&gt;<br>
1915           &lt;/Attribute&gt;<br>
1916           </span><br>
1917           <p>Permits the release of <span class="fixedwidth">eduPersonPrincipalName</span>
1918           with any value.</p>
1919         </blockquote>
1920          
1921         <blockquote>
1922           <span class="fixedwidth">
1923           &lt;Attribute name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;&gt;<br>
1924           &nbsp;&nbsp;&lt;Value release=&quot;deny&quot;&gt;member@example.edu&lt;/Value&gt;<br>
1925           &lt;/Attribute&gt;<br>
1926           </span><br>
1927           <p>Denies the release of
1928           <span class="fixedwidth">eduPersonScopedAffiliation</span> value
1929           <span class="fixedwidth">member@example.edu</span>.  Other values of the
1930           attribute may still be released if so specified by a
1931           <span class="fixedwidth">permit</span> ARP.</p>
1932         </blockquote>
1933       </blockquote> 
1934       
1935       <!-- ##To be included in future releases.  Not yet implemented.
1936       
1937       <p>There is also a special <span class="fixedwidth">AttributeIdentifier</span>
1938       element that allows internal references to an attribute
1939       within an ARP.  This is useful for quickly applying multiple
1940       rules to the same target.  It is used as follows:</p>
1941
1942         <blockquote>
1943           <span class="fixedwidth">
1944           &nbsp;&nbsp;&lt;Rule&gt;<br>
1945           
1946           &nbsp;&nbsp;&nbsp;&nbsp;&lt;Target&gt;<br>
1947           
1948           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;AnyTarget/&gt;<br>
1949           
1950           &nbsp;&nbsp;&nbsp;&nbsp;&lt;/Target&gt;<br>
1951           
1952           &nbsp;&nbsp;&nbsp;&nbsp;&lt;Attribute
1953           name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;&gt;<br>
1954
1955           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;Value
1956           release=&quot;permit&quot;&gt;member@example.edu&lt;/Value
1957           &gt;<br>
1958
1959           &nbsp;&nbsp;&nbsp;&nbsp;&lt;/Attribute&gt;<br>
1960           
1961           &nbsp;&nbsp;&lt;/Rule&gt;<br>
1962           
1963           &nbsp;&nbsp;&lt;AttributeReference identifier=&quot;http://www.example.edu/attributes/attribute1&quot;&gt;<br>
1964
1965           &nbsp;&nbsp;&lt;Attribute name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot; identifier=&quot;http://www.example.edu/attributes/attribute1&quot;&gt;<br>
1966
1967           &nbsp;&nbsp;&nbsp;&nbsp;&lt;Value release=&quot;permit&quot;&gt;student@example.edu&lt;Value&gt;<br>
1968
1969           &nbsp;&nbsp;&lt;/Attribute&gt;<br>
1970           </span>
1971       -->
1972       
1973         </blockquote>
1974     <h4><a name="5.b."></a>5.b. Sharing certificate/key pairs
1975     between Apache and Java keystores <font color="#5555EE">(optional)</font></h4>
1976
1977     <blockquote>
1978       <blockquote>
1979         <p>The JDK includes the command line program
1980         <span class="fixedwidth">keytool</span> for managing Java keystores. This utility
1981         cannot import or export private key information, making it
1982         difficult to use the same private key and certificate for
1983         Apache and Java-based applications. The Shibboleth
1984         distribution includes <span class="fixedwidth">extkeytool</span>, a program that
1985         can be used in conjunction with <span class="fixedwidth">keytool</span> to perform
1986         these tasks. Select the appropriate step-by-step procedure
1987         for your situation from the following guides.</p>
1988         
1989         <p>Before running <span class="fixedwidth">extkeytool</span>, the variable
1990         SHIB_HOME must be set to the path to the directory where the
1991         Shibboleth tarball was exploded(typically
1992         /usr/local/shibboleth-origin-1.0/).</p>
1993
1994         <p><b>If you have a pre-exiting RSA key/certificate
1995         combination in a keystore and you would like to use it with
1996         Apache:</b></p>
1997
1998         <ol type="1">
1999           <li>
2000             <p>Determine the alias of the keystore keyEntry
2001             containing the key you would like to use in your Apache
2002             setup. Assuming that your keystore is named
2003             <span class="fixedwidth">yourstore</span>, the following command should
2004             present a list of the entries in the keystore.</p>
2005
2006             <blockquote>
2007               <p><span class="fixedwidth">$ keytool -list -v -keystore
2008               yourstore</span></p>
2009             </blockquote>
2010           </li>
2011
2012           <li>
2013             <p>Assuming that you identified the appropriate alias
2014             as <span class="fixedwidth">youralias</span> and the password for the keystore
2015             is <span class="fixedwidth">yourpass</span>, enter the following command to
2016             export the key in Base64-encoded pkcs8 format.</p>
2017
2018             <blockquote>
2019               <p><span class="fixedwidth">$ extkeytool -exportkey -keystore yourstore
2020               -alias youralias -storepass yourpass -rfc -file
2021               yourkey.pkcs8</span></p>
2022             </blockquote>
2023           </li>
2024
2025           <li>
2026             <p>In order to use this key with Apache, you must
2027             convert it to PEM-encoded RSA native format. You have
2028             the option of storing the key unencrypted or
2029             encrypted:</p>
2030
2031             <ol type="A">
2032               <li>
2033                 <p>To use the unencrypted format, enter the
2034                 following command for the conversion:</p>
2035
2036                 <blockquote>
2037                   <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.pkcs8
2038                   -nocrypt|openssl rsa -out yourkey.key</span></p>
2039                 </blockquote>
2040               </li>
2041
2042               <li>
2043                 <p>To use the encrypted format, enter the following
2044                 command for the conversion:</p>
2045
2046                 <blockquote>
2047                   <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.pkcs8
2048                   -nocrypt|openssl rsa -des3 -out
2049                   yourkey.enckey</span></p>
2050                 </blockquote>
2051               </li>
2052             </ol>
2053           </li>
2054
2055           <li>
2056             <p>The following command will export the corresponding
2057             certificate.</p>
2058
2059             <blockquote>
2060               <p><span class="fixedwidth">$ keytool -export -keystore yourstore -alias
2061               youralias -rfc -file yourcert</span></p>
2062             </blockquote>
2063           </li>
2064
2065           <li>
2066             <p>Set the <span class="fixedwidth">mod_ssl</span>
2067             <span class="fixedwidth">SSLCertificateKeyFile</span> and
2068             <span class="fixedwidth">SSLCertificateFile</span> directives to point to the
2069             two files you have just created. Take care to remove
2070             any temporary files you created (i.e.
2071             <span class="fixedwidth">yourkey.pkcs8</span>) and set appropriate file
2072             permissions, especially if you chose to store the key
2073             in an unencrypted format.</p>
2074           </li>
2075         </ol>
2076
2077         <p><b>If you have a pre-existing RSA key/certificate
2078         combination that you use with Apache and would like to
2079         import it into a java keystore:</b></p>
2080
2081         <ol type="1">
2082           <li>
2083             <p>Convert the private key to unencrypted DER-encoded
2084             pkcs8 format. Assuming your PEM-encoded key is stored
2085             in a file named <span class="fixedwidth">yourkey.enckey</span>, enter the
2086             following command.</p>
2087
2088             <blockquote>
2089               <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.enckey -topk8
2090               -nocrypt -outform DER -out yourkey.der.pkcs8</span></p>
2091             </blockquote>
2092           </li>
2093
2094           <li>
2095             <p>Create a certificate bundle file. This file should
2096             include a series of PEM-encoded X509 certificates
2097             representing a complete trust chain, from the root CA
2098             certificate to the certificate that matches your
2099             private key. If your certificate is stored in a file
2100             named <span class="fixedwidth">mycert</span> and the CA signer certificate is
2101             stored in a file named <span class="fixedwidth">ca.cert</span>, you might
2102             enter the following command to create the bundle.</p>
2103
2104             <blockquote>
2105               <p><span class="fixedwidth">$ cat mycert ca.cert &gt; cert.bundle</span></p>
2106             </blockquote>
2107
2108             <b>Note: <span class="fixedwidth">mod_ssl</span>-enabled Apache
2109             installations include a number of commonly recognized
2110             CA certificates in the <span class="fixedwidth">ca-bundle.crt</span> file
2111             under the <span class="fixedwidth">$ServerRoot/conf/ssl.crt/</span>
2112             directory.</b>
2113           </li>
2114
2115           <li>
2116             <p>Import the key and certificate into the keystore.
2117             Assuming you have already created a keystore named
2118             <span class="fixedwidth">yourstore</span> with a password of of
2119             <span class="fixedwidth">yourpass</span>, enter the following command to store
2120             the data under the alias <span class="fixedwidth">youralias</span>.</p>
2121
2122             <blockquote>
2123               <p><span class="fixedwidth">$ ./extkeytool -importkey -keystore yourstore
2124               -alias youralias -storepass yourpass -keyfile
2125               yourkey.der.pkcs8 -certfile cert.bundle -provider
2126               org.bouncycastle.jce.provider.BouncyCastleProvider</span></p>
2127             </blockquote>
2128           </li>
2129
2130           <li>
2131             <p>You can verify that the import was successful by
2132             listing entry. Use the command below.</p>
2133
2134             <blockquote>
2135               <p><span class="fixedwidth">$ keytool -list -v -keystore yourstore -alias
2136               youralias</span></p>
2137             </blockquote>
2138           </li>
2139
2140           <li>
2141             <p>Remember to delete <span class="fixedwidth">yourkey.der.pkcs8</span>, as it
2142             contains your unencrypted private key.</p>
2143           </li>
2144         </ol>
2145
2146         <p><b>If you are starting from scratch and do not yet have
2147         a certificate/key pair:</b></p>
2148
2149         <ol type="1">
2150           <li>
2151             <p>Generate an RSA private key. Use the command below,
2152             substituting <span class="fixedwidth">yourkey</span> with an appropriate name
2153             to use to refer to the key.</p>
2154
2155             <blockquote>
2156               <p><span class="fixedwidth">$ openssl genrsa -des3 -out yourkey.enckey
2157               1024</span></p>
2158             </blockquote>
2159           </li>
2160
2161           <li>
2162             <p>The following command generates a Certificate
2163             Signing Request, which should be communicated to a
2164             Certificate Authority.</p>
2165
2166             <blockquote>
2167               <p><span class="fixedwidth">$ openssl req -new -key
2168               yourkey.enckey</span></p>
2169             </blockquote>
2170           </li>
2171
2172           <li>
2173             <p>The Certificate Authority should respond with a
2174             PEM-encoded X509 certificate. Set the <span class="fixedwidth">mod_ssl</span>
2175             <span class="fixedwidth">SSLCertificateKeyFile</span> directive to point to
2176             the key file you just created and the
2177             <span class="fixedwidth">SSLCertificateFile</span> directive to point to file
2178             containing the certificate issued by the Certificate
2179             Authority. Previous sections explaion how to share the
2180             key/certificate pair with a Java keystore.</p>
2181           </li>
2182         </ol>
2183       </blockquote>
2184     </blockquote>
2185
2186     <br>
2187     <h4><a name="5.c."></a>5.c. The Attribute Resolver</h4>
2188
2189     <blockquote>
2190       <p>Shibboleth provides a powerful attribute resolver that allows
2191       origins to quickly configure the retrieval of simple attributes
2192       from standard types of attribute stores.  The resolver is configured
2193       using an xml file wich should be pointed to with the <span
2194       class="fixedwidth">edu.internet2.middleware.shibboleth.aa.
2195       attrresolv.AttributeResolver.ResolverConfig</span> propety in <span
2196       class="fixedwidth">origin.properties</span> as described in
2197       section <a href="#4.a.">4.a</a>.  For more complex attributes or
2198       those that require processing before release, customized Java
2199       classes will need to be written.  For more information,
2200       consult the programmer's guide.</p>
2201
2202       <p>The resolver is essentially a directed graph from attribute
2203       definitions to data connectors. The data connectors pull data, in
2204       the form of attributes, from external data sources.  The attribute
2205       definitions then process this data into a from suitable for use
2206       by Shibboleth.  This procedure can be as simple as taking an
2207       unmodified string value from a data connector and tagging it with
2208       a name or can include arbitrarily complex business rules.</p>
2209
2210       <p>The <span class="fixedwidth">resolver.xml</span> file that is
2211       pointed to by <span class="fixedwidth">origin.properties</span>
2212       consists of zero or more attribute definitions followed by zero or
2213       more data connectors.  Each attribute definition consists of an
2214           identifier corresponding to the URN of the attribute, and optional 
2215           references to data connectors on which it depends.  Each data connector
2216       consists of a string identifier which is used by attribute
2217       definitions that refer to it, and one or more elements specific to
2218       the configuration of that data connector.</p>
2219
2220       <p>Shibboleth comes with two attribute definitions provided in
2221       version 1.0: the <span
2222       class="fixedwidth">SimpleAttributeDefinition</span>, which acts as
2223       a basic proxy for attributes supplied by data connectors with some
2224       name conversion and attribute scoping added, and a <span
2225       class="fixedwidth">CustomAttributeDefinition</span>, which can be
2226       used to configure user-created attribute definition plugins.
2227       Similarly, Shibboleth 1.0 comes with two data connectors: the
2228       <span class="fixedwidth">JNDIDirectoryDataConnector</span>, which
2229       pulls data from any source for which there is a JNDI Directory
2230       Context implementation, including LDAP, NDS, etc., and the <span
2231       class="fixedwidth">CustomDataConnector</span>, which is used to
2232       configure user-created data connector plugins.</p>
2233
2234       <p>A detailed explanation of each configuration option for the
2235       provided connectors follows:</p>
2236       
2237       <p><span class="fixedwidth">JNDIDirectoryDataConnector</span>:</p>
2238
2239       <dl>
2240         <dd class="attribute">
2241           <span class="fixedwidth">id = &lt;string&gt;</span>
2242         </dd>
2243
2244         <dd class="value">
2245           <p>Specifies a unique, textual name for the connector used by
2246           attribute definitions to refer to and use it to build
2247           attributes.  Contained within the <span
2248           class="fixedwidth">JNDIDirectoryDataConnector</span>
2249           element.</p>
2250         </dd>
2251
2252         <dd class="attribute">
2253           <span class="fixedwidth">&lt;Property name=&quot;&lt;name&gt;&quot; value=&quot;&lt;value&gt;&quot;/&gt;</span>
2254         </dd>
2255
2256         <dd class="value">
2257           <p>An element of the element <span
2258           class="fixedwidth">JNDIDirectoryDataConnector</span>. 
2259           Specifies a set of name/value pairs that are used to configure
2260           the JNDI Directory Context.  This list of name/value pairs is
2261           defined by the context itself, but is specified within <span
2262           class="fixedwidth">resolver.xml</span>.  Refer to the <a
2263           href="http://http://marsalis.internet2.edu/cgi-bin/viewcvs.cgi
2264           /shibboleth/java/src/conf/resolver.ldap.xml">Shibboleth
2265           CVS</a> for an example of names and values used to connect to
2266           an LDAP directory.</p>
2267         </dd>
2268
2269         <dd class="attributeopt">
2270           <span class="fixedwidth">&lt;Search&gt;</span>
2271         </dd>
2272
2273         <dd class="valueopt">
2274           <p>An element of the element <span
2275           class="fixedwidth">JNDIDirectoryDataConnector</span>.  This
2276           element defines the DN filter used to perform the LDAP search.
2277            The search string must return no more than one result.</p>
2278         </dd>
2279
2280         <dd class="attributeopt">
2281           <span class="fixedwidth">&lt;Controls&gt;</span>
2282         </dd>
2283
2284         <dd class="valueopt">
2285           <p>An element of the element <span
2286           class="fixedwidth">Search</span>.  This
2287           element grants some fine-grained control over the LDAP API
2288           calls.</p>
2289         </dd>
2290
2291         <dd class="attributeopt">
2292           <span class="fixedwidth">&lt;cacheTime &quot;&lt;seconds&gt;&quot;/&gt;</span>
2293         </dd>
2294
2295         <dd class="valueopt">
2296           <p>An element of the element <span
2297           class="fixedwidth">JNDIDirectoryDataConnector</span>. 
2298           Specifies an optional duration in <span
2299           class="fixedwidth">seconds</span> for which the attribute
2300           resolver may cache information retrieved from this
2301           connector.</p>
2302         </dd>
2303       </dl>
2304
2305       <p>A representation of a properly constructed <span
2306       class="fixedwidth">JNDIDirectoryDataConnector</span> element would
2307       look like:</p>
2308
2309       <blockquote><span class="fixedwidth">
2310         &lt;JNDIDirectoryDataConnector id=&quot;directory&quot;&gt;<br>
2311           &nbsp;&nbsp;&lt;Search filter=&quot;cn=%PRINCIPAL%&quot;&gt;<br>
2312             &nbsp;&nbsp;&nbsp;&nbsp;&lt;Controls searchScope=&quot;SUBTREE_SCOPE&quot; returningObjects=&quot;false&quot; /&gt;<br>
2313           &nbsp;&nbsp;&lt;/Search&gt;<br>
2314           &nbsp;&nbsp;&lt;Property name=&quot;java.naming.factory.initial&quot; value=&quot;com.sun.jndi.ldap.LdapCtxFactory&quot; /&gt;<br>
2315           &nbsp;&nbsp;&lt;cacheTime=&quot;2400&quot;/&gt;<br>
2316         &lt;/JNDIDirectoryDataConnector&gt;
2317       </span></blockquote>
2318
2319       <p><span class="fixedwidth">SimpleAttributeDefinition</span>:</p>
2320
2321       <dl>
2322         <dd class="attribute">
2323           <span class="fixedwidth">id = &lt;string&gt;</span>
2324         </dd>
2325
2326         <dd class="value">
2327           <p>Specifies a unique, textual name for the attribute which is
2328           used as the attribute's name when it is sent over the wire by
2329           Shibboleth.  Contained within the <span
2330           class="fixedwidth">SimpleAttributeDefinition</span>
2331           element.</p>
2332         </dd>
2333
2334         <dd class="attributeopt">
2335           <span class="fixedwidth">&lt;AttributeDependency / DataConnectorDependency requires=&quot;&lt;id&gt;&quot;/&gt;</span>
2336         </dd>
2337
2338         <dd class="valueopt">
2339           <p>An element of the element <span
2340           class="fixedwidth">SimpleAttributeDefinition</span>, which may
2341           contain 0 or more of either <span
2342           class="fixedwidth">AttributeDependency</span> or <span
2343           class="fixedwidth">DataConnectorDependency</span>.  These
2344           specify attributes and data connectors that can be utilized by
2345           this attribute definition.  Each of these elements must
2346           contain a <span class="fixedwidth">requires</span> statement
2347           which this attribute definition can then use to build its
2348           value.</p>
2349         </dd>
2350
2351         <dd class="attributeopt">
2352           <span class="fixedwidth">smartScope = &quot;&lt;domain&gt;&quot;</span>
2353         </dd>
2354
2355         <dd class="valueopt">
2356           <p>Specifes a domain scope to be attached to the attribute. If
2357           the value of the attribute as retrieved from the data
2358           connector includes a pre-existing scope (<span
2359           class="fixedwidth">bob@foo.edu</span>), that scope is used
2360           instead.  Contained within the <span
2361           class="fixedwidth">SimpleAttributeDefinition</span>
2362           element.</p>
2363         </dd>
2364
2365         <dd class="attributeopt">
2366           <span class="fixedwidth">sourceName = &quot;&lt;string&gt;&quot;</span>
2367         </dd>
2368
2369         <dd class="valueopt">
2370           <p>Specifies a different source attribute name to be used in
2371           calls to the data connector, while the name on the wire will
2372           be the specified <span class="fixedwidth">id</span>.  This
2373           would be useful to send a local UniversityID attribute as
2374           eduPersonPrincipalName.  If not supplied, the connector
2375           tokenizes the <span class="fixedwidth">id</span> field and
2376           uses the section following the <span
2377           class="fixedwidth">#</span> to query data connectors. 
2378           Contained within the <span
2379           class="fixedwidth">SimpleAttributeDefinition</span>
2380           element.</p>
2381         </dd>
2382
2383         <dd class="attributeopt">
2384           <span class="fixedwidth">&lt;cacheTime &quot;&lt;seconds&gt;&quot;/&gt;</span>
2385         </dd>
2386
2387         <dd class="valueopt">
2388           <p>An element of the element <span
2389           class="fixedwidth">SimpleAttributeDefinition</span>. 
2390           Specifies an optional duration in <span
2391           class="fixedwidth">seconds</span> for which the attribute
2392           resolver may cache this attribute for use in additional
2393           assertions.</p>
2394         </dd>
2395
2396         <dd class="attributeopt">
2397           <span class="fixedwidth">&lt;lifeTime &quot;&lt;seconds&gt;&quot;/&gt;</span>
2398         </dd>
2399
2400         <dd class="valueopt">
2401           <p>An element of the element <span
2402           class="fixedwidth">SimpleAttributeDefinition</span>. 
2403           Specifies in the attribute assertion how long the attribute
2404           should be cached and retained by the target upon receipt. 
2405           Federations and trust agreements may have some bearing on the
2406           population and use of this field.</p>
2407         </dd>
2408       </dl>
2409
2410       <p>A representation of a properly constructed <span
2411       class="fixedwidth">SimpleAttributeDefinition</span> element would
2412       look like:</p>
2413
2414       <blockquote><span class="fixedwidth">
2415         &lt;SimpleAttributeDefinition id=&quot;urn:mace:dir:attribute-def:eduPersonPrincipalName&quot; smartScope=&quot;shibdev.edu&quot; sourceName=&quot;universityPerson&quot;&gt;<br>
2416           &nbsp;&nbsp;&lt;DataConnectorDependency requires=&quot;dataConnector&quot;/&gt;<br>
2417           &nbsp;&nbsp;&lt;AttributeDependency requires=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;/&gt;<br>
2418               &nbsp;&nbsp;&lt;cacheTime=&quot;600&quot;/&gt;&lt;br&gt;<br>
2419               &nbsp;&nbsp;&lt;lifeTime=&quot;3600&quot;/&gt;&lt;br&gt;<br>
2420             &lt;/SimpleAttributeDefinition&gt;
2421       </span></blockquote>
2422
2423       <p>A properly formed <span class="fixedwidth">resolver.xml</span>
2424       file to automatically generate a simple response for EPPN may take
2425       the form:</p>
2426
2427       <blockquote><span class="fixedwidth">
2428          &lt;AttributeResolver xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; xmlns=&quot;urn:mace:shibboleth:resolver:1.0&quot; xsi:schemaLocation=&quot;urn:mace:shibboleth:resolver:1.0 shibboleth-resolver-1.0.xsd&quot;&gt;<br>
2429              <br>
2430              &nbsp;&nbsp;&lt;SimpleAttributeDefinition id=&quot;urn:mace:dir:attribute-def:eduPersonPrincipalName&quot; smartScope=&quot;shibdev.edu&quot;&gt;<br>
2431                     &nbsp;&nbsp;&nbsp;&nbsp;&lt;DataConnectorDependency requires=&quot;echo&quot;/&gt;<br>
2432               &nbsp;&nbsp;&lt;/SimpleAttributeDefinition&gt;<br>
2433              <br>
2434         &nbsp;&nbsp;&lt;CustomDataConnector id=&quot;echo&quot;
2435                 class=&quot;edu.internet2.middleware.shibboleth.aa.attrresolv.provider.SampleConnector&quot; /&gt;<br>
2436         &lt;/AttributeResolver&gt;
2437       </span></blockquote>
2438       
2439       <p>There are additional examples of <span class="fixedwidth">resolver.xml</span> files provided in the <a href="http://marsalis.internet2.edu/cgi-bin/viewcvs.cgi/shibboleth/java/src/conf/">Shibboleth CVS</a>.</p>
2440
2441     </blockquote>
2442     <br>
2443     <h4><a name="5.d."></a>5.d. Local Error Page</h4>
2444     <blockquote>
2445                 <p>Origin sites are encouraged to provide federations with the 
2446                 URL of a local Shibboleth error page. If a browser user from the 
2447                 origin site encounters a problem at a shibbolized target, the target 
2448                 is likely to display an error page that includes a link back to this 
2449                 origin provided page.</p>
2450
2451                 <p>The page should provide information on how to obtain local support 
2452                 for using Shibbolized resources. It might also include suggestions on 
2453                 what information should be recorded before beginning the problem 
2454                 resolution process.</p> 
2455     </blockquote>
2456
2457     <br>
2458     <br>
2459     <hr>
2460     <br>
2461      
2462
2463     <h3><a name="6."></a>6. Troubleshooting</h3>
2464
2465     <p>This section provides basic information about testing,
2466     logging, and error handling for Shibboleth origins. This
2467     information is not intended to be comprehensive, but instead
2468     rudimentary guidelines for basic configuration tests and
2469     problems. For more detailed information or answers to specific
2470     problems not addressed in this section, please mail <a href=
2471     "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>
2472     with a thorough description of errors and configurations
2473     used.</p>
2474
2475     <h4><a name="6.a."></a>6.a. Basic Testing</h4>
2476
2477     <blockquote>
2478       <p>Internet2 provides a basic target that can be used to test
2479       origin setup functionality. After your origin is recognized
2480       by InQueue, simply use any browser to access <a href=
2481       "https://wayf.internet2.edu/InQueue/sample.jsp">https://wayf.internet2.edu/InQueue/sample.jsp</a>.
2482       Select your origin's name and follow the login process as a
2483       user would. Note that SSL must be used, and both the HS and
2484       AA must be fully configured.</p>
2485
2486       <p>The test target will then display a simple page which
2487       includes the basic information sent to it by your origin and
2488       the authentication rules it is using.</p>
2489
2490       <p><b>For information regarding specific error messages that
2491       may be generated if the origin does not work successfully,
2492       please refer to section <a href="#6.c.">6.c</a>.</b></p>
2493     </blockquote>
2494
2495     <h4><a name="6.b."></a>6.b. Logging</h4>
2496
2497     <blockquote>
2498       <p>Shibboleth's origin components log various operations
2499       which may prove useful for auditing, testing, and security
2500       purposes. This data is sent through <span class="fixedwidth">log4j</span>'s
2501       standard mechanism. The location of
2502       the log file, the level at which the log is output, the
2503       formatting of the logs, and many more options may be
2504       configured by editing
2505       <span class="fixedwidth">/WEB-INF/classes/conf/log4j.properties</span>. By default,
2506       it is setup to log to the console of the servlet container, with a
2507       level of <span class="fixedwidth">WARN</span>, but there is also a commented out
2508       example in the file to give a possible alternate configuration.</p>
2509     </blockquote>
2510
2511     <h4><a name="6.c."></a>6.c. Common Problems</h4>
2512
2513     <blockquote>
2514       <p>A knowledge base is being developed in the <a
2515                   href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.html">
2516                   Shibboleth Deployer's FAQ</a>.  Please mail <a href=
2517       "mailto:mace-shib-users@internet2.edu">mace-shib-users@
2518       internet2.edu</a> with any additional questions or problems
2519       encountered that are not answered by this basic guide.</p>
2520     </blockquote>
2521   </body>
2522 </html>
2523