1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
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">
10 background-color: #FFFFFF;
28 background-color: #DDDDDD;
29 background-image: none;
33 border-bottom-width: 2px;
34 border-top-width: 2px;
35 border-left-width: 2px;
36 border-right-width: 2px;
40 background-color: #DDDDDD;
41 background-image: none;
47 background-color: #DDDDDD;
48 background-image: none;
57 background-color: #DDDDDD;
58 border: 1px black inset;
59 background-image: none;
67 background-color: #EEEEEE;
68 background-image: none;
70 padding-bottom: 0.5em;
74 border-bottom-width: none;
75 border-top-width: none;
76 border-left-width: 1px;
77 border-right-width: 1px;
84 background-color: #BCBCEE;
85 border: 1px black inset;
86 background-image: none;
94 background-color: #DDDDFF;
95 background-image: none;
97 padding-bottom: 0.5em;
101 border-bottom-width: none;
102 border-top-width: none;
103 border-left-width: 1px;
104 border-right-width: 1px;
111 background-color: #DDDDDD;
112 border: 1px black inset;
113 background-image: none;
122 background-color: #BCBCEE;
123 border: 1px black inset;
124 background-image: none;
130 background-color: #EEEEEE;
135 font-family: monospace;
140 </style></head><body link="red" vlink="red" alink="black" bgcolor="white">
141 InQueue Federation Policy and Configuration Guidelines<br>
145 <h3>InQueue Federation Policy and Configuration Guidelines</h3>
147 <h4>1. Introduction to InQueue</h4>
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>
155 <li>maintenance and distribution of participating site description and
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>
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
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>
175 <h4>2. InQueue Policies</h4>
177 <h4>2.1 Participation</h4>
179 <blockquote><p>An organization may join InQueue as an origin, as a
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>
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>
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>
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>
204 <h4>2.2 Data management</h4>
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
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>
216 <h4>2.3 Security management</h4>
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
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>
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="fixed">http://wayf.internet2.edu/InQueue/ca-bundle.
238 crt</span>. This list should then be copied for <span
239 class="fixed">mod_ssl</span>, which will typically need to
241 class="fixed">/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>
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>
251 <li>If a Federation member sends or receives an Attribute Assertion
252 containing the InQueue policy uri and referencing one of the listed
254 the syntax and semantics of the associated attribute value should
256 to the definitions specified in the <a href="http://www.educause.edu/eduperson/">EduPerson specification 2002/10</a>
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>
264 <li>If a Federation member sends or receives an Attribute Assertion
265 containing the InQueue policy uri and referencing one of the listed
267 the syntax and semantics of the associated attribute value should
269 to the definitions specified in the relevant <a href="http://www/ietf.org">IETF</a> RFCs.
283 <li>preferredLanguage
287 <li>facsimileTelephoneNumber
296 <li>physicalDeliveryOfficeName
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
301 the syntax and semantics of the associated attribute value should
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".
313 <h4>3. Joining InQueue</h4>
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>
321 <li>Domain Name of the origin site (e.g., Ohio State's is
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 the <span class="fixed">providerID</span> attribute in the main <a href="http://SHIBBOLETHORIGINGUIDEURL#confShibbolethOriginConfig"><span class="fixed">ShibbolethOriginConfig</span></a> element or the InQueue <a href="http://SHIBBOLETHORIGINGUIDEURL#confRelyingParty"><span class="fixed">RelyingParty</span></a> element in <span class="fixed">origin.xml</span>.</li>
326 <li>Complete URL to access the Shibboleth Attribute Authority at the site.</li>
327 <li>The CN (usually the hostname) of the AA's certificate's subject.
328 This should also be the value of the <a href="http://SHIBBOLETHORIGINGUIDEURL#confFileResolver"><span class="fixed">FileResolver</span></a> element pointed to by <span class="fixed">AASigningCredential</span> attribute in the main <a href="http://SHIBBOLETHORIGINGUIDEURL#confShibbolethOriginConfig"><span class="fixed">ShibbolethOriginConfig</span></a> element or the InQueue <a href="http://SHIBBOLETHORIGINGUIDEURL#confRelyingParty"><span class="fixed">RelyingParty</span></a> element in <span class="fixed">origin.xml</span>.</li>
329 <li>Any shorthand aliases the WAYF should support for the origin
330 site (e.g., Ohio State, OSU, Buckeyes)</li>
331 <li>Contact names and addresses for technical and administrative
333 <li>The URL of an error page that users selecting this origin from
334 the WAYF may be referred to by targets if Shibboleth
335 malfunctions. (optional)</li>
336 <li>If the HS's certificate is not issueed by one of the root CAs
338 by InQueue, then it must be submitted in Base64-encoded DER (aka
340 <li>(optional) Briefly describe the organization's planned uses of Shibboleth.
343 <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
344 inqueue-support@internet2.edu</a> containing the following
345 information:</p></blockquote>
349 <li>The name of the organization</li>
350 <li>Contact names and addresses for both administrative and
351 technical purposes</li>
352 <li>The URL of all SHIRE services (specified using a shireURL attribute in a <a href="http://SHIBBOLETHTARGETGUIDEURL#confSessions"><span class="fixed">Sessions</span></a> element) set up for this organization.</li>
356 <h4>4. Configuration for Using InQueue</h4>
358 <blockquote><p>Once your site is accepted into and added to InQueue,
359 the following configuration parameters must be entered to ensure
360 interoperability and compliance with federation guidelines. Consult
361 the Shibboleth Deploy Guides for further information on these fields
362 and on <span class="fixed">origin.xml</span> and <span class="fixed">shibboleth.xml</span>.</p></blockquote>
364 <blockquote><h5>4.a. Origins:</h5>
365 <p>The following steps must be undertaken to configure a
366 standard Shibboleth origin configuration to use InQueue. Some
367 steps may vary or may be completed already depending on how
368 <span class="fixed">origin.xml</span> has already been
371 <li><a href="http://SHIBBOLETHORIGINGUIDEURL#confShibbolethOriginConfig"><span class="fixed">ShibbolethOriginConfig</span></a> must be modified as follows:
373 <li><span class="fixed">providerId</span> must be populated with a URI that will be assigned by InQueue when you are accepted into the federation.</li>
374 <li><span class="fixed">defaultRelyingParty</span> should be changed to <span class="fixed">urn:mace:inqueue</span>.</li>
376 <li>Uncomment the InQueue <a href="http://SHIBBOLETHORIGINGUIDEURL#confRelyingParty"><span class="fixed">RelyingParty</span></a> element, and within it, modify the <span class="fixed">providerId</span> to match the value assigned by InQueue to this origin.</li>
377 <li>A new <a href="http://SHIBBOLETHORIGINGUIDEURL#confKeyStoreResolver"><span class="fixed">KeyStoreResolver</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>
378 <li>Add a <a href="http://SHIBBOLETHORIGINGUIDEURL#confFederationProvider"><span class="fixed">FederationProvider</span></a> element for InQueue as follows:
379 <blockquote><span class="fixed">
380 <FederationProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadataLoadWrapper" uri="/conf/inqueue_sites.xml"/>
381 </span></blockquote></li>
385 <blockquote><h5>4.b. Targets:</h5>
387 <p>The following steps must be undertaken to configure a
388 standard Shibboleth origin configuration to use InQueue. Some
389 steps may vary or may be completed already depending on how
390 <span class="fixed">shibboleth.xml</span> has already been
391 modified. This guide covers modification of the default <a
392 href="http://SHIBBOLETHTARGETGUIDEURL#confApplications"><span
393 class="fixed">Applications</span></a> element from localhost
394 operation to InQueue operation for simplicity's sake.</p>
396 <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>
397 <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>
398 <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>
399 <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>
403 <blockquote><h5>4.c. Refreshing Federation Metadata:</h5>
404 <p>Shibboleth 1.2 includes metadata both for origin sites
405 and for target sites. The origin has the <a
406 href="http://SHIBBOLETHORIGINGUIDEURL#4.e."><span
407 class="fixed">metadatatool</span></a> and the target uses
408 the <a href="http://SHIBBOLETHTARGETGUIDEURL#4.g."><span
409 class="fixed">siterefresh</span></a> tool to maintain
410 locally cached versions of various files. Once your site
411 is accepted into the InQueue federation, it is necessary
412 that you periodically update the federation's metadata.
413 This metadata includes information used to identify and
414 authenticate InQueue sites. This should be frequently run
415 by adding it to a <span class="fixed">crontab</span> to
416 ensure that the data is fresh.</p>
418 <p>InQueue's metadata is digitally signed, so the first step is to obtain the InQueue signing certificate.
419 It can be downloaded from <span class="fixed">http://wayf.internet2.edu/InQueue/internet2.pem
420 </span> and has a fingerprint of:</p>
421 <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>
423 <p>The following commands can be used to obtain the federation's metadata for a Shibboleth <b>target</b>:</p>
424 <blockquote><span class="fixed">
425 $ cd /opt/shibboleth/etc/shibboleth<br>
426 $ ../../bin/siterefresh --url http://wayf.internet2.edu/InQueue/sites.xml --out sites.xml --cert internet2.pem<br>
427 $ ../../bin/siterefresh --url http://wayf.internet2.edu/InQueue/trust.xml --out trust.xml --cert internet2.pem</span>
430 <p>The following commands can be used to obtain the federation's metadata for a Shibboleth <b>origin</b>:</p>
431 <blockquote><span class="fixed">bin/metadatatool -i https://wayf.internet2.edu/InQueue/sites.xml -k conf/internet2.jks -p shib123 -a sitesigner -o /conf/sites.xml
436 <blockquote><p>A <a href="https://wayf.internet2.edu/InQueue/sample.jsp">sample shibboleth target</a>
437 is available for testing newly installed origin sites. New targets can make use of a sample origin,
438 which is listed as "Example State University" on the InQueue WAYF ( Username: demo / Password: demo ).</p></blockquote>