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