Revised config file element descriptions.
[java-idp.git] / doc / InQueue.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3         <head>
4                 <title>InQueue Federation Policy and Configuration Guidelines</title>
5                 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6                 <style type="text/css">
7
8                         html
9                         {       
10                                 background-color: #FFFFFF;
11                                 color: #000000;
12                                 margin: .5em;
13                         }
14                         a:visited
15                         {
16                                 color: #999999;
17                         }
18                         a:link
19                         {
20                                 color: #990000;
21                         }
22                         a:active
23                         {
24                                 color: #440000;
25                         }
26                         dl
27                         {
28                                 background-color: #DDDDDD;
29                                 background-image: none;
30                                 margin: 5px;
31                                 padding: 0px;
32                                 border-style: solid;
33                                 border-bottom-width: 2px;
34                                 border-top-width: 2px;
35                                 border-left-width: 2px;
36                                 border-right-width: 2px;
37                         }
38                         dt
39                         {
40                                 background-color: #DDDDDD;
41                                 background-image: none;
42                                 margin: 1px;
43                                 padding: 1px;
44                         }
45                         dd
46                         {
47                                 background-color: #DDDDDD;
48                                 background-image: none;
49                                 margin: 0px;
50                                 padding: 1px;
51                         }
52                         .attribute
53                         {
54                                 font-size: 115%;
55                                 font-color: #000000;
56                                 text-align: left;
57                                 background-color: #DDDDDD;
58                                 border: 1px black inset;
59                                 background-image: none;
60                                 margin: 0px;
61                                 padding: 2px;
62                         }
63                         .value
64                         {
65                                 font-color: #000000;
66                                 text-align: left;
67                                 background-color: #EEEEEE;
68                                 background-image: none;
69                                 padding-top: 0em;
70                                 padding-bottom: 0.5em;
71                                 padding-right: 1em;
72                                 padding-left: 5em;
73                                 border-style: solid;
74                                 border-bottom-width: none;
75                                 border-top-width: none;
76                                 border-left-width: 1px;
77                                 border-right-width: 1px;
78                         }
79                         .attributeopt
80                         {
81                                 font-size: 115%;
82                                 font-color: #000000;
83                                 text-align: left;
84                                 background-color: #BCBCEE;
85                                 border: 1px black inset;
86                                 background-image: none;
87                                 margin: 0px;
88                                 padding: 2px;
89                         }
90                         .valueopt
91                         {
92                                 font-color: #000000;
93                                 text-align: left;
94                                 background-color: #DDDDFF;
95                                 background-image: none;
96                                 padding-top: 0em;
97                                 padding-bottom: 0.5em;
98                                 padding-right: 1em;
99                                 padding-left: 5em;
100                                 border-style: solid;
101                                 border-bottom-width: none;
102                                 border-top-width: none;
103                                 border-left-width: 1px;
104                                 border-right-width: 1px;
105                         }
106                         .attributelong
107                         {
108                                 font-size: 85%;
109                                 font-color: #000000;
110                                 text-align: left;
111                                 background-color: #DDDDDD;
112                                 border: 1px black inset;
113                                 background-image: none;
114                                 margin: 0px;
115                                 padding: 2px;
116                         }
117                         .attributeoptlong
118                         {
119                                 font-size: 85%;
120                                 font-color: #000000;
121                                 text-align: left;
122                                 background-color: #BCBCEE;
123                                 border: 1px black inset;
124                                 background-image: none;
125                                 margin: 0px;
126                                 padding: 2px;
127                         }
128                         .demo
129                         {
130                                 background-color: #EEEEEE;
131                                 padding: 3px;
132                         }
133                         .fixedwidth
134                         {
135                                 font-family: monospace;
136                                 font-size: 90%;
137                                 font-color: #121212;
138                         }
139
140                 </style></head><body link="red" vlink="red" alink="black" bgcolor="white">
141                 InQueue Federation Policy and Configuration Guidelines<br>
142                 Version 1.1<br />
143                 August 4, 2003<br />
144
145                 <h3>InQueue Federation Policy and Configuration Guidelines</h3>
146
147                 <h4>1.  Introduction to InQueue</h4>
148                 <blockquote><p>
149                         The InQueue Federation, operated by Internet2, is designed for
150                         organizations that are becoming familiar with the Shibboleth software
151                         package and the federated trust model.  InQueue provides the basic
152                         services needed for a federation using Shibboleth:</p>
153
154                         <ul>
155                                 <li>maintenance and distribution of participating site description and
156                                 security files;</li>
157                                 <li>a central WAYF ("where are you from") web site;</li>
158                                 <li>specification of operational procedures and policies, including
159                                 user data (attribute) definitions; and</li>
160                                 <li>example target and origin sites with which to test
161                                 interoperability.</li>
162                         </ul>
163
164                         <p>Participating in InQueue permits an organization to learn about the
165                         Shibboleth software via the experience of multi-party federated access,
166                         while integrating its services into the organization's procedures and
167                         policies.</p>
168
169                         <p>The InQueue federation is specifically <b>not</b> intended to support
170                         production-level end-user access to protected resources.  Organizations
171                         operating target sites are strongly discouraged from making sensitive or
172                         valuable resources available via the Federation.</p>
173                 </blockquote>
174
175                 <h4>2.  InQueue Policies</h4>
176
177                 <h4>2.1  Participation</h4>
178
179                 <blockquote><p>An organization may join InQueue as an origin, as a
180                         target, or both.
181                         Participants are expected to be authorized representatives of
182                         their organization.  Internet2 reserves the right to make final
183                         decisions about participation in the Federation.</p>
184
185                         <p>InQueue is intended to serve as a primary federation
186                         for an organization only during the period an
187                         organization is learning about Shibboleth and federated
188                         operations.  Upon completion of this period, the
189                         organization is expected to join a Federation (or some
190                         other management solution) that meets its long-term
191                         operational needs. </p>
192
193                         <p>By joining InQueue, an organization agrees that the
194                         Federation can list their name on the Federation web
195                         site as a member of the Federation.</p>
196                         
197                         <p>In joining InQueue, an organization will make a good
198                         faith effort to maintain a web page describing their use
199                         of Shibboleth. This page will be linked from the
200                         Federation member list.</p>
201
202                         </blockquote>
203
204                         <h4>2.2  Data management</h4>
205
206                         <blockquote><p>
207                                 By participating, origins agree that all attributes sent
208                                 to targets in the Federation to the best of their knowledge accurately
209                                 represent information about the authenticated individual accessing the
210                                 target resource.</p>
211
212                                 <p>Targets agree to dispose of all received
213                                 attributes properly by not mis-using them, aggregating them, or
214                                 sharing them with other organizations.</p></blockquote>
215
216                         <h4>2.3  Security management</h4>
217
218                         <blockquote><p>InQueue distributes a set of root certificates for
219                                 issuers from which server certificates may be obtained to identify
220                                 InQueue server components.
221                                 Additionally, sites with certificates not rooted
222                                 in one of these trusted roots may have these certificates added to the
223                                 appropriate trust file.  Targets must have a certificate signed by an
224                                 acceptible CA.  The list of certificate authorities used by
225                                 InQueue is:</p>
226                                 <ul type="circle">
227                                         <li><a href="http://www.verisign.com/">Verisign/RSA Secure Server CA</a></li>
228                                         <li><a href="http://bossie.doit.wisc.edu/cert/i2server">Internet2
229                                                 HEPKI Test CA</a></li>
230                                         <li><a href="http://www.cren.net/crenca/">CREN CA</a></li>
231                                 </ul>
232                                 
233                                 <p>For origins, OpenSSL must also be configured to use the
234                                 appropriate set of trusted roots for the issuance of SSL
235                                 certificates that Shibboleth trusts.  For InQueue, this list may
236                                 be obtained from <span
237                                 class="fixedwidth">http://wayf.internet2.edu/InQueue/ca-bundle.
238                                 crt</span>.  This list should then be copied for <span
239                                 class="fixedwidth">mod_ssl</span>, which will typically need to
240                                 be to <span
241                                 class="fixedwidth">/conf/ssl.crt/ca-bundle.crt</span>.  This
242                                 list of CA's is <b>not</b> rigorous nor secure and may contain
243                                 CA's which have no level of assurance or are questionable.</p>
244                         </blockquote>
245
246                         <h4>2.4  Attributes</h4>
247                         <blockquote><p>The InQueue 
248                                 Federation specifies a set of attribute definitions to support basic
249                                 attribute-based authorization.</p>
250                                 <ol>
251                                 <li>If a Federation member sends or receives an Attribute Assertion 
252                                 containing the InQueue policy uri and referencing one of the listed
253                                 attributes, 
254                                 the syntax and semantics of the associated attribute value should
255                                 conform 
256                                 to the definitions specified in the <a href="http://www.educause.edu/eduperson/">EduPerson specification 2002/10</a>
257
258                                 <ul type="circle">
259                                         <li>eduPersonPrincipalName</li>
260                                         <li>eduPersonEntitlement</li>
261                                         <li>eduPersonAffiliation (expressed in a slightly different form via
262                                         a new attribute called eduPersonScopedAffiliation)</li>
263                                 </ul>
264                                 <li>If a Federation member sends or receives an Attribute Assertion 
265                                 containing the InQueue policy uri and referencing one of the listed
266                                 attributes, 
267                                 the syntax and semantics of the associated attribute value should
268                                 conform 
269                                 to the definitions specified in the relevant <a href="http://www/ietf.org">IETF</a> RFCs.
270
271                                 <ul type="circle">
272                                         <li>cn
273                                         <li>sn
274                                         <li>telephoneNumber
275                                         <li>title
276                                         <li>initials
277                                         <li>description
278                                         <li>carLicense
279                                         <li>departmentNumber
280                                         <li>displayName
281                                         <li>employeeNumber
282                                         <li>employeeType
283                                         <li>preferredLanguage
284                                         <li>manager
285                                         <li>roomNumber
286                                         <li>seeAlso
287                                         <li>facsimileTelephoneNumber
288                                         <li>street
289                                         <li>postOfficeBox
290                                         <li>postalCode
291                                         <li>st
292                                         <li>givenName
293                                         <li>l
294                                         <li>businessCategory
295                                         <li>ou
296                                         <li>physicalDeliveryOfficeName
297                                 </ul>
298                                 <li>If a Federation member sends or receives an eduPersonEntitlement Attribute Assertion 
299                                 containing the InQueue policy uri and containing one of the listed
300                                 values, 
301                                 the syntax and semantics of the associated attribute value should
302                                 conform 
303                                 to these definitions
304
305                                 <ul type="circle">
306                                         <li>urn:mace:incommon:entitlement:common:1
307                                         <p>The person possesses an eduPersonAffiliation value of faculty, staff,  or student, or qualifies as a "library walk-in".
308                                         
309                                 </ul>                           
310                                 </ol>
311                         </blockquote>
312
313                         <h4>3.  Joining InQueue</h4>
314
315                         <blockquote><p>To join InQueue, origins <a href="mailto:inqueue-support@internet2.edu?subject=Shib%20Origin%20Site%%0D%20%2020Application"> submit a request to
316                                         inqueue-support@internet2.edu</a> containing the following
317                                 information:</p></blockquote>
318
319                         <blockquote>
320                                 <ul type="circle">
321                                         <li>Domain Name of the origin site (e.g., Ohio State's is
322                                         "osu.edu").</li>
323                                         <li>Complete URL to access the Shibboleth Handle Service at the site.</li>
324                                         <li>The CN (usually the hostname) of the HS's certificate's subject.
325                                         This should also be the value of <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.
326                                                 HandleServlet.issuer</span> in <span class="fixedwidth">origin.properties</span>.</li>
327                                         <li>Any shorthand aliases the WAYF should support for the origin
328                                         site (e.g., Ohio State, OSU, Buckeyes)</li>
329                                         <li>Contact names and addresses for technical and administrative
330                                         issues.</li>
331                                         <li>The URL of an error page that users selecting this origin from
332                                         the WAYF may be referred to by targets if Shibboleth
333                                         malfunctions. (optional)</li>
334                                         <li>If the HS's certificate is not issueed by one of the root CAs
335                                         used
336                                         by InQueue, then it must be submitted in Base64-encoded DER (aka
337                                         "PEM") format.</li>
338                                         <li>(optional) Briefly describe the organization's planned uses of Shibboleth.
339                         </ul></blockquote>
340
341                         <blockquote><p>To join InQueue, targets must <a href="mailto:inqueue-support@internet2.edu?subject=Shib%20Target%20Site%%0D%20%2020Application"> submit a basic application to
342                                         inqueue-support@internet2.edu</a> containing the following
343                                 information:</p></blockquote>
344
345                         <blockquote>
346                                 <ul type="circle">
347                                         <li>The name of the organization</li>
348                                         <li>Contact names and addresses for both administrative and
349                                         technical purposes</li>
350                                 </ul>
351                         </blockquote>
352
353                         <h4>4.  Configuration for Using InQueue</h4>
354
355                         <blockquote><p>Once your site is accepted into and added to InQueue,
356                                 the following configuration parameters must be entered to ensure
357                                 interoperability and compliance with federation guidelines.  Consult
358                                 the Shibboleth Deploy Guides for further information on these fields
359                                 and on <span class="fixedwidth">origin.properties</span> and <span class="fixedwidth">shibboleth.ini</span>.</p></blockquote>
360
361                         <blockquote><h5>4.a. Origins:</h5>
362
363                                 <dl><dd class="attribute"><span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName</span>
364                                         </dd><dd class="value"><p>Must be populated with a URI that will
365                                         be assigned by InQueue when you are accepted into the
366                                         federation.</p></dd><dd class="attribute"><span class="fixedwidth">edu.internet2.middleware.shibboleth.audiences</span>
367                                         </dd><dd class="value"><p>This field must contain InQueue's <span class="fixedwidth">urn:mace:inqueue</span> URI, and may contain other federation URIs as well.</p></dd></dl>
368                                 </blockquote>
369
370                                 <blockquote><h5>4.b. Targets:</h5>
371
372                                         <dl><dd class="attribute"><span class="fixedwidth">wayfURL</span>
373                                                 </dd><dd class="value"><p>This field must be set to InQueue's simple WAYF at <span class="fixedwidth">https://wayf.internet2.edu/InQueue/WAYF</span>.</p></dd><dd class="attribute"><span class="fixedwidth">[policies]</span>
374                                                 </dd><dd class="value"><p>This section must contain <span class="fixedwidth">InQueue = urn:mace:inqueue</span>, and may
375                                                 contain other federation name/value pairs as well.</p></dd>
376                                         </dl>
377                                 </blockquote>
378
379                                 <blockquote><h5>4.b.i. Refreshing Federation Metadata:</h5>
380                                         <p>Once your target site is accepted into the InQueue federation, it is necessary that you periodically
381                                         update the target's federation metadata.  This metadata includes information used to identify and authenticate
382                                         InQueue sites.</p>
383                                         
384                                         <p>InQueue's metadata is digitally signed, so the first step is to obtain the InQueue signing certificate.  
385                                         It can be downloaded from <span class="fixedwidth">http://wayf.internet2.edu/InQueue/internet2.pem
386                                         </span> and has a fingerprint of:</p>
387                                         <p><span class="fixedwidth">b4 42 6c 1e 8b 7d 8e b3 68 03 00 e4 c4 57 dd 74 89 f8 9a 80</span>.</p>
388
389                                         <p>The following commands can be used to obtain the federation's metadata:</p>
390                                         <p><span class="fixedwidth"> $ cd /opt/shibboleth/etc/shibboleth</span></p>
391                                         <p><span class="fixedwidth">$ ../../bin/siterefresh --url http://wayf.internet2.edu/InQueue/sites.xml
392                                                 --out sites.xml --cert internet2.pem</span></p>
393                                                 <p><span class="fixedwidth">$ ../../bin/siterefresh --url http://wayf.internet2.edu/InQueue/trust.xml 
394                                                         --out trust.xml --cert internet2.pem</span></p>
395                                 </blockquote>
396
397                                 <h4>5.  Testing</h4>
398                                 <blockquote><p>A <a href="https://wayf.internet2.edu/shibboleth/sample.jsp">sample shibboleth target</a>
399                                         is available for testing newly installed origin sites.  New targets can make use of a sample origin, 
400                                         which is listed as "Example State University" on the InQueue WAYF ( Username: demo / Password: demo ).</p></blockquote>
401
402                 </body></html>
403