Implemented Bob's latest suggestions.
[java-idp.git] / doc / DEPLOY-GUIDE-ORIGIN.html
index 98f1b7c..740623d 100644 (file)
@@ -149,12 +149,9 @@ font-color: #121212;
     <center>
       <h2>Shibboleth Origin Deployment Guide</h2>
     </center>
-    Shibboleth Origin Deployment Guide<br>
-    draft-internet2-mace-shibboleth-shib-origin-deploy-30.html<br>
-    Nate Klingenstein<br>
-    12 June, 2003<br>
-    Comments should be directed to <a href=
-    "mailto:ndk@internet2.edu">ndk@internet2.edu</a>.<br>
+       Shibboleth Origin Deployment Guide<br>
+       Shibboleth Version 1.0<br />
+       June 19, 2003<br />
      
     <h3>This version of the deploy guide is for Shibboleth v1.0.  For
     documentation related to prior versions of Shibboleth, please
@@ -173,58 +170,89 @@ font-color: #121212;
     implementation of the architectural document, functional
     enhancements, and user interface improvements.</p>
 
-    <p>Functionality which has been added since the previous
-    version (v0.8) includes:</p>
-
-    <ul>
-      <li>
-        <p>Various improvements to error handling.  Origin sites are now
-        able to supply a URL to a federation for users to be referred to
-        when Shibboleth encounters a problem.  Targets will be able to
-        utilize this URL in error templates.</p>
-      </li>
-
-      <li>
-        <p>The SHAR may now store its session and attribute cache in a
-        back-end database in addition to the previously available
-        in-memory option.  The method by which <span
-        class="fixedwidth">sites.xml</span> is refreshed has been
-        modified to improve robustness.</p>
-      </li>
-
-      <li>
-        <p>Attribute acceptance policies have been greatly enhanced,
-        with filtering of attribute values by sites supported.</p>
-      </li>
-
-      <li>
-        <p>OpenSAML now populates <span
-        class="fixedwidth">AuthType</span> element in the SAML Subject
-        element using a value specified by origin sites using a
-        configuration directive.  This value describes the type of
-        authentication mechanism used at the origin site(e.g. Kerberos,
-        PKI, etc.). This value is made available on the target side as
-        another variable that may be used in authorization
-        decisions.</p>
-      </li>
-
-      <li>
-        <p>Origin sites whose HS certificate is not signed by one of a
-        federation's trusted roots are able to provide that federation
-        with the certificate; this cert can now be stored in the sites
-        metadata, and targets will be able to use this certificate to
-        validate the HS' signature.</p>
-      </li>
-
-      <li>
-        <p>The AA implementation has been improved with a powerful
-        attribute resolver.  This should greatly simplify the process of
-        configuring the AA to support additional general attributes,
-        while Java classes may still be written for more complex
-        evaluations.</p>
-      </li>
-
-    </ul>
+       <h4>Major New Features - 1.0</h4>
+       This new release contains many improvements and enhancements, including: 
+       
+       <h5>Federation Support</h5> 
+       <ol>
+               <li>
+               Federation and trust support has been substantially extended. Federation 
+               structures are now defined. The set of metadata collected and managed 
+               by each Federation is more fully defined. The configuration values 
+               assigned by a Federation are now identified. <br>
+               </li>
+               <li>
+               There is some support for targets to be members of multiple federations; 
+               this support will continue to evolve. When a browser user arrives, 
+               a target will determine which federation their origin belongs to, 
+               and then use the trust fabric associated with that Federation. <br>
+               </li>
+               <li>
+               Better support for flexible and bilateral trust agreements. A key 
+               specific to an origin site can be used to vallidate its signature. 
+               <br>
+               </li>
+
+               <li>
+               This version contains a significantly more mature security implementation, 
+               and should meet the security requirements of typical sites. <p></p>
+               </li>
+       </ol>
+
+       <h5>Origin</h5> 
+       <ol>
+
+               <li> The Attribute Authority has a powerful new attribute resolver. 
+               Simple scenarios (using a string attribute stored in ldap) can be 
+               accomplished by merely editing a configuration file. Java classes 
+               may still be written for more complex evaluations (eg retrieving information 
+               from multiple disparate repositories, and computing the SAML attribute 
+               using business rules). This should greatly simplify the process of 
+               configuring the AA to support additional general attributes.<br>
+               </li>
+       </ol>
+
+       <h5>Target</h5> 
+       <ol>
+               <li> Significantly more flexibility in configuring targets to ensure 
+               robustness. Failover and redundant configurations are now supported. 
+               <br>
+               <ol>
+                       <li>The SHAR may now optionally store its session and attribute 
+                       cache in a back-end database in addition to the previously available 
+                       in-memory option. This would allow a site to run an apache server 
+                       farm, with multiple SHARs, supporting the same set of sessions. 
+                       </li>
+                       <li>Federation supplied files (sites.xml and trust.xml) are now 
+                       refreshed in a much more robust manner. <br>
+                       </li>
+
+               </ol>
+               </li>
+               <li>Attribute acceptance policies have been greatly enhanced, and now 
+               supports filtering of attribute values by sites. <br>
+               </li>
+               <li>The SHAR can be configured to request specific attributes from the 
+               Origin. <br>
+               </li>
+       </ol>
+       <h5>Miscellaneous</h5> 
+       <ol>
+               <li>Origin sites can configure a value to describe the type of authentication 
+               mechanism used at the origin site(e.g. password, Kerberos, PKI, etc.). 
+               This value is made available on the target side as Shib-Authentication-Method. 
+               <br>
+               </li>
+               <li>Various improvements to error handling. Origin sites are now able 
+               to supply an &quot;error URL&quot; and contact information to a federation. 
+               When a target encounters an error, it can include this information 
+               in the error page. <br>
+
+               </li>
+               <li>Local time string values are now used in log files. <br>
+               </li>
+               <li>Internationalization support has been extended.</li>
+       </ol>
 
     <p>Before starting, please sign up for all applicable <a href=
     "http://shibboleth.internet2.edu/shib-misc.html#mailinglist">
@@ -372,6 +400,7 @@ font-color: #121212;
               certificate/key pairs between Apache and Java
               keystores</font> <font color="#5555EE">(optional)</font></a></li>
           <li><a href="#5.c."><font color="black">The Attribute Resolver</font></a></li>
+          <li><a href="#5.d."><font color="black">Local Error Page</font></a></li>
         </ol>
       </li>
 
@@ -1770,7 +1799,7 @@ font-color: #121212;
 
           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;Attribute
-          name=&quot;urn:mace:eduPerson:1.0:eduPersonScopedAffiliation&quot;&gt;<br>
+          name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;&gt;<br>
 
           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
@@ -1878,7 +1907,7 @@ font-color: #121212;
 
         <blockquote>
           <span class="fixedwidth">
-          &lt;Attribute name=&quot;urn:mace:eduPerson:1.0:eduPersonPrincipalName&quot;&gt;<br>
+          &lt;Attribute name=&quot;urn:mace:dir:attribute-def:eduPersonPrincipalName&quot;&gt;<br>
           &nbsp;&nbsp;&lt;AnyValue release=&quot;Permit&quot;&gt;<br>
           &lt;/Attribute&gt;<br>
           </span><br>
@@ -1888,7 +1917,7 @@ font-color: #121212;
          
         <blockquote>
           <span class="fixedwidth">
-          &lt;Attribute name=&quot;urn:mace:eduPerson:1.0:eduPersonScopedAffiliation&quot;&gt;<br>
+          &lt;Attribute name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;&gt;<br>
           &nbsp;&nbsp;&lt;Value release=&quot;deny&quot;&gt;member@example.edu&lt;/Value&gt;<br>
           &lt;/Attribute&gt;<br>
           </span><br>
@@ -1903,7 +1932,7 @@ font-color: #121212;
       <!-- ##To be included in future releases.  Not yet implemented.
       
       <p>There is also a special <span class="fixedwidth">AttributeIdentifier</span>
-      element that allows internal references to the an attribute
+      element that allows internal references to an attribute
       within an ARP.  This is useful for quickly applying multiple
       rules to the same target.  It is used as follows:</p>
 
@@ -1918,8 +1947,7 @@ font-color: #121212;
           &nbsp;&nbsp;&nbsp;&nbsp;&lt;/Target&gt;<br>
           
           &nbsp;&nbsp;&nbsp;&nbsp;&lt;Attribute
-          name=&quot;urn:mace:eduPerson:1.0:
-          eduPersonScopedAffiliation&quot;&gt;<br>
+          name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;&gt;<br>
 
           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;Value
           release=&quot;permit&quot;&gt;member@example.edu&lt;/Value
@@ -1931,7 +1959,7 @@ font-color: #121212;
           
           &nbsp;&nbsp;&lt;AttributeReference identifier=&quot;http://www.example.edu/attributes/attribute1&quot;&gt;<br>
 
-          &nbsp;&nbsp;&lt;Attribute name=&quot;urn:mace:eduPerson:1.0:eduPersonAffiliation&quot; identifier=&quot;http://www.example.edu/attributes/attribute1&quot;&gt;<br>
+          &nbsp;&nbsp;&lt;Attribute name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot; identifier=&quot;http://www.example.edu/attributes/attribute1&quot;&gt;<br>
 
           &nbsp;&nbsp;&nbsp;&nbsp;&lt;Value release=&quot;permit&quot;&gt;student@example.edu&lt;Value&gt;<br>
 
@@ -2298,12 +2326,6 @@ font-color: #121212;
           Shibboleth.  Contained within the <span
           class="fixedwidth">SimpleAttributeDefinition</span>
           element.</p>
-
-          <p>Attributes are named in the format <span
-          class="fixedwidth">&lt;URI&gt;#&lt;attributename&gt;</span>;
-          for example, <span
-          class="fixedwidth">urn:mace:dir:eduperson#
-          eduPersonScopedAffiliation</span>.</p>
         </dd>
 
         <dd class="attributeopt">
@@ -2387,9 +2409,9 @@ font-color: #121212;
       look like:</p>
 
       <blockquote><span class="fixedwidth">
-        &lt;SimpleAttributeDefinition id=&quot;urn:mace:dir:eduperson#eduPersonPrincipalName&quot; smartScope=&quot;shibdev.edu&quot; sourceName=&quot;universityPerson&quot;&gt;<br>
+        &lt;SimpleAttributeDefinition id=&quot;urn:mace:dir:attribute-def:eduPersonPrincipalName&quot; smartScope=&quot;shibdev.edu&quot; sourceName=&quot;universityPerson&quot;&gt;<br>
           &nbsp;&nbsp;&lt;DataConnectorDependency requires=&quot;dataConnector&quot;/&gt;<br>
-          &nbsp;&nbsp;&lt;AttributeDependency requires=&quot;urn:mace:dir:eduperson#eduPersonAffiliation&quot;/&gt;<br>
+          &nbsp;&nbsp;&lt;AttributeDependency requires=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;/&gt;<br>
              &nbsp;&nbsp;&lt;cacheTime=&quot;600&quot;/&gt;&lt;br&gt;<br>
              &nbsp;&nbsp;&lt;lifeTime=&quot;3600&quot;/&gt;&lt;br&gt;<br>
            &lt;/SimpleAttributeDefinition&gt;
@@ -2402,7 +2424,7 @@ font-color: #121212;
       <blockquote><span class="fixedwidth">
          &lt;AttributeResolver xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; xmlns=&quot;urn:mace:shibboleth:resolver:1.0&quot; xsi:schemaLocation=&quot;urn:mace:shibboleth:resolver:1.0 shibboleth-resolver-1.0.xsd&quot;&gt;<br>
             <br>
-            &nbsp;&nbsp;&lt;SimpleAttributeDefinition id=&quot;urn:mace:dir:eduperson#eduPersonPrincipalName&quot; smartScope=&quot;shibdev.edu&quot;&gt;<br>
+            &nbsp;&nbsp;&lt;SimpleAttributeDefinition id=&quot;urn:mace:dir:attribute-def:eduPersonPrincipalName&quot; smartScope=&quot;shibdev.edu&quot;&gt;<br>
                    &nbsp;&nbsp;&nbsp;&nbsp;&lt;DataConnectorDependency requires=&quot;echo&quot;/&gt;<br>
              &nbsp;&nbsp;&lt;/SimpleAttributeDefinition&gt;<br>
             <br>
@@ -2414,6 +2436,20 @@ font-color: #121212;
       <p>There are additional examples of <span class="fixedwidth">resolver.xml</span> files provided in the <a href="http://marsalis.internet2.edu/cgi-bin/viewcvs.cgi/shibboleth/java/src/conf/">Shibboleth CVS</a>.</p>
 
     </blockquote>
+    <br>
+    <h4><a name="5.d."></a>5.d. Local Error Page</h4>
+    <blockquote>
+               <p>Origin sites are encouraged to provide federations with the 
+               URL of a local Shibboleth error page. If a browser user from the 
+               origin site encounters a problem at a shibbolized target, the target 
+               is likely to display an error page that includes a link back to this 
+               origin provided page.</p>
+
+               <p>The page should provide information on how to obtain local support 
+               for using Shibbolized resources. It might also include suggestions on 
+               what information should be recorded before beginning the problem 
+               resolution process.</p> 
+    </blockquote>
 
     <br>
     <br>
@@ -2438,8 +2474,8 @@ font-color: #121212;
     <blockquote>
       <p>Internet2 provides a basic target that can be used to test
       origin setup functionality. After your origin is recognized
-      by InCommon, simply use any browser to access <a href=
-      "https://wayf.internet2.edu/shibboleth/sample.jsp">https://wayf.internet2.edu/shibboleth/sample.jsp</a>.
+      by InQueue, simply use any browser to access <a href=
+      "https://wayf.internet2.edu/InQueue/sample.jsp">https://wayf.internet2.edu/InQueue/sample.jsp</a>.
       Select your origin's name and follow the login process as a
       user would. Note that SSL must be used, and both the HS and
       AA must be fully configured.</p>
@@ -2458,16 +2494,15 @@ font-color: #121212;
     <blockquote>
       <p>Shibboleth's origin components log various operations
       which may prove useful for auditing, testing, and security
-      purposes. This data is sent through <span class="fixedwidth">log4j</span>'s standard
-      mechanism.  The location of
+      purposes. This data is sent through <span class="fixedwidth">log4j</span>'s
+      standard mechanism. The location of
       the log file, the level at which the log is output, the
       formatting of the logs, and many more options may be
       configured by editing
-      <span class="fixedwidth">/WEB-INF/classes/conf/log4j.properties</span>. By default, it is
-      setup to log to the console of the servlet container, with a
+      <span class="fixedwidth">/WEB-INF/classes/conf/log4j.properties</span>. By default,
+      it is setup to log to the console of the servlet container, with a
       level of <span class="fixedwidth">WARN</span>, but there is also a commented out
-      example in the file to give a possible alternate
-      configuration.</p>
+      example in the file to give a possible alternate configuration.</p>
     </blockquote>
 
     <h4><a name="6.c."></a>6.c. Common Problems</h4>