-
- <h4><a name="2.i."></a>2.i. Other Considerations</h4>
-
- <blockquote>
- <p>Especially for higher education, there are a handful of
- laws enacted which may have important ramifications on the
- disclosure of personal information and attributes. Since
- Shibboleth does not necessarily need to transmit identity, it
- is an ideal solution for many higher education situations.
- Nevertheless, all parties within the United States of America
- are strongly advised to consult the <a href=
- "http://www.ed.gov/offices/OM/fpco/ferpa/">Family Educational
- Rights and Privacy Act of 1974(FERPA)</a>, and all other
- relevant state and federal legislation before deploying
- Shibboleth.</p>
- </blockquote>
- <br>
- <br>
- <hr>
- <br>
-
-
- <h3><a name="3."></a>3. Installation</h3>
-
- <h4><a name="3.a."></a>3.a. Software Requirements</h4>
-
- <p><b>The following requirements are primarily recommendations
- based on the most common ways to run Shibboleth. However, the
- origin should be able to run under any servlet container
- supporting <span class="fixedwidth">Servlet API v2.3</span> and <span class="fixedwidth">JSP specification
- 1.2</span>.</b></p>
-
- <blockquote>
- <ul type="circle">
- <li><a href=
- "http://http://www.apache.org/dist/httpd/">Apache
- 1.3.26+ (<2.0)</a></li>
-
- <li><a href="http://jakarta.apache.org/tomcat/">Tomcat
- 4.1.18-24 LE Java server</a></li>
-
- <li>
- <a href="http://java.sun.com/j2se/">Sun J2SE JDK v1.4.1_01 and above</a>
-
- <blockquote>
- <p>Other versions of the JRE are not supported and are
- known to cause errors when working with
- certificates.</p>
- </blockquote>
- </li>
-
- <li>
- mod_jk
-
- <blockquote>
- <p>You may need to build mod_jk against Apache, which
- will generally require GCC or a platform-specific C
- compiler.</p>
- </blockquote>
- </li>
-
- <li>
- An enterprise authentication mechanism
-
- <blockquote>
- <p>Ideally, this will be a WebISO or SSO system such as
- <a href= "http://pubcookie.org/">Pubcookie</a>. The
- minimal requirement is for the web server to be able to
- authenticate browser users and supply their identity to
- the Handle Server.</p>
- </blockquote>
- </li>
-
- <li>
- An enterprise directory service
-
- <blockquote>
- <p>Shibboleth currently supports retrieving user
- attribute information from an <a href=
- "http://www.openldap.org">LDAP</a> directory. For
- testing purposes, Shibboleth also supports a minimal
- echo responder which will always return pre-defined
- attributes.</p>
- </blockquote>
- </li>
- </ul>
- </blockquote>
-
- <h4><a name="3.b."></a>3.b. Deploy HS and AA</h4>
-
- <blockquote>
- <ol type="1">
- <li>
- <p>Ensure you have already obtained the proper <a href=
- "http://shibboleth.internet2.edu/release/shib-download.html">.tarball</a>.</p>
- </li>
-
- <li>
- <p>The archive will expand into a <span class="fixedwidth">shibboleth-origin-1.0/</span>
- directory(<span class="fixedwidth">/opt/</span> recommended).</p>
- </li>
-
- <li>
- <p>Run the following command to move the Java files into
- Tomcat's tree:</p>
-
- <blockquote>
- <span class="fixedwidth">cp /opt/shibboleth-origin-1.0/dist/shibboleth.war
- /usr/local/tomcat/webapps/</span>
- </blockquote>
- </li>
-
- <li>
- <p>Tomcat 4.1.x requires that several Java jarfiles used
- by Shibboleth be located in a special "endorsed" folder to
- override obsolete classes that Sun includes with their JVM.
- To deal with this problem use the following command, adjusting
- paths as needed:</p>
- <blockquote>
- <span class="fixedwidth">$ cp /opt/shibboleth-origin-1.0/endorsed/*.jar /usr/local/tomcat/common/endorsed</span>
- </blockquote>
- <p>Different versions of Tomcat or other Java servers may have
- other locations in which to place these files or deal with this
- problem. Refer to your application server's documentation to
- find out how to properly endorse classes, if necessary.</p>
- </li>
-
- <li>
- <p>Restart Tomcat, which will automatically detect that
- there has been a new .war file added. This file will by
- default be expanded into
- <span class="fixedwidth">/usr/local/tomcat/webapps/shibboleth</span>.</p>
- </li>
-
- <li>
- <p>Apache must be told to map the URL's for the
- Shibboleth HS and AA to Tomcat. Two popular ways of doing
- this are to include the following text directly in
- <span class="fixedwidth">httpd.conf</span>, or to place <span class="fixedwidth">Include
- conf/mod_jk.conf</span> in <span class="fixedwidth">httpd.conf</span>, and place
- the following lines in
- <span class="fixedwidth">/etc/httpd/conf/mod_jk.conf</span>:</p>
-
- <blockquote>
- <span class="fixedwidth">--------- begin ---------<br>
- <IfModule !mod_jk.c><br>
- LoadModule jk_module libexec/mod_jk.so<br>
- </IfModule><br>
- <br>
- JkWorkersFile
- "/usr/local/tomcat/conf/jk/workers.properties"<br>
- JkLogFile "/usr/local/apache/logs/mod_jk.log"<br>
- <br>
- JkLogLevel emerg<br>
- <br>
- JkMount /shibboleth/* ajp13<br>
- <br>
- --------- end ---------</span>
- </blockquote>
- </li>
-
- <li>
- <p>Tomcat's <span class="fixedwidth">/conf/server.xml</span>
- ships by default with the Coyote/JK2 connector enabled, which
- fails with Shibboleth due to the lack of support for <span
- class="fixedwidth">REMOTE_USER</span>. This connector must be
- commented out. Then, uncomment and modify the traditional AJP
- 1.3 connector as follows:</p>
-
- <ol type="A">
- <li>
- <p>Add <span class="fixedwidth">address="127.0.0.1"</span> inside the
- <span class="fixedwidth"><Ajp13Connector></span> configuration
- element to prevent off-host access.</p>
- </li>
-
- <li>
- <p>Add <span class="fixedwidth">tomcatAuthentication="false"</span> to the
- <span class="fixedwidth"><Ajp13Connector></span> configuration element
- to ensure that the user's identity is passed from
- Apache to the servlet environment.</p>
- </li>
- </ol>
- </li>
- <li>
- <p>It is <b>strongly</b> recommended that the AA be SSL-protected to protect attributes in transit. To do so, add an appropriate location block to <span class="fixedwidth">httpd.conf</span>:</p>
- <blockquote><span class="fixedwidth">
- <Location /shibboleth/AA>
- SSLVerifyClient optional
- SSLOptions +StdEnvVars +ExportCertData
- </Location>
- </span></blockquote>
- </li>
- </ol>
- </blockquote>
- <br>
- <hr>
- <br>
-
-
- <h3><a name="4."></a>4. Getting Running</h3>
-
- <h4><a name="4.a."></a>4.a. Basic Configuration</h4>
-
- <blockquote>
- <p><b>This section of the deploy guide specifies only the
- essential changes that need to be made to the configuration
- defaults for the origin to function successfully in a
- federated environment. More complex configuration will likely
- be required for many applications and federations; for a full
- description of every field in <span
- class="fixedwidth">origin.properties</span>, please refer to
- <a href="#5.a.">section 5.a</a>.</b></p>
-
- <p>The main configuration file for Shibboleth's origin side is
- located in
- <span class="fixedwidth">/webapps/shibboleth/WEB-INF/classes/conf/origin.properties.</span>. This file contains configuration information
- for the origin side in several sections. The configuration
- must be consistent with values elsewhere in the deployment,
- such as the <a href="#4.c.">HS' certificate</a> and with
- directory access bindings, etc., or access errors may occur.</p>
-
- <p>All pathnames are relative, and have an effective root
- path of
- <span class="fixedwidth">$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/</span>. To
- specify files outside of the webapp, specify a full URI, such
- as <span class="fixedwidth">file:///usr/local/shibboleth/</span>.</p>
-
- <ol type="1">
- <li><span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.issuer
- = <domain name></span>
- <blockquote>This will be, in most cases, the DNS name of the machine on which the HS runs. It must match the CN of the certificate used below.</blockquote>
- </li>
- <li><span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName
- = <URI></span>
- <blockquote>The value of this must entered as assigned by the
- federation used for testing or initial operation.</blockquote>
- </li>
- <li><span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl
- = <url></span>
- <blockquote>This will be the URL assigned the AA servlet in
- step <a href="#3.b.">3.b</a>. Note that this <b>must</b> be
- an <span class="fixedwidth">https://</span> URL in order for
- the AA to know which SHAR is requesting
- attributes.</blockquote>
- </li>
- <li>
- <ul type="circle">
- <li><span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath
- = <pathname></span></li>
- <li><span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword
- = <password></span></li>
- <li><span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias
- = <alias></span></li>
- <li><span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword
- = <password></span></li>
- <li><span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias
- = <alias></span></li></ul>
-
- <blockquote>Respectively, the location and password of
- the Java keystore containing the x.509 certificate and
- matching private key to be used by the HS, the alias
- and password of the private key, and the optional
- certificate alias, if it differs from the key's
- alias.</blockquote>
- </li>
- <li><span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.AAServlet.authorityName
- = <domain name></span>
-
- <blockquote>Specifies the name of the AA, which is typically
- the domain name of the server running it.</blockquote></li>
-
- <li><span class="fixedwidth">edu.internet2.middleware.shibboleth.audiences
- = <URI></span>
-
- <blockquote>This section must contain the URI of the
- federation under which the origin will operate or test
- initially. This will be provided by the
- federation.</blockquote></li>
- </ol>
- </blockquote>
- <br>
-
- <h4><a name="4.a.i"></a>4.a.i Modifying the default Attribute Resolver configuration</h4>
- <blockquote>
- <p>The resolver.xml file controls the retrieval of attributes from enterprise repositories, and the process of mapping them to Shibboleth/SAML attributes. For more precise information regarding how attributes are processed or syntactically formed, please refer to section <a href="#5.d.">5.d.</a></p>
-
- <p>In order to make the Shibboleth software operational, however, minor edits must be made to the example version of the resolver.xml file. The file can be found at <span class="fixedwidth">/webapps/shibboleth/WEB-INF/classes/conf/resolver.xml.</span> Two changes are necessary:</p>
-
- <p>1. The value of the smartScope attribute should be changed to the Domain Name value submitted to the Federation. It appears on two SimpleAttributeDefinition elements: eduPersonScopedAffiliation and eduPersonPrincipalName.</p>
-
- <p>2. The comment indicators should be removed from around the definitions of those two elements ( <!-- and --> ).</p>
-
- </blockquote>
-
-<br>
-
- <h4><a name="4.b."></a>4.b. Key Generation and Certificate
- Installation</h4>
-
- <blockquote>
- <p>The SAML messages generated by the HS must be digitally
- signed. Each HS must be issued a private and public keypair,
- which is stored in a Java keystore. The current
- implementation of Shibboleth requires the use of an ordinary
- file-based keystore. The keytool program is included with the
- Java development and runtime kits. Access parameters to the
- keystore will need to be consistent with those specified in
- <span class="fixedwidth">origin.properties</span>.</p>
-
- <p>A sample keystore is included in the distribution and can
- be found in
- <span class="fixedwidth">/usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf/keystore
- .jks</span> with a password of <span class="fixedwidth">shibhs</span>. It is intended
- to serve as an example and not as a production keystore.</p>
-
- <p>The following commands will generate a new RSA keypair and
- store it in the <span class="fixedwidth">keystore.jks</span> file, with a keyentry
- alias of <span class="fixedwidth">hs</span> and new passwords of your choosing:</p>
-
- <blockquote>
- <span class="fixedwidth">$ cd
- /usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf<br>
- $ keytool -storepasswd -keystore keystore.jks -new
- <newpassword><br>
- $ keytool -genkey -keystore keystore.jks -alias hs -keyalg
- rsa -keysize 2048<br>
- </span>
- </blockquote>
-
- <p>You will be prompted for passwords during key generation
- as needed, to access the keystore and assign the key itself
- its own password. You will also be prompted for the
- distinguished name components to associate with the key. This
- DN will be placed in a self-signed certificate and will be
- the name that is associated with your HS by Shibboleth. In
- particular, the first component you enter for Name will be
- the <span class="fixedwidth">Common Name</span>(when keytool asks for first and last
- name, common name is intended), which in most cases should be
- the hostname of the HS system. Note that a specific federation of
- sites may dictate what type of key algorithm, key size, or
- validity period is appropriate.</p>
-
- <p>Once you have a keypair generated, the self-signed certificate
- must be replaced with a certificate signed by a CA acceptable to
- the federation you will be joining. Shibboleth is generally able to
- climb trust chains to reach an intermediate CA's root CA. Note
- that the intermediate CA's signing certificate must still be
- signed by a root CA recognized by the federation.</p>
-
- <p>To generate a certificate signing request for a CA, use
- the following command:</p>
-
- <blockquote>
- <span class="fixedwidth">$ keytool -certreq -keystore keystore.jks -alias hs
- -file <csr-file><br>
- </span>
- </blockquote>
-
- <p>The contents of <span class="fixedwidth"><csr-file></span> can then be sent
- to a CA for signing. You will receive a signed certificate in
- return in a file. To install the new certificate into your
- keystore, use the following command:</p>
-
- <blockquote>
- <span class="fixedwidth">$ keytool -import -keystore keystore.jks -alias hs
- -file <cert-file></span>
- </blockquote>
-
- <p>Note that if the signing CA's certificate is not already
- installed in your keystore as a trusted signer, you may need
- to download the CA's root certificate and import it into the
- keystore file under a different alias, using a command
- similar to the above.</p>
-
- <p>For information on sharing certificate/key pairs between Apache
- and Java keystores see section <a href="#5.c.">5.c.</a>.</p>
- </blockquote>
-
- <h4><a name="4.c."></a>4.c. Linking the Authentication System
- to the HS</h4>
-
- <blockquote>
- <p>The interaction between the HS and the local authentication
- system is implemented by supplying the HS with the identity of
- the browser user. Most often, this will mean protecting the HS
- servlet with some form of local authentication that populates
- <span class="fixedwidth">REMOTE_USER</span>. Location blocks can be added to
- <span class="fixedwidth">httpd.conf</span>, associating the appropriate
- authentication mechanism with the URL of the HS servlet. The
- following example demonstrates association of a very basic
- authentication method with the HS:</p>
-
- <blockquote>
- <span class="fixedwidth"><Location /shibboleth/HS><br>
- AuthType Basic<br>
- AuthName "Internet2 Handle Service"<br>
- AuthUserFile /usr/local/apache/conf/user.db<br>
- require valid-user<br>
- </Location><br>
- </span>
- </blockquote>
-
- <p>Note that .htaccess files cannot be used for this purpose
- because URL's are "virtualized" by Tomcat.</p>
-
- <p>It is recommended that the origin be tested at the end of
- this process using the process described in section <a href=
- "#6.a.">6.a</a>.</p>
- </blockquote>
-
- <h4><a name="4.c.i."></a>4.c.i. Enabling client certificate
- authentication <font color="#5555EE">(optional)</font></h4>
-
- <blockquote>
- <blockquote>
-
- <p>Shibboleth supports client certificate authentication by
- utilization of a filter that relies on the web server to do all
- processing to ensure that the certificate is both valid and
- appropriate for the application. An example deployment descriptor
- is included with the Shibboleth distribution at <span
- class="fixedwidth">$SHIB_HOME/webAppConfig/origin-client-cert.xml</span>.
- To enable the filter, add the following to the deployment
- descriptor (<span class="fixedwidth">web.xml</span>):</p>
-
- <blockquote>
- <span class="fixedwidth"> <filter><br>
- <filter-name><br>
- Client Cert AuthN Filter<br>
- </filter-name><br>
- <filter-class><br>
- edu.internet2.middleware.shibboleth.utils.ClientCertTrustFilter<br>
- </filter-class><br>
- </filter><br>
- <br>
- <br>
- <filter-mapping><br>
- <filter-name><br>
- Client Cert AuthN Filter<br>
- </filter-name><br>
- <url-pattern><br>
- /HS<br>
- </url-pattern><br>
- </filter-mapping><br></span>
- </blockquote>
-
- <p>By default, the filter pulls the principal name out of the <span
- class="fixedwidth">CN</span> of the cert's <span
- class="fixedwidth">Subject</span> by using regular expression
- grouping. This may be done using patterns such as:</p>
-
- <blockquote>
- <span class="fixedwidth">regex: '.*CN=([^,/]+).*' match group: 1</span>
- </blockquote>
-
- <p>The servlet filter will accept two initialization parameters,
- <span class="fixedwidth">regex</span> and <span
- class="fixedwidth">matchGroup</span> that can be used to extract
- the principal name differently.</p>
-
- </blockquote>
- </blockquote>
-
- <h4><a name="4.d."></a>4.d. Establishing default ARP's for the
- origin community</h4>
-
- <p><b>For a more basic introduction to ARP's, please refer to
- section <a href="#2.e.">2.e</a>.</b></p>
-
- <blockquote>
- <p>An ARP determines which attributes are released to a SHAR
- when a user tries to access a resource. It acts as a sort of
- filter on user information contained in the authoritative
- directory, deciding what can be released to whom, but not
- modifying or creating information itself. ARP's are generally
- administered by the site, but Shibboleth will provide for users to
- broker control of their own information and privacy by
- allowing them to create ARP's pertaining to themselves.</p>
-
- <p>It is recommended that a set of policies be established
- between an origin and frequently accessed targets to specify
- default releases of expected attributes. Federation guidelines may
- provide more information on population of ARP's.</p>
-
- <p>Currently, there is no direct mechanism for users to create
- their own ARP's besides direct XML writing. In future
- versions, a GUI will be provided for simpler management of
- ARP's. Care should be given to balancing giving sufficient
- control over information to users and avoiding access
- problems. For example, users may decide to restrict the
- release of their personal information to such a degree that
- access to a site for a class may become impossible because
- Shibboleth cannot release enough information to grant
- access.</p>
-
- <p>The Shibboleth distribution contains an example site arp that
- releases the eduPersonScopedAffiliation attribute to all targets. For
- more precise information regarding how ARP's are processed or
- syntactically formed, please refer to section <a href="#5.b.i.">5.b.i</a>.</p>
- </blockquote>
-
- <br>
- <hr>
- <br>
-
- <h3><a name="5."></a>5. Advanced Configuration</h3>
-
- <h4><a name="5.a."></a><span class="fixedwidth">origin.properties</span></h4>
-
- <blockquote>
- <p>The main configuration file for Shibboleth's origin side is
- located in
- <span class="fixedwidth">/webapps/shibboleth/WEB-INF/classes/conf/origin.properties.</span>. This file contains configuration information
- for the origin side in several sections. The configuration
- must be consistent with values elsewhere in the deployment,
- such as the <a href="#4.c.">HS' certificate</a> and with
- directory access bindings, etc., or access errors may occur.</p>
-
- <p>All pathnames are relative, and have an effective root
- path of
- <span class="fixedwidth">$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/</span>. To
- specify files outside of the webapp, specify a full URI, such
- as <span class="fixedwidth">file:///usr/local/shibboleth/</span>.</p>
-
- <p>Fields that are purple are optional; grey fields are
- mandatory.</p>
-
- <p>These are the variables that may be specified for each
- component of <span class="fixedwidth">origin.properties</span>:</p>
-
- <br>
- <p>General Configuration:</p>
-
- <dl>
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.issuer
- = <domain name></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the DNS name the HS should use for
- itself in issuing assertions.</p>
- </dd>
-
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName
- = <URI></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the the <span
- class="fixedwidth">URI</span> to use as the name of
- the origin site as a whole. This field is primarily
- meant to be populated in the context of the federation
- in which the origin site resides, is intended to be
- globally unique, and will typically be assigned by the
- federation.</p>
- </dd>
-
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl
- = <url></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the <span class="fixedwidth">URL</span>
- at which the HS' corresponding AA may be contacted.
- Note that this <b>must</b> be an <span
- class="fixedwidth">https://</span> URL in order for
- the AA to know which SHAR is requesting
- attributes.</p>
- </dd>
-
- <dd class="attributeoptlong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.username
- = <var></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the HTTP request header that should be used
- to acquire the user's principal name from the
- authentication service. Defaults to <span
- class="fixedwidth">REMOTE_USER</span>.</p>
- </dd>
-
- <dd class="attributeoptlong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.authMethod
- = <uri></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifes the URI used to populate <span
- class="fixedwidth">AuthenticationMethod</span> in the SAML
- attribute assertion. This corresponds to the method used
- to authenticate users by the authentication service used
- by the HS. Some common authentication methods and
- corresponding URI's are listed below; for a complete list,
- please consult section 7.1 of the SAML 1.1 core
- specifications or your federation's guidelines.</p>
- <table border=2 cellpadding=0 cellspacing=0>
- <tr>
- <td><span class="fixedwidth">urn:oasis:names:tc:SAML:1.0:am:password</span></td>
- <td>The authentication was performed using a password.</td>
- </tr>
- <tr>
- <td><span class="fixedwidth">urn:ietf:rfc:1510</span></td>
- <td>The authentication was performed using Kerberos.</td>
- </tr>
- <tr>
- <td><span class="fixedwidth">urn:oasis:names:tc:SAML:1.0:am:X509-PKI</span></td>
- <td>The authentication was performed using a
- certificate and key issued to the end user. More
- specific forms of PKI authentication such as SPKI and
- XKMS are also assigned URN's in the SAML specs.</td>
- </tr>
- </table>
- </dd>
- </dl>
-
- <br>
- <p>Assertion Signing:</p>
-
- <dl>
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath
- = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the location of the Java keystore
- containing the x.509 certificate and matching private
- key to be used by the HS.</p>
- </dd>
-
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword
- = <password></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the password to the referenced
- keystore.</p>
- </dd>
-
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias
- = <alias></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the alias used for accessing the private
- key.</p>
- </dd>
-
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword
- = <password></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the password used to retrieve the private key.</p>
- </dd>
-
- <dd class="attributeoptlong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias
- = <alias></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the alias for the certificate
- corresponding to the private key used by the HS.
- Defaults to the private key's alias.</p>
- </dd>
- </dl>
- <br>
-
- <p>General AA Configuration:</p>
-
- <dl>
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.AAServlet.authorityName
- = <domain name></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the name of the AA, which is typically
- the domain name of the server running it.</p>
- </dd>
-
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.AAServlet.passThruErrors
- = <true/false></span>
- </dd>
-
- <dd class="value">
- <p>Specifies whether the AA should pass on internal errors
- to the SHAR for debugging purposes. Defaults to <span
- class="fixedwidth">false</span>.</p>
- </dd>
- </dl>
-
- <p>AA Attribute Resolution:</p>
-
- <dl>
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.attrresolv.AttributeResolver.ResolverConfig
- = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the location of the configuration file
- for the resolver the AA uses to build attributes.
- Defaults to <span
- class="fixedwidth">/conf/resolver.xml</span>. For
- information on how to configure and use the attribute
- resolver, consult section <a href="4.e.">4.e</a>.</p>
- </dd>
- </dl>
-
- <p>ARP Configuration:</p>
-
- <dl>
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.ArpRepository.implementation
- = <string></span>
- </dd>
-
- <dd class="value">
- <p>References the type of ARP repository implemented.
- Shibboleth provides a built-in ARP repository
- specified by
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.
- provider.FileSystemArpRepository</span>.</p>
-
- <p>Note that the set of principals that an ARP applies
- to is not expressed by the ARP itself, but rather the
- implementation of the ARP repository. For example, if
- the ARP repository were implemented in LDAP, the ARP's
- that apply to a user would be attributes of that
- user's personal LDAP entry, and the site ARP would be
- an attribute of an entry representing the site. While
- not performed by the built-in ARP repository, a
- repository implementation might also implement group
- ARP's; for example, in an LDAP directory, the user
- entry might have some group membership attributes that
- refer to group entries, and those group entries would
- have ARP attributes, and all those ARP's would be
- applicable.</p>
- </dd>
-
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path
- = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the relative or absolute path to the
- folder containing the ARP files.</p>
- </dd>
-
- <dd class="attributeoptlong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.ArpTTL
- = <seconds></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the duration in <span
- class="fixedwidth">seconds</span> that ARP's may be
- cached by the AA. Defaults to <span
- class="fixedwidth">0</span>, or no caching.</p>
- </dd>
- </dl>
-
- <p>Handle Repository Configuration:</p>
-
- <dl>
- <dd class="attributeoptlong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleRepository.implementation
- = <string></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the method by which the HS and AA share
- handles. These are by default passed by memory(which
- can be specified explicitly using
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.
- MemoryHandleRepository</span>), and may also be passed
- using symmetric encryption with
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository</span>.</p>
- </dd>
- </dl>
-
- <p>edu.internet2.middleware.shibboleth.hs.provider.
- MemoryHandleRepository <font color="#5555EE">(specify
- if
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleRepository.
- implementation</span> is <span class="fixedwidth">MemoryHandleRepository</span>)</font></p>
-
- <blockquote>
- <dl>
- <dd class="attributeoptlong">
-<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.BaseHandleRepository.handleTTL
- = <seconds></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the time in <span
- class="fixedwidth">seconds</span> for which issued handles
- are valid. Defaults to <span
- class="fixedwidth">1800</span>, or 30 minutes. The time
- should be long enough to allow for clock skew and short
- enough to protect against various attacks. Consult your
- federation guidelines for further advice.</p>
- </dd>
- </dl>
- </blockquote>
-
- <p>edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository <font color="#5555EE">(specify
- if
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleRepository.
- implementation</span> is <span class="fixedwidth">CryptoHandleRepository</span>)</font></p>
-
- <p>In order to use the crypto repository implementation, you must
- have a <span class="fixedwidth">DESede</span> secret key in a
- keystore of type <span class="fixedwidth">JCEKS</span>. The
- origin distribution includes a program that will automatically
- generate such a key. In order to invoke it, run <span
- class="fixedwidth">./ant genSecret</span>, which will create a
- keystore in <span
- class="fixedwidth">$SHIB_HOME/src/conf/handle.jks</span> that
- includes the key, with an alias of <span
- class="fixedwidth">handleKey</span> and a password of <span
- class="fixedwidth">shibhs</span>. If <span
- class="fixedwidth">./ant dist</span> is run subsequently, this
- keystore will be included in the webapp archive that is
- created.</p>
-
- <blockquote>
- <dl>
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePath
- = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the path to the keystore containing the
- key used to encrypt passed principal identifiers.</p>
- </dd>
-
- <dd class="attributelong">
-<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePassword
- = <password></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the password for the keystore.</p>
- </dd>
-
- <dd class="attributelong">
-<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyAlias
- = <password></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the alias for the appropriate encryption
- key within the keystore.</p>
- </dd>
-
- <dd class="attributelong">
-<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyPassword
- = <password></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the password used to retrieve the key.</p>
- </dd>
-
- <dd class="attributeoptlong">
-<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.CryptoHandleRepository.handleTTL
- = <seconds></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the time in <span
- class="fixedwidth">seconds</span> for which issued handles
- are valid. Defaults to <span
- class="fixedwidth">1800</span>, or 30 minutes. The time
- should be long enough to allow for clock skew and short
- enough to protect against various attacks. Consult your
- federation guidelines for further advice.</p>
- </dd>
-
- </dl>
- </blockquote>
-
- <p>Federation Configuration:</p>
-
- <dl>
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.audiences
- = <URI's></span>
- </dd>
-
- <dd class="value">
- <p>Specifies a list of <span
- class="fixedwidth">URI</span>'s that will be used for
- the <span class="fixedwidth">Audience</span> field of
- the SAML attribute assertion. All URI's listed will
- be sent with any assertion issued by the AA. These
- URI's are defined and provided by and correspond to
- federations.</p>
-
- <p>Note that the values of the URI's here <b>must</b>
- match one of the policy URI's accepted by the
- receiving target in the <span
- class="fixedwidth">[policies]</span> section of <span
- class="fixedwidth">shibboleth.ini</span> or
- interoperation will fail by design.
- </dd>
- </dl>
-
- </blockquote>
- <br>
-
- <h4><a name="5.b."></a>5.b. ARP Overview</h4>
-
- <blockquote>
- <h5>This section applies primarily to the syntactic and
- technical details of ARP's. For basic information on and
- explanation of what an ARP is and how it should be managed,
- please refer to sections <a href="#2.e.">2.e</a> and <a href=
- "#4.d.">4.d</a>.</h5>
-
- <p>Every ARP file contains one ARP. ARP's may be specified either
- as the site ARP or user ARP's. The site ARP pertains to every
- principal for whom the AA retrieves information; a user ARP
- applies only to the individual user for whom it is defined. The
- set of principals to whom the ARP applies is defined by the name
- of the ARP file: the site ARP is stored in <span
- class="fixedwidth">arp.site.xml</span> and user ARP's are stored as
- <span class="fixedwidth">arp.user.$PRINCIPALNAME.xml</span>.
- Up to two ARP's will apply to a principal: the site ARP, and the
- user ARP for that principal.</p>
-
- <p>Each ARP acts as a container that holds a set of ARP rules
- that are applicable to the principals that ARP is effective
- for. Each ARP rule specifies a single release policy within
- the ARP container pertaining to a specific set of targets.
- This set of targets may be specified as a specific SHAR, a
- SHAR tree, or a regular expression, and becomes the ARP rule's
- target definition. Each ARP rule may contain specifications
- regarding the release of any number of attribute values to
- requests matching that ARP rule for that user. ARP rules may
- be flagged as default, implying that they are always applied
- to any user matched by the ARP container. Note that ARP's may
- also be used to restrict specific attribute/value pairs in
- addition to restricting or releasing individual attributes.</p>
-
- <p>When a query is received, the AA generates an effective
- ARP, which is the fully evaluated set of ARP rules regarding
- that SHAR based on all ARP containers applicable to the
- principal. This effective ARP is then applied to attribute
- values retrieved from the directory and the appropriate
- assertion is constructed. Default rules are always
- included in construction of the effective ARP.</p>
-
- </blockquote>
-
- <h4><a name="5.b.i."></a>5.b.i. ARP Processing</h4>
-
- <blockquote>
- <blockquote>
- <p>When a request arrives from a particular SHAR, the
- applicable set of ARP rules are parsed into an effective
- ARP. This parsing is done as follows:</p>
-
- <ol type=1>
- <li>Identify all ARP's that should be applied to a particular
- principal. This is done by isolating the files in the folder
- specified by <span
- class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path</span> that have the
- name either arp.site.xml or arp.user.$PRINCIPALNAME.xml.</li>
- <li>Find all ARP rules relevant to the query:
- <ol type=i>
- <li>Any ARP rules within the identified ARP's designated
- as defaults are automatically included in the effective
- ARP without performing any matching functions.</li>
- <li>For each non-default rule in each identified ARP,
- the matching functions specified in the rule's target
- definition are performed. A separate matching function
- is performed for the requesting SHAR and the resource on
- behalf of which the SHAR is making the request.</li>
- <li>Each matching function evaluates to <span class="fixedwidth">TRUE</span> if
- the match is successful or <span class="fixedwidth">FALSE</span> if it is
- unsuccessful. If both functions evaluate to
- <span class="fixedwidth">TRUE</span>, the rule is included in the Effective
- ARP.</li>
- </ol></li>
- <li>Construct the Attribute Filter:
- <ol type=i>
- <li>For each attribute, compile a temporary list of
- associated rules that includes all values with a release
- qualifier of <span class="fixedwidth">permit</span>.</li>
- <li>Subtract from this list all attribute values with
- rules specifying a release qualifier of <span class="fixedwidth">deny</span>.
- The resulting list represents the allowable release
- values for the attribute and is used as a mask for the
- values which are returned from the Attribute
- Resolver.</li>
- <li>If a statement specifies that all values should be
- permitted, then specific <span class="fixedwidth">deny</span> qualifiers for
- specific values should still be enforced. If a
- statement specifies that all values should be denied,
- then <span class="fixedwidth">permit</span> qualifiers for specific values will
- be ignored.</li>
- </ol></li>
- <li>Using the mask and attributes returned from the
- Attribute Resolver, an assertion is constructed.</li>
- </ol>
- </blockquote>
- </blockquote>
-
-
- <h4><a name="5.b.ii."></a>5.b.ii. ARP Syntax</h4>
-
- <blockquote>
- <blockquote>
-
- <p>Each ARP is described by an XML file based on a standard
- <span class="fixedwidth">.xsd</span> schema. It consists of a standard
- <span class="fixedwidth">AttributeReleasePolicy</span> element referencing the
- appropriate <span class="fixedwidth">xsi:schemaLocation</span> and a self-explanatory
- <span class="fixedwidth">Description</span> element followed by any number of
- <span class="fixedwidth">Rule</span> elements. Each <span class="fixedwidth">Rule</span> element must
- consist of a <span class="fixedwidth">Target</span> element and one or more
- <span class="fixedwidth">Attribute</span> elements. The <span class="fixedwidth">Target</span> element
- specifies the rules by which the target definition is formed.
- The <span class="fixedwidth">Attribute</span> elements specifies the name and values
- of the attributes that may be released.</p>
-
- <p>The simplest possible ARP is as follows, which releases
- <span class="fixedwidth">eduPersonScopedAffiliation</span> to any target for the
- users the ARP applies to:</p>
-
- <blockquote>
- <span class="fixedwidth">
- <?xml version="1.0"?><br>
-
- <AttributeReleasePolicy
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns="urn:mace:shibboleth:arp:1.0"
- xsi:schemaLocation="urn:mace:shibboleth:arp:1.0
- shibboleth-arp-1.0.xsd"><br>
-
-
- <Description>Simplest possible
- ARP.</Description><br>
-
-
- <Rule><br>
-
-
- <Target><br>
-
-
-
- <AnyTarget/><br>
-
-
- </Target><br>
-
-
- <Attribute
- name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"><br>
-
-
-
- <AnyValue release=
- "permit"/><br>
-
-
- </Attribute
- ><br>
-
- </Rule
- ><br>
-
- </AttributeReleasePolicy><br>
-
- </span>
- </blockquote>
- </blockquote>
-
- <p>All ARP's must take the same basic form. A detailed
- description of how each element of the <span class="fixedwidth">Rule</span> element
- may be sub-populated follows:</p>
-
- <p>The <span class="fixedwidth">Target</span> element:</p>
-
- <blockquote>
-
- <p><span class="fixedwidth">Target</span> may contain either the
- <span class="fixedwidth">AnyTarget</span> element, which will cause the
- <span class="fixedwidth">Target</span> to always return <span class="fixedwidth">TRUE</span>, or both the
- <span class="fixedwidth">Requester</span> element, which provides for matches to be
- performed against the SHAR name and the <span class="fixedwidth">Resource</span>
- element, which provides for matches to be performed against
- the requested URL.</p>
-
- <p>There are three matches that may be performed by the AA
- in evaluating ARP's by using the <span class="fixedwidth">matchFunction</span>
- component of the <span class="fixedwidth">Requester</span> and <span class="fixedwidth">Resource</span>
- elements. The following match patterns may be
- specified directly following the <span class="fixedwidth">Requester</span> or
- <span class="fixedwidth">Resource</span> elements, such as <span class="fixedwidth"><Requester
- matchFunction="urn:mace:shibboleth:arp:matchFunction:regexMatch"></span>:</p>
-
- <ul type=disc>
- <li>
- <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:exactShar
- </span></p>
- <blockquote>
- <p>May be used with the <span class="fixedwidth">Requester</span>
- element.</p>
-
- <p>Evaluates to <span class="fixedwidth">TRUE</span> when the string content
- of the <span class="fixedwidth">Requester</span> element matches exactly the
- name of the requesting SHAR. Otherwise evaluates to
- <span class="fixedwidth">FALSE</span>. Serves as the default value
- associated with <span class="fixedwidth">Requester</span> if none is
- specified.</p>
- </blockquote>
- </li>
- <li>
- <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:resourceTree
- </span></p>
- <blockquote>
- <p>May be used with the <span class="fixedwidth">Resource</span> element.</p>
-
- <p>Evaluates to <span class="fixedwidth">TRUE</span> when the location of
- the resource either matches exactly or begins with
- the string content of the <span class="fixedwidth">Resource</span> element.
- Otherwise evaluates to <span class="fixedwidth">FALSE</span>.</p>
- </blockquote>
- </li>
- <li>
- <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:regexMatch
- </span></p>
- <blockquote>
- <p>May be used with both the <span class="fixedwidth">Requester</span>
- and <span class="fixedwidth">Resource</span> elements.</p>
-
- <p>Evaluates to <span class="fixedwidth">TRUE</span> when the name of the
- requesting SHAR or the requested URL tree is a valid
- match of the regular expression represented as the
- content of the containing element. Otherwise evaluates
- to <span class="fixedwidth">FALSE</span>. Regular expressions are evaluated in
- accordance with the the <a
- href="http://java.sun.com/j2se/1.4/docs/api/java/util/
- regex/Pattern.html#sum">Java 1.4 Pattern API</a>.</p>
- </blockquote>
- </li>
- </ul>
-
- </blockquote>
-
- <p>The <span class="fixedwidth">Attribute</span> element:</p>
-
- <blockquote>
-
- <p>The <span class="fixedwidth">Attribute</span> element must always specify the
- URN of the attribute whose release parameters it specifies.
- Additionally, it must contain either the <span class="fixedwidth">AnyValue</span>
- element or one or more <span class="fixedwidth">Value</span> elements. These
- elements, in turn, must specify either <span class="fixedwidth">release</span> =
- <span class="fixedwidth">permit</span> or <span class="fixedwidth">deny</span>. The <span class="fixedwidth">Value</span>
- element must then contain one value for which the rule
- applies. Examples:</p>
-
- <blockquote>
- <span class="fixedwidth">
- <Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName"><br>
- <AnyValue release="Permit"><br>
- </Attribute><br>
- </span><br>
- <p>Permits the release of <span class="fixedwidth">eduPersonPrincipalName</span>
- with any value.</p>
- </blockquote>
-
- <blockquote>
- <span class="fixedwidth">
- <Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"><br>
- <Value release="deny">member@example.edu</Value><br>
- </Attribute><br>
- </span><br>
- <p>Denies the release of
- <span class="fixedwidth">eduPersonScopedAffiliation</span> value
- <span class="fixedwidth">member@example.edu</span>. Other values of the
- attribute may still be released if so specified by a
- <span class="fixedwidth">permit</span> ARP.</p>
- </blockquote>
- </blockquote>
-
- <!-- ##To be included in future releases. Not yet implemented.