Added Ian
[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                         .fixed
27                         {
28                                 font-family: monospace;
29                                 font-size: 90%;
30                                 font-color: #121212;
31                         }
32
33                 </style></head><body link="red" vlink="red" alink="black" bgcolor="white">
34                 InQueue Federation Policy and Configuration Guidelines<br>
35                 Version 1.2<br />
36                 May 19, 2004<br />
37
38                 <h3>InQueue Federation Policy and Configuration Guidelines</h3>
39
40                 <h4>1.  Introduction to InQueue</h4>
41                 <blockquote><p>
42                         The InQueue Federation, operated by Internet2, is designed for
43                         organizations that are becoming familiar with the Shibboleth
44                         software package and the federated trust model.  It is also
45                         available as a temporary alternative to sites for which no suitable
46                         production-level federation exists.  InQueue provides the basic
47                         services needed for a federation using Shibboleth:</p>
48
49                         <ul>
50                                 <li>maintenance and distribution of participating site description and
51                                 security files;</li>
52                                 <li>a central WAYF ("where are you from") web site;</li>
53                                 <li>specification of operational procedures and policies, including
54                                 user data (attribute) definitions; and</li>
55                                 <li>example target and origin sites with which to test
56                                 interoperability.</li>
57                         </ul>
58
59                         <p>Participating in InQueue permits an organization to learn about the
60                         Shibboleth software via the experience of multi-party federated access,
61                         while integrating its services into the organization's procedures and
62                         policies.</p>
63
64                         <p>The InQueue federation is specifically <b>not</b> intended to support
65                         production-level end-user access to protected resources.  Organizations
66                         operating target sites are strongly discouraged from making sensitive or
67                         valuable resources available via the Federation. <b>Specifically, certificate
68                         authorities with no level of assurance may be used to issue certificates
69                         to participating sites, and therefore none of the interactions can be
70                         trusted.</b></p>
71                 </blockquote>
72
73                 <h4>2.  InQueue Policies</h4>
74
75                 <h4>2.1  Participation</h4>
76
77                 <blockquote><p>An organization may join InQueue as an origin, as a
78                         target, or both.
79                         Participants are expected to be authorized representatives of
80                         their organization.  Internet2 reserves the right to make final
81                         decisions about participation in the Federation.</p>
82
83                         <p>InQueue is intended to serve as a primary federation
84                         for an organization only during the period an
85                         organization is learning about Shibboleth and federated
86                         operations.  Upon completion of this period, the
87                         organization is expected to join a Federation (or some
88                         other management solution) that meets its long-term
89                         operational needs. </p>
90
91                         <p>By joining InQueue, an organization agrees that the
92                         Federation can list their name on the Federation web
93                         site as a member of the Federation.</p>
94                         
95                         <p>In joining InQueue, an organization will make a good
96                         faith effort to maintain a web page describing their use
97                         of Shibboleth. This page will be linked from the
98                         Federation member list.</p>
99
100                         </blockquote>
101
102                         <h4>2.2  Data management</h4>
103
104                         <blockquote><p>
105                                 By participating, origins agree that all attributes sent
106                                 to targets in the Federation to the best of their knowledge accurately
107                                 represent information about the authenticated individual accessing the
108                                 target resource.</p>
109
110                                 <p>Targets agree to dispose of all received
111                                 attributes properly by not mis-using them, aggregating them, or
112                                 sharing them with other organizations.</p></blockquote>
113
114                         <h4>2.3  Security management</h4>
115
116                         <blockquote><p>InQueue distributes a set of root certificates for
117                         issuers from which server certificates may be obtained to identify
118                         InQueue server components.  Both targets and origins should have a
119                         certificate obtained from one of the authorities below.  Additional
120                         certificate authorities may be recognized as necessary to support
121                         use of both free and common commercial certificates for testing. 
122                         The list of certificate authorities used by InQueue is:</p>
123                                 <ul type="circle">
124                                         <li><a href="http://www.verisign.com/">Verisign/RSA Secure Server CA</a></li>
125                                         <li><a href="http://bossie.doit.wisc.edu/cert/i2server">Internet2
126                                                 HEPKI Test CA</a></li>
127                                         <li><a href="http://www.cren.net/crenca/">CREN CA</a></li>
128                                         <li><a href="http://www.thawte.com/ssl/index.html">Thawte Server & Premium Server CA's</a></li>
129                                         <li><a href="http://www.incommonfederation.org/">InCommon CA</a></li>
130                                 </ul>
131
132                         </blockquote>
133
134                         <h4>2.4  Attributes</h4>
135                         <blockquote><p>The InQueue 
136                                 Federation specifies a set of attribute definitions to support basic
137                                 attribute-based authorization.</p>
138                                 <ol>
139                                 <li>Attribute assertions issued or received by InQueue members including eduPerson attributes should conform to the syntax and semantics defined by the <a href="http://www.educause.edu/eduperson/">eduPerson 2003/12</a> specification.
140
141                                 <ul type="circle">
142                                         <li>urn:mace:dir:attribute-def:eduPersonEntitlement</li>
143                                         <li>urn:mace:dir:attribute-def:eduPersonPrincipalName</li>
144                                         <li>urn:mace:dir:attribute-def:eduPersonScopedAffiliation</li>
145                                 </ul></li>
146                                 <li>If a Federation member sends or receives an Attribute Assertion 
147                                 containing the InQueue policy uri and referencing one of the listed
148                                 attributes, 
149                                 the syntax and semantics of the associated attribute value should
150                                 conform 
151                                 to the definitions specified in the relevant <a href="http://www/ietf.org">IETF</a> RFCs.
152
153                                 <ul type="circle">
154                                         <li>cn
155                                         <li>sn
156                                         <li>telephoneNumber
157                                         <li>title
158                                         <li>initials
159                                         <li>description
160                                         <li>carLicense
161                                         <li>departmentNumber
162                                         <li>displayName
163                                         <li>employeeNumber
164                                         <li>employeeType
165                                         <li>preferredLanguage
166                                         <li>manager
167                                         <li>roomNumber
168                                         <li>seeAlso
169                                         <li>facsimileTelephoneNumber
170                                         <li>street
171                                         <li>postOfficeBox
172                                         <li>postalCode
173                                         <li>st
174                                         <li>givenName
175                                         <li>l
176                                         <li>businessCategory
177                                         <li>ou
178                                         <li>physicalDeliveryOfficeName
179                                 </ul>
180                                 <li>If a Federation member sends or receives an eduPersonEntitlement Attribute Assertion 
181                                 containing the InQueue policy uri and containing one of the listed
182                                 values, 
183                                 the syntax and semantics of the associated attribute value should
184                                 conform 
185                                 to these definitions
186
187                                 <ul type="circle">
188                                         <li>urn:mace:incommon:entitlement:common:1
189                                         <p>The person possesses an eduPersonAffiliation value of faculty, staff,  or student, or qualifies as a "library walk-in".
190                                         
191                                 </ul>                           
192                                 </ol>
193                         </blockquote>
194
195                         <h4>3.  Joining InQueue</h4>
196
197                         <blockquote><p>To join InQueue, origins <a href="mailto:inqueue-support@internet2.edu?subject=Shib%20Origin%20Site%%0D%20%2020Application"> submit a request to
198                                         inqueue-support@internet2.edu</a> containing the following
199                                 information:</p></blockquote>
200
201                         <blockquote>
202                                 <ul type="circle">
203                                         <li>Domain Name of the origin site (e.g., Ohio State's is
204                                         "osu.edu").</li>
205                                         <li>Complete URL to access the Shibboleth Handle Service at
206                                         the site.</li>
207                                         <li>The CN (usually the hostname) or the full subject of the
208                                         HS's certificate's subject.  If the certificate is readable
209                                         by OpenSSL (not keytool), this value can be obtained using
210                                         the following command:
211                                         <blockquote><span class="fixed">
212                                                 $ openssl x509  -in &lt;file&gt; -subject -nameopt rfc2253
213                                         </span></blockquote></li>
214                                         <li>Complete URL to access the Shibboleth Attribute Authority at the site.</li>
215                                         <li>Any shorthand aliases the WAYF should support for the origin
216                                         site (e.g., Ohio State, OSU, Buckeyes)</li>
217                                         <li>Contact names and e-mail addresses for technical and
218                                         administrative issues.</li>
219                                         <li>The URL of an error page that users selecting this
220                                         origin from the WAYF may be referred to by targets if there
221                                         is a problem encountered by the target, such as incorrect
222                                         attributes leading to an access failure. (optional)</li>
223                                         <li>(optional) Briefly describe the organization's planned
224                                         uses of Shibboleth.
225                         </ul></blockquote>
226
227                         <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
228                                         inqueue-support@internet2.edu</a> containing the following
229                                 information:</p></blockquote>
230
231                         <blockquote>
232                                 <ul type="circle">
233                                         <li>The name of the organization</li>
234                                         <li>Contact names and e-mail addresses for techincal and
235                                         administrative issues.</li>
236                                         <li>The CN (usually the hostname) or the full subject of the
237                                         SHAR's certificate's subject.  If the certificate is readable
238                                         by OpenSSL (not keytool), this value can be obtained using
239                                         the following command:
240                                         <blockquote><span class="fixed">
241                                                 $ openssl x509  -in &lt;file&gt; -subject -nameopt rfc2253
242                                         </span></blockquote></li>
243                                         <li>The URL of all SHIRE locations (specified using a
244                                         <span class="fixed">shireURL</span> attribute in a <a
245                                         href="http://SHIBBOLETHTARGETGUIDEURL#confSessions"><span
246                                         class="fixed">Sessions</span></a> element) set up for this
247                                         organization, e.g. <span
248                                         class="fixed">https://example.org/Shibboleth.shire</span>. 
249                                         Note that the assumption is that access will only occur over
250                                         the protocol specified by the SHIRE URL submitted (<span
251                                         class="fixed">https</span> or <span
252                                         class="fixed">http</span>); if there is a desire to listen
253                                         on both ports, this should be noted in the application.</li>
254                                 </ul>
255                         </blockquote>
256
257                         <h4>4.  Configuration for Using InQueue</h4>
258
259                         <blockquote><p>Once your site is accepted into and added to InQueue,
260                                 the following configuration parameters must be entered to ensure
261                                 interoperability and compliance with federation guidelines.  Consult
262                                 the Shibboleth Deploy Guides for further information on these fields
263                                 and on <span class="fixed">origin.xml</span> and <span class="fixed">shibboleth.xml</span>.</p></blockquote>
264
265                         <blockquote><h5>4.a. Origins:</h5>
266                                 <p>The following steps must be undertaken to configure a
267                                 standard Shibboleth origin configuration to use InQueue.  Some
268                                 steps may vary or may be completed already depending on how
269                                 <span class="fixed">origin.xml</span> has already been
270                                 modified.</p>
271                                 <ol>
272                                         <li><a href="http://SHIBBOLETHORIGINGUIDEURL#confShibbolethOriginConfig"><span class="fixed">ShibbolethOriginConfig</span></a> must be modified as follows:
273                                         <ul>
274                                                 <li><span class="fixed">providerId</span> must be
275                                                 populated with a URI that will be assigned by InQueue
276                                                 when you are accepted into the federation.</li>
277                                                 <li><span class="fixed">defaultRelyingParty</span>
278                                                 should be changed to <span
279                                                 class="fixed">urn:mace:inqueue</span>.</li>
280                                                 <li>Ensure that <span class="fixed">AAUrl</span> has
281                                                 been changed to reflect the value sent in with the
282                                                 application.</li>
283                                         </ul></li>
284                                         <li>Uncomment the InQueue <a href="http://SHIBBOLETHORIGINGUIDEURL#confRelyingParty"><span class="fixed">RelyingParty</span></a> element.  If the default <span class="fixed">providerId</span> as specified in <a href="http://SHIBBOLETHORIGINGUIDEURL#confShibbolethOriginConfig"><span class="fixed">ShibbolethOriginConfig</span></a> is not the one supplied by InQueue, modify the <span class="fixed">providerId</span> to match the value assigned by InQueue to this origin.</li>
285                                         <li>A new <a href="http://SHIBBOLETHORIGINGUIDEURL#confKeyStoreResolver"><span class="fixed">KeyStoreResolver</span></a> or <a href="http://SHIBBOLETHORIGINGUIDEURL#confFileResolver"><span class="fixed">FileResolver</span></a> element must be added pointing to the private key and certificate for use by this origin.  See <a href="http://SHIBBOLETHORIGINGUIDEURL#4.b.">section 4.b</a> of the origin deploy guide for further information.</li>
286                                         <li>Uncomment the <a href="http://SHIBBOLETHORIGINGUIDEURL#confFederationProvider"><span class="fixed">FederationProvider</span></a> element for InQueue.</li>
287                                         <li>OpenSSL must also be configured to use the
288                                 appropriate set of trusted roots for the issuance of SSL
289                                 certificates that Shibboleth trusts.  For InQueue, this list may
290                                 be obtained from <span
291                                 class="fixed">http://wayf.internet2.edu/InQueue/ca-bundle.crt</span>.
292                                 This list should then be copied for <span
293                                 class="fixed">mod_ssl</span>, which will typically need to
294                                 be to <span
295                                 class="fixed">/conf/ssl.crt/ca-bundle.crt</span>.  This
296                                 list of CA's is <b>not</b> rigorous nor secure and may contain
297                                 CA's which have no level of assurance or are questionable.</li>
298                                 </ol>
299                                 </blockquote>
300
301                                 <blockquote><h5>4.b. Targets:</h5>
302
303                                 <p>The following steps must be undertaken to configure a
304                                 standard Shibboleth target configuration to use InQueue.  Some
305                                 steps may vary or may be completed already depending on how
306                                 <span class="fixed">shibboleth.xml</span> has already been
307                                 modified.  This guide covers modification of the default <a
308                                 href="http://SHIBBOLETHTARGETGUIDEURL#confApplications"><span
309                                 class="fixed">Applications</span></a> element from localhost
310                                 operation to InQueue operation for simplicity's sake.</p>
311                                 <ol>
312                                         <li>The <span class="fixed">providerId</span> attribute of the <a href="http://SHIBBOLETHTARGETGUIDEURL#confApplications"><span class="fixed">Applications</span></a> element should be changed to the InQueue-assigned value.</li>
313                                         <li>Ensure that the <a href="http://SHIBBOLETHTARGETGUIDEURL#confSessions"><span class="fixed">Sessions</span></a> element's <span class="fixed">wayfURL</span> is <span class="fixed">https://wayf.internet2.edu/InQueue/WAYF</span>.</li>
314                                         <li>Uncomment the InQueue <a href="http://SHIBBOLETHTARGETGUIDEURL#confRelyingParty"><span class="fixed">RelyingParty</span></a> element within the <a href="http://SHIBBOLETHTARGETGUIDEURL#confCredentialsUse"><span class="fixed">CredentialsUse</span></a> element.</li>
315                                         <li>Uncomment the <a href="http://SHIBBOLETHTARGETGUIDEURL#confFileResolver"><span class="fixed">FileResolver</span></a> element with a <span class="fixed">Id</span> of <span class="fixed">inqueuecreds</span>.  The key path, key password, and certificate path should be modified to match new credentials generated according to <a href="http://SHIBBOLETHTARGETGUIDEURL#4.c.">section 4.c</a> of the target deploy guide.</li>
316                                 </ol>
317                                 </blockquote>
318
319                                 <blockquote><h5>4.c. Refreshing Federation Metadata:</h5>
320                                         <p>Shibboleth 1.2 includes new metadata both for origin sites
321                                         and for target sites.  The origin has the <a
322                                         href="http://SHIBBOLETHORIGINGUIDEURL#4.e."><span
323                                         class="fixed">metadatatool</span></a> and the target uses
324                                         the <a href="http://SHIBBOLETHTARGETGUIDEURL#4.g."><span
325                                         class="fixed">siterefresh</span></a> tool to maintain
326                                         locally cached versions of various files.   Once your site
327                                         is accepted into the InQueue federation, it is necessary
328                                         that you periodically update the federation's metadata. 
329                                         This metadata includes information used to identify and
330                                         authenticate InQueue sites.  This should be frequently run
331                                         by adding it to a <span class="fixed">crontab</span> to
332                                         ensure that the data is fresh.</p>
333                                         
334                                         <p>InQueue's metadata is digitally signed, so the first step is to obtain the InQueue signing certificate.  
335                                         It can be downloaded from <span class="fixed">http://wayf.internet2.edu/InQueue/inqueue.pem
336                                         </span> and has a fingerprint of:</p>
337                                         <p><span class="fixed">b4 42 6c 1e 8b 7d 8e b3 68 03 00 e4 c4 57 dd 74 89 f8 9a 80</span>.</p>
338
339                                         <p>The following commands can be used to obtain the federation's metadata for a Shibboleth 1.2 <b>target</b>:</p>
340                                         <blockquote><span class="fixed">
341                                         $ cd /opt/shibboleth/etc/shibboleth<br>
342                     $ ../../bin/siterefresh --url http://wayf.internet2.edu/InQueue/IQ-sites.xml --out IQ-sites.xml --cert inqueue.pem<br>
343                                         $ ../../bin/siterefresh --url http://wayf.internet2.edu/InQueue/IQ-trust.xml --out IQ-trust.xml --cert inqueue.pem</span>
344                                         </blockquote>
345
346                                         <p>The origin metadatatool's operation is greatly simplified
347                                         if a keystore file is downloaded from <span
348                                         class="fixed">https://wayf.internet2.edu/InQueue/inqueue.jks</span>
349                                         and placed in the same directory as <span
350                                         class="fixed">metadatatool</span>.  After this has been
351                                         done, the following commands can be used to obtain the
352                                         federation's metadata for a Shibboleth <b>origin</b>:</p>
353                                         <blockquote><span class="fixed">metadatatool -i http://wayf.internet2.edu/InQueue/IQ-sites.xml -o IQ-sites.xml -k inqueue.jks -a inqueue
354                                         </span></blockquote>
355                                 </blockquote>
356
357                                 <h4>5.  Testing</h4>
358                                 <blockquote><p>A <a href="https://wayf.internet2.edu/InQueue/sample.jsp">sample shibboleth target</a>
359                                         is available for testing newly installed origin sites.  New targets can make use of a sample origin, 
360                                         which is listed as "Example State University" on the InQueue WAYF ( Username: demo / Password: demo ).</p></blockquote>
361         </body>
362 </html>