background-color: #EEEEEE;
padding: 3px;
}
-.fixedwidth
+.fixed
{
font-family: monospace;
font-size: 90%;
font-color: #121212;
}
+.feature
+{
+color: #00FF00
+}
</style>
</head>
<h2>Shibboleth Origin Deployment Guide</h2>
</center>
Shibboleth Origin Deployment Guide<br>
- Shibboleth Version 1.0<br />
- June 19, 2003<br />
+ Shibboleth Version 1.0.1<br />
+ July 25, 2003<br />
- <h3>This version of the deploy guide is for Shibboleth v1.0. For
- documentation related to prior versions of Shibboleth, please
- consult the appropriate branch in the Shibboleth
- CVS.</h3>
+ <h3>This version of the deploy guide is for Shibboleth v1.0.1. For documentation
+ related to prior versions of Shibboleth, please consult the appropriate branch
+ in the Shibboleth CVS.</h3>
<h3>Federations have been abstracted out from the Shibboleth
documentation. For further information on using Shibboleth in a
federation, refer to the federation guide.</h3>
- <p>Shibboleth v1.0 is stable and secure enough to deploy in
- production scenarios. While attempts have been made to include all
- functionality that would represent a break of interoperability with
- previous versions in v1.0, be aware that future versions of
- Shibboleth are likely to be developed and may include further
- implementation of the architectural document, functional
- enhancements, and user interface improvements.</p>
-
- <h4>Major New Features - 1.0</h4>
+ <p>Shibboleth v1.0.1 is stable and secure enough to deploy in production
+ scenarios. It is backward compatible with 1.0 in all respects, including
+ configuration, but some older commands have been deprecated or replaced.</p>
+
+ <p>Features and changes specific to 1.0.1 are marked with <span class="feature">
+ [1.0.1]</span></p>
+
+ <h4>Major New Features in 1.0 and 1.0.1</h4>
This new release contains many improvements and enhancements, including:
- <h5>Federation Support</h5>
+ <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>
+ <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. </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.</li>
+ <li>Better support for flexible and bilateral trust agreements. A key
+ specific to an origin site can be used to vallidate its signature.</li>
+ <li>This version contains a significantly more mature security
+ implementation, and should meet the security requirements of typical sites.</li>
</ol>
-
- <h5>Origin</h5>
+ <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>
+ <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.</li>
+ <li>Support for a runtime-derived per-requester persistent identifier
+ attribute to support anonymous personalization by targets has been added via
+ an attribute plugin. <span class="feature">[1.0.1]</span></li>
+ <li>Specialized deployments without privacy needs can configure identity-based
+ handles interoperable with other SAML deployments. <span class="feature">
+ [1.0.1]</span></li>
</ol>
-
- <h5>Target</h5>
+ <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>
+ <li>Significantly more flexibility in configuring targets to ensure
+ robustness. Failover and redundant configurations are now supported.</li>
+ <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.</li>
+ <li>The SHAR can be configured to request specific attributes from the
+ Origin.</li>
+ <li>The SHAR can use TCP sockets when responding to the Apache module, for
+ specialized deployment behind firewalls. <span class="feature">[1.0.1]</span>
+ </li>
+ <li>Attribute acceptance policies have been greatly enhanced, and are now
+ used to configure all aspects of attribute handling by the target, except
+ for requesting specific attributes by sitename. Adding attributes now takes
+ place in one configuration step. <span class="feature">[1.0.1]</span> </li>
+ <li>Support for Apache 1.3 on Windows NT/2000/XP/2003 has been added.
+ <span class="feature">[1.0.1]</span></li>
+ <li>Microsoft IIS web server support has been added via an ISAPI filter and
+ extension. <span class="feature">[1.0.1]</span></li>
</ol>
- <h5>Miscellaneous</h5>
+ <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 "error URL" 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>
+ <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.</li>
+ <li>Various improvements to error handling. Origin sites are now able to
+ supply an error URL and contact information to a federation. When a target
+ encounters an error, it can include this information in the error page.</li>
+ <li>Local time string values are now used in log files.</li>
+ <li>Internationalization support has been extended.</li>
</ol>
<p>Before starting, please sign up for all applicable <a href=
assistance can be found here.</p>
<p>Please send any questions, concerns, or eventual confusion
- to <a href=
- "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.
+ to <a href="mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.
This should include, but not be limited to, questions about the
documentation, undocumented problems, installation or
operational issues, and anything else that arises. Please
<br>
- <h3><a name="TOC"></a>Shibboleth Origin -- Table of
- Contents</h3>
+ <h3><a name="TOC"></a>Shibboleth Origin -- Table of Contents</h3>
<br>
Shibboleth: the Attribute Authority (AA), the Handle Service
(HS), the directory service, and the local sign-on system
(SSO). The AA and HS are provided with Shibboleth, and an
- open-source WebISO solution Pubcookie can be obtained from
+ open-source WebISO solution, Pubcookie, can be obtained from
www.pubcookie.org; the directory is provided by the origin
site. Shibboleth is able to interface with a directory
exporting an LDAP interface containing user attributes, and is
<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
+ supporting <span class="fixed">Servlet API v2.3</span> and <span class="fixed">JSP specification
1.2</span>.</b></p>
<blockquote>
4.1.18-24 LE Java server</a></li>
<li>
- <a href="http://java.sun.com/j2se/">Sun J2SE v 1.4.1_01 SDK</a>
-
- <blockquote>
- <p>Other versions of the JRE are not supported and are
- known to cause errors when working with
- certificates.</p>
- </blockquote>
+ <a href="http://java.sun.com/j2se/">Sun J2SE JDK v1.4.1_01 and above</a>
</li>
<li>
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 two pre-defined
+ echo responder which will always returns predefined
attributes.</p>
</blockquote>
</li>
<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>
+ "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">/usr/local/</span> recommended).</p>
+ <p>The archive will expand into a <span class="fixed">shibboleth-origin-1.0/</span>
+ directory(<span class="fixed">/opt</span> recommended).</p>
</li>
<li>
Tomcat's tree:</p>
<blockquote>
- <span class="fixedwidth">cp /usr/local/shibboleth-origin-1.0/dist/shibboleth.war
+ <span class="fixed">cp /opt/shibboleth-origin-1.0/dist/shibboleth.war
/usr/local/tomcat/webapps/</span>
</blockquote>
</li>
To deal with this problem use the following command, adjusting
paths as needed:</p>
<blockquote>
- <span class="fixedwidth">$ cp /usr/local/shibboleth-origin-1.0/endorsed/*.jar /usr/local/tomcat/common/endorsed</span>
+ <span class="fixed">$ 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
<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>
+ <span class="fixed">/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
+ <span class="fixed">httpd.conf</span>, or to place <span class="fixed">Include
+ conf/mod_jk.conf</span> in <span class="fixed">httpd.conf</span>, and place
the following lines in
- <span class="fixedwidth">/etc/httpd/conf/mod_jk.conf</span>:</p>
+ <span class="fixed">/etc/httpd/conf/mod_jk.conf</span>:</p>
<blockquote>
- <span class="fixedwidth">--------- begin ---------<br>
+ <span class="fixed">--------- begin ---------<br>
<IfModule !mod_jk.c><br>
LoadModule jk_module libexec/mod_jk.so<br>
</IfModule><br>
</li>
<li>
- <p>Tomcat's <span class="fixedwidth">/conf/server.xml</span>
+ <p>Tomcat's <span class="fixed">/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
+ class="fixed">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
+ <p>Add <span class="fixed">address="127.0.0.1"</span> inside the
+ <span class="fixed"><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
+ <p>Add <span class="fixed">tomcatAuthentication="false"</span> to the
+ <span class="fixed"><Ajp13Connector></span> configuration element
to ensure that the user's identity is passed from
Apache to the servlet environment.</p>
</li>
<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
+ <span class="fixed">/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
<p>All pathnames are relative, and have an effective root
path of
- <span class="fixedwidth">$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/</span>. To
+ <span class="fixed">$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>
+ as <span class="fixed">file:///opt/shibboleth-origin-1.0/</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>
+ component of <span class="fixed">origin.properties</span>:</p>
<br>
<p>General Configuration:</p>
<dl>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.issuer
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.issuer
= <domain name></span>
</dd>
</dd>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName
+ <span class="fixed">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
+ class="fixed">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
</dd>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl
= <url></span>
</dd>
<dd class="value">
- <p>Specifies the <span class="fixedwidth">URL</span>
+ <p>Specifies the <span class="fixed">URL</span>
at which the HS' corresponding AA may be
contacted.</p>
</dd>
<dd class="attributeoptlong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.username
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.username
= <var></span>
</dd>
<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>
+ class="fixed">REMOTE_USER</span>.</p>
</dd>
<dd class="attributeoptlong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.authMethod
+ <span class="fixed">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
+ class="fixed">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
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><span class="fixed">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><span class="fixed">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><span class="fixed">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
<dl>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath
= <pathname></span>
</dd>
</dd>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword
= <password></span>
</dd>
</dd>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias
= <alias></span>
</dd>
</dd>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword
= <password></span>
</dd>
</dd>
<dd class="attributeoptlong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias
= <alias></span>
</dd>
<dl>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.AAServlet.authorityName
+ <span class="fixed">edu.internet2.middleware.shibboleth.aa.AAServlet.authorityName
= <domain name></span>
</dd>
</dd>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.AAServlet.passThruErrors
+ <span class="fixed">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>
+ class="fixed">false</span>.</p>
</dd>
</dl>
<dl>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.attrresolv.AttributeResolver.ResolverConfig
+ <span class="fixed">edu.internet2.middleware.shibboleth.aa.attrresolv.AttributeResolver.ResolverConfig
= <pathname></span>
</dd>
<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
+ class="fixed">/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>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.ArpRepository.implementation
+ <span class="fixed">edu.internet2.middleware.shibboleth.aa.arp.ArpRepository.implementation
= <string></span>
</dd>
<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.
+ <span class="fixed">edu.internet2.middleware.shibboleth.aa.arp.
provider.FileSystemArpRepository</span>.</p>
<p>Note that the set of principals that an ARP applies
</dd>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path
+ <span class="fixed">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path
= <pathname></span>
</dd>
</dd>
<dd class="attributeoptlong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.ArpTTL
+ <span class="fixed">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
+ class="fixed">seconds</span> that ARP's may be
cached by the AA. Defaults to <span
- class="fixedwidth">0</span>, or no caching.</p>
+ class="fixed">0</span>, or no caching.</p>
</dd>
</dl>
<dl>
<dd class="attributeoptlong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleRepository.implementation
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleRepository.implementation
= <string></span>
</dd>
<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.
+ <span class="fixed">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>
+ <span class="fixed">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>
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleRepository.
+ implementation</span> is <span class="fixed">MemoryHandleRepository</span>)</font></p>
<blockquote>
<dl>
<dd class="attributeoptlong">
-<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.BaseHandleRepository.handleTTL
+<span class="fixed">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
+ class="fixed">seconds</span> for which issued handles
are valid. Defaults to <span
- class="fixedwidth">1800</span>, or 30 minutes. The time
+ class="fixed">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>
<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>
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleRepository.
+ implementation</span> is <span class="fixed">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
+ have a <span class="fixed">DESede</span> secret key in a
+ keystore of type <span class="fixed">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
+ class="fixed">./ant genSecret</span>, which will create a
keystore in <span
- class="fixedwidth">$SHIB_HOME/src/conf/handle.jks</span> that
+ class="fixed">$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
+ class="fixed">handleKey</span> and a password of <span
+ class="fixed">shibhs</span>. If <span
+ class="fixed">./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
+ <span class="fixed">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePath
= <pathname></span>
</dd>
</dd>
<dd class="attributelong">
-<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePassword
+<span class="fixed">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePassword
= <password></span>
</dd>
</dd>
<dd class="attributelong">
-<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyAlias
+<span class="fixed">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyAlias
= <password></span>
</dd>
</dd>
<dd class="attributelong">
-<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyPassword
+<span class="fixed">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyPassword
= <password></span>
</dd>
</dd>
<dd class="attributeoptlong">
-<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.CryptoHandleRepository.handleTTL
+<span class="fixed">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
+ class="fixed">seconds</span> for which issued handles
are valid. Defaults to <span
- class="fixedwidth">1800</span>, or 30 minutes. The time
+ class="fixed">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>
<dl>
<dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.audiences
+ <span class="fixed">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
+ class="fixed">URI</span>'s that will be used for
+ the <span class="fixed">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
<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
+ class="fixed">[policies]</span> section of <span
+ class="fixed">shibboleth.ini</span> or
interoperation will fail by design.
</dd>
</dl>
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>
+ <span class="fixed">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
+ <span class="fixed">/usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf/keystore.jks</span>
+ with a password of <span class="fixed">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>
+ store it in the <span class="fixed">keystore.jks</span> file, with a keyentry
+ alias of <span class="fixed">hs</span> and new passwords of your choosing:</p>
<blockquote>
- <span class="fixedwidth">$ cd
- /usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf<br>
+ <span class="fixed">$ 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
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
+ the <span class="fixed">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
the following command:</p>
<blockquote>
- <span class="fixedwidth">$ keytool -certreq -keystore keystore.jks -alias hs
+ <span class="fixed">$ 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
+ <p>The contents of <span class="fixed"><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
+ <span class="fixed">$ keytool -import -keystore keystore.jks -alias hs
-file <cert-file></span>
</blockquote>
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
+ <span class="fixed">REMOTE_USER</span>. Location blocks can be added to
+ <span class="fixed">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>
+ <span class="fixed"><Location /shibboleth/HS><br>
AuthType Basic<br>
AuthName "Internet2 Handle Service"<br>
AuthUserFile /usr/local/apache/conf/user.db<br>
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>.
+ class="fixed">$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>
+ descriptor (<span class="fixed">web.xml</span>):</p>
<blockquote>
- <span class="fixedwidth"> <filter><br>
+ <span class="fixed"> <filter><br>
<filter-name><br>
Client Cert AuthN Filter<br>
</filter-name><br>
</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
+ class="fixed">CN</span> of the cert's <span
+ class="fixed">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>
+ <span class="fixed">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
+ <span class="fixed">regex</span> and <span
+ class="fixed">matchGroup</span> that can be used to extract
the principal name differently.</p>
</blockquote>
<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.c.">5.c.</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>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="fixed">/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>
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>.
+ class="fixed">arp.site.xml</span> and user ARP's are stored as
+ <span class="fixed">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>
<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
+ class="fixed">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>
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
+ <li>Each matching function evaluates to <span class="fixed">TRUE</span> if
+ the match is successful or <span class="fixed">FALSE</span> if it is
unsuccessful. If both functions evaluate to
- <span class="fixedwidth">TRUE</span>, the rule is included in the Effective
+ <span class="fixed">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>
+ qualifier of <span class="fixed">permit</span>.</li>
<li>Subtract from this list all attribute values with
- rules specifying a release qualifier of <span class="fixedwidth">deny</span>.
+ rules specifying a release qualifier of <span class="fixed">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
+ permitted, then specific <span class="fixed">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
+ then <span class="fixed">permit</span> qualifiers for specific values will
be ignored.</li>
</ol></li>
<li>Using the mask and attributes returned from the
<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
+ <span class="fixed">.xsd</span> schema. It consists of a standard
+ <span class="fixed">AttributeReleasePolicy</span> element referencing the
+ appropriate <span class="fixed">xsi:schemaLocation</span> and a self-explanatory
+ <span class="fixed">Description</span> element followed by any number of
+ <span class="fixed">Rule</span> elements. Each <span class="fixed">Rule</span> element must
+ consist of a <span class="fixed">Target</span> element and one or more
+ <span class="fixed">Attribute</span> elements. The <span class="fixed">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
+ The <span class="fixed">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
+ <span class="fixed">eduPersonScopedAffiliation</span> to any target for the
users the ARP applies to:</p>
<blockquote>
- <span class="fixedwidth">
+ <span class="fixed">
<?xml version="1.0"?><br>
<AttributeReleasePolicy
</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
+ description of how each element of the <span class="fixed">Rule</span> element
may be sub-populated follows:</p>
- <p>The <span class="fixedwidth">Target</span> element:</p>
+ <p>The <span class="fixed">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>
+ <p><span class="fixed">Target</span> may contain either the
+ <span class="fixed">AnyTarget</span> element, which will cause the
+ <span class="fixed">Target</span> to always return <span class="fixed">TRUE</span>, or both the
+ <span class="fixed">Requester</span> element, which provides for matches to be
+ performed against the SHAR name and the <span class="fixed">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>
+ in evaluating ARP's by using the <span class="fixed">matchFunction</span>
+ component of the <span class="fixed">Requester</span> and <span class="fixed">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
+ specified directly following the <span class="fixed">Requester</span> or
+ <span class="fixed">Resource</span> elements, such as <span class="fixed"><Requester
matchFunction="urn:mace:shibboleth:arp:matchFunction:regexMatch"></span>:</p>
<ul type=disc>
<li>
- <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:exactShar
+ <p><span class="fixed">urn:mace:shibboleth:arp:matchFunction:exactShar
</span></p>
<blockquote>
- <p>May be used with the <span class="fixedwidth">Requester</span>
+ <p>May be used with the <span class="fixed">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
+ <p>Evaluates to <span class="fixed">TRUE</span> when the string content
+ of the <span class="fixed">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
+ <span class="fixed">FALSE</span>. Serves as the default value
+ associated with <span class="fixed">Requester</span> if none is
specified.</p>
</blockquote>
</li>
<li>
- <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:resourceTree
+ <p><span class="fixed">urn:mace:shibboleth:arp:matchFunction:resourceTree
</span></p>
<blockquote>
- <p>May be used with the <span class="fixedwidth">Resource</span> element.</p>
+ <p>May be used with the <span class="fixed">Resource</span> element.</p>
- <p>Evaluates to <span class="fixedwidth">TRUE</span> when the location of
+ <p>Evaluates to <span class="fixed">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>
+ the string content of the <span class="fixed">Resource</span> element.
+ Otherwise evaluates to <span class="fixed">FALSE</span>.</p>
</blockquote>
</li>
<li>
- <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:regexMatch
+ <p><span class="fixed">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>May be used with both the <span class="fixed">Requester</span>
+ and <span class="fixed">Resource</span> elements.</p>
- <p>Evaluates to <span class="fixedwidth">TRUE</span> when the name of the
+ <p>Evaluates to <span class="fixed">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
+ to <span class="fixed">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>
- <p>The <span class="fixedwidth">Attribute</span> element:</p>
+ <p>The <span class="fixed">Attribute</span> element:</p>
<blockquote>
- <p>The <span class="fixedwidth">Attribute</span> element must always specify the
+ <p>The <span class="fixed">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>
+ Additionally, it must contain either the <span class="fixed">AnyValue</span>
+ element or one or more <span class="fixed">Value</span> elements. These
+ elements, in turn, must specify either <span class="fixed">release</span> =
+ <span class="fixed">permit</span> or <span class="fixed">deny</span>. The <span class="fixed">Value</span>
element must then contain one value for which the rule
applies. Examples:</p>
<blockquote>
- <span class="fixedwidth">
+ <span class="fixed">
<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>
+ <p>Permits the release of <span class="fixed">eduPersonPrincipalName</span>
with any value.</p>
</blockquote>
<blockquote>
- <span class="fixedwidth">
+ <span class="fixed">
<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
+ <span class="fixed">eduPersonScopedAffiliation</span> value
+ <span class="fixed">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>
+ <span class="fixed">permit</span> ARP.</p>
</blockquote>
</blockquote>
<!-- ##To be included in future releases. Not yet implemented.
- <p>There is also a special <span class="fixedwidth">AttributeIdentifier</span>
+ <p>There is also a special <span class="fixed">AttributeIdentifier</span>
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>
<blockquote>
- <span class="fixedwidth">
+ <span class="fixed">
<Rule><br>
<Target><br>
<blockquote>
<blockquote>
<p>The JDK includes the command line program
- <span class="fixedwidth">keytool</span> for managing Java keystores. This utility
+ <span class="fixed">keytool</span> for managing Java keystores. This utility
cannot import or export private key information, making it
difficult to use the same private key and certificate for
Apache and Java-based applications. The Shibboleth
- distribution includes <span class="fixedwidth">extkeytool</span>, a program that
- can be used in conjunction with <span class="fixedwidth">keytool</span> to perform
+ distribution includes <span class="fixed">extkeytool</span>, a program that
+ can be used in conjunction with <span class="fixed">keytool</span> to perform
these tasks. Select the appropriate step-by-step procedure
for your situation from the following guides.</p>
- <p>Before running <span class="fixedwidth">extkeytool</span>, the variable
+ <p>Before running <span class="fixed">extkeytool</span>, the variable
SHIB_HOME must be set to the path to the directory where the
Shibboleth tarball was exploded(typically
- /usr/local/shibboleth-origin-1.0/).</p>
+ /opt/shibboleth-origin-1.0/).</p>
<p><b>If you have a pre-exiting RSA key/certificate
combination in a keystore and you would like to use it with
<p>Determine the alias of the keystore keyEntry
containing the key you would like to use in your Apache
setup. Assuming that your keystore is named
- <span class="fixedwidth">yourstore</span>, the following command should
+ <span class="fixed">yourstore</span>, the following command should
present a list of the entries in the keystore.</p>
<blockquote>
- <p><span class="fixedwidth">$ keytool -list -v -keystore
- yourstore</span></p>
+ <p><span class="fixed">$ keytool -list -v -keystore yourstore</span></p>
</blockquote>
</li>
<li>
<p>Assuming that you identified the appropriate alias
- as <span class="fixedwidth">youralias</span> and the password for the keystore
- is <span class="fixedwidth">yourpass</span>, enter the following command to
+ as <span class="fixed">youralias</span> and the password for the keystore
+ is <span class="fixed">yourpass</span>, enter the following command to
export the key in Base64-encoded pkcs8 format.</p>
<blockquote>
- <p><span class="fixedwidth">$ extkeytool -exportkey -keystore yourstore
+ <p><span class="fixed">$ extkeytool -exportkey -keystore yourstore
-alias youralias -storepass yourpass -rfc -file
yourkey.pkcs8</span></p>
</blockquote>
following command for the conversion:</p>
<blockquote>
- <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.pkcs8
+ <p><span class="fixed">$ openssl pkcs8 -in yourkey.pkcs8
-nocrypt|openssl rsa -out yourkey.key</span></p>
</blockquote>
</li>
command for the conversion:</p>
<blockquote>
- <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.pkcs8
+ <p><span class="fixed">$ openssl pkcs8 -in yourkey.pkcs8
-nocrypt|openssl rsa -des3 -out
yourkey.enckey</span></p>
</blockquote>
certificate.</p>
<blockquote>
- <p><span class="fixedwidth">$ keytool -export -keystore yourstore -alias
+ <p><span class="fixed">$ keytool -export -keystore yourstore -alias
youralias -rfc -file yourcert</span></p>
</blockquote>
</li>
<li>
- <p>Set the <span class="fixedwidth">mod_ssl</span>
- <span class="fixedwidth">SSLCertificateKeyFile</span> and
- <span class="fixedwidth">SSLCertificateFile</span> directives to point to the
+ <p>Set the <span class="fixed">mod_ssl</span>
+ <span class="fixed">SSLCertificateKeyFile</span> and
+ <span class="fixed">SSLCertificateFile</span> directives to point to the
two files you have just created. Take care to remove
any temporary files you created (i.e.
- <span class="fixedwidth">yourkey.pkcs8</span>) and set appropriate file
+ <span class="fixed">yourkey.pkcs8</span>) and set appropriate file
permissions, especially if you chose to store the key
in an unencrypted format.</p>
</li>
<li>
<p>Convert the private key to unencrypted DER-encoded
pkcs8 format. Assuming your PEM-encoded key is stored
- in a file named <span class="fixedwidth">yourkey.enckey</span>, enter the
+ in a file named <span class="fixed">yourkey.enckey</span>, enter the
following command.</p>
<blockquote>
- <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.enckey -topk8
+ <p><span class="fixed">$ openssl pkcs8 -in yourkey.enckey -topk8
-nocrypt -outform DER -out yourkey.der.pkcs8</span></p>
</blockquote>
</li>
representing a complete trust chain, from the root CA
certificate to the certificate that matches your
private key. If your certificate is stored in a file
- named <span class="fixedwidth">mycert</span> and the CA signer certificate is
- stored in a file named <span class="fixedwidth">ca.cert</span>, you might
+ named <span class="fixed">mycert</span> and the CA signer certificate is
+ stored in a file named <span class="fixed">ca.cert</span>, you might
enter the following command to create the bundle.</p>
<blockquote>
- <p><span class="fixedwidth">$ cat mycert ca.cert > cert.bundle</span></p>
+ <p><span class="fixed">$ cat mycert ca.cert > cert.bundle</span></p>
</blockquote>
- <b>Note: <span class="fixedwidth">mod_ssl</span>-enabled Apache
+ <b>Note: <span class="fixed">mod_ssl</span>-enabled Apache
installations include a number of commonly recognized
- CA certificates in the <span class="fixedwidth">ca-bundle.crt</span> file
- under the <span class="fixedwidth">$ServerRoot/conf/ssl.crt/</span>
+ CA certificates in the <span class="fixed">ca-bundle.crt</span> file
+ under the <span class="fixed">$ServerRoot/conf/ssl.crt/</span>
directory.</b>
</li>
<li>
<p>Import the key and certificate into the keystore.
Assuming you have already created a keystore named
- <span class="fixedwidth">yourstore</span> with a password of of
- <span class="fixedwidth">yourpass</span>, enter the following command to store
- the data under the alias <span class="fixedwidth">youralias</span>.</p>
+ <span class="fixed">yourstore</span> with a password of of
+ <span class="fixed">yourpass</span>, enter the following command to store
+ the data under the alias <span class="fixed">youralias</span>.</p>
<blockquote>
- <p><span class="fixedwidth">$ ./extkeytool -importkey -keystore yourstore
+ <p><span class="fixed">$ ./extkeytool -importkey -keystore yourstore
-alias youralias -storepass yourpass -keyfile
yourkey.der.pkcs8 -certfile cert.bundle -provider
org.bouncycastle.jce.provider.BouncyCastleProvider</span></p>
listing entry. Use the command below.</p>
<blockquote>
- <p><span class="fixedwidth">$ keytool -list -v -keystore yourstore -alias
+ <p><span class="fixed">$ keytool -list -v -keystore yourstore -alias
youralias</span></p>
</blockquote>
</li>
<li>
- <p>Remember to delete <span class="fixedwidth">yourkey.der.pkcs8</span>, as it
+ <p>Remember to delete <span class="fixed">yourkey.der.pkcs8</span>, as it
contains your unencrypted private key.</p>
</li>
</ol>
<ol type="1">
<li>
<p>Generate an RSA private key. Use the command below,
- substituting <span class="fixedwidth">yourkey</span> with an appropriate name
+ substituting <span class="fixed">yourkey</span> with an appropriate name
to use to refer to the key.</p>
<blockquote>
- <p><span class="fixedwidth">$ openssl genrsa -des3 -out yourkey.enckey
+ <p><span class="fixed">$ openssl genrsa -des3 -out yourkey.enckey
1024</span></p>
</blockquote>
</li>
Certificate Authority.</p>
<blockquote>
- <p><span class="fixedwidth">$ openssl req -new -key
+ <p><span class="fixed">$ openssl req -new -key
yourkey.enckey</span></p>
</blockquote>
</li>
<li>
<p>The Certificate Authority should respond with a
- PEM-encoded X509 certificate. Set the <span class="fixedwidth">mod_ssl</span>
- <span class="fixedwidth">SSLCertificateKeyFile</span> directive to point to
+ PEM-encoded X509 certificate. Set the <span class="fixed">mod_ssl</span>
+ <span class="fixed">SSLCertificateKeyFile</span> directive to point to
the key file you just created and the
- <span class="fixedwidth">SSLCertificateFile</span> directive to point to file
+ <span class="fixed">SSLCertificateFile</span> directive to point to file
containing the certificate issued by the Certificate
Authority. Previous sections explaion how to share the
key/certificate pair with a Java keystore.</p>
origins to quickly configure the retrieval of simple attributes
from standard types of attribute stores. The resolver is configured
using an xml file wich should be pointed to with the <span
- class="fixedwidth">edu.internet2.middleware.shibboleth.aa.
+ class="fixed">edu.internet2.middleware.shibboleth.aa.
attrresolv.AttributeResolver.ResolverConfig</span> propety in <span
- class="fixedwidth">origin.properties</span> as described in
+ class="fixed">origin.properties</span> as described in
section <a href="#4.a.">4.a</a>. For more complex attributes or
those that require processing before release, customized Java
classes will need to be written. For more information,
unmodified string value from a data connector and tagging it with
a name or can include arbitrarily complex business rules.</p>
- <p>The <span class="fixedwidth">resolver.xml</span> file that is
- pointed to by <span class="fixedwidth">origin.properties</span>
+ <p>The <span class="fixed">resolver.xml</span> file that is
+ pointed to by <span class="fixed">origin.properties</span>
consists of zero or more attribute definitions followed by zero or
more data connectors. Each attribute definition consists of an
identifier corresponding to the URN of the attribute, and optional
<p>Shibboleth comes with two attribute definitions provided in
version 1.0: the <span
- class="fixedwidth">SimpleAttributeDefinition</span>, which acts as
+ class="fixed">SimpleAttributeDefinition</span>, which acts as
a basic proxy for attributes supplied by data connectors with some
name conversion and attribute scoping added, and a <span
- class="fixedwidth">CustomAttributeDefinition</span>, which can be
+ class="fixed">CustomAttributeDefinition</span>, which can be
used to configure user-created attribute definition plugins.
Similarly, Shibboleth 1.0 comes with two data connectors: the
- <span class="fixedwidth">JNDIDirectoryDataConnector</span>, which
+ <span class="fixed">JNDIDirectoryDataConnector</span>, which
pulls data from any source for which there is a JNDI Directory
Context implementation, including LDAP, NDS, etc., and the <span
- class="fixedwidth">CustomDataConnector</span>, which is used to
+ class="fixed">CustomDataConnector</span>, which is used to
configure user-created data connector plugins.</p>
<p>A detailed explanation of each configuration option for the
provided connectors follows:</p>
- <p><span class="fixedwidth">JNDIDirectoryDataConnector</span>:</p>
+ <p><span class="fixed">JNDIDirectoryDataConnector</span>:</p>
<dl>
<dd class="attribute">
- <span class="fixedwidth">id = <string></span>
+ <span class="fixed">id = <string></span>
</dd>
<dd class="value">
<p>Specifies a unique, textual name for the connector used by
attribute definitions to refer to and use it to build
attributes. Contained within the <span
- class="fixedwidth">JNDIDirectoryDataConnector</span>
+ class="fixed">JNDIDirectoryDataConnector</span>
element.</p>
</dd>
<dd class="attribute">
- <span class="fixedwidth"><Property name="<name>" value="<value>"/></span>
+ <span class="fixed"><Property name="<name>" value="<value>"/></span>
</dd>
<dd class="value">
<p>An element of the element <span
- class="fixedwidth">JNDIDirectoryDataConnector</span>.
+ class="fixed">JNDIDirectoryDataConnector</span>.
Specifies a set of name/value pairs that are used to configure
the JNDI Directory Context. This list of name/value pairs is
defined by the context itself, but is specified within <span
- class="fixed
width">resolver.xml</span>. Refer to the <a
+ class="fixed">resolver.xml</span>. Refer to the <a
href="http://http://marsalis.internet2.edu/cgi-bin/viewcvs.cgi
/shibboleth/java/src/conf/resolver.ldap.xml">Shibboleth
CVS</a> for an example of names and values used to connect to
</dd>
<dd class="attributeopt">
- <span class="fixedwidth"><Search></span>
+ <span class="fixed"><Search></span>
</dd>
<dd class="valueopt">
<p>An element of the element <span
- class="fixedwidth">JNDIDirectoryDataConnector</span>. This
+ class="fixed">JNDIDirectoryDataConnector</span>. This
element defines the DN filter used to perform the LDAP search.
The search string must return no more than one result.</p>
</dd>
<dd class="attributeopt">
- <span class="fixedwidth"><Controls></span>
+ <span class="fixed"><Controls></span>
</dd>
<dd class="valueopt">
<p>An element of the element <span
- class="fixedwidth">Search</span>. This
+ class="fixed">Search</span>. This
element grants some fine-grained control over the LDAP API
calls.</p>
</dd>
<dd class="attributeopt">
- <span class="fixedwidth"><cacheTime "<seconds>"/></span>
+ <span class="fixed"><cacheTime "<seconds>"/></span>
</dd>
<dd class="valueopt">
<p>An element of the element <span
- class="fixedwidth">JNDIDirectoryDataConnector</span>.
+ class="fixed">JNDIDirectoryDataConnector</span>.
Specifies an optional duration in <span
- class="fixedwidth">seconds</span> for which the attribute
+ class="fixed">seconds</span> for which the attribute
resolver may cache information retrieved from this
connector.</p>
</dd>
</dl>
<p>A representation of a properly constructed <span
- class="fixedwidth">JNDIDirectoryDataConnector</span> element would
+ class="fixed">JNDIDirectoryDataConnector</span> element would
look like:</p>
- <blockquote><span class="fixedwidth">
+ <blockquote><span class="fixed">
<JNDIDirectoryDataConnector id="directory"><br>
<Search filter="cn=%PRINCIPAL%"><br>
<Controls searchScope="SUBTREE_SCOPE" returningObjects="false" /><br>
</JNDIDirectoryDataConnector>
</span></blockquote>
- <p><span class="fixedwidth">SimpleAttributeDefinition</span>:</p>
+ <p><span class="fixed">SimpleAttributeDefinition</span>:</p>
<dl>
<dd class="attribute">
- <span class="fixedwidth">id = <string></span>
+ <span class="fixed">id = <string></span>
</dd>
<dd class="value">
<p>Specifies a unique, textual name for the attribute which is
used as the attribute's name when it is sent over the wire by
Shibboleth. Contained within the <span
- class="fixedwidth">SimpleAttributeDefinition</span>
+ class="fixed">SimpleAttributeDefinition</span>
element.</p>
</dd>
<dd class="attributeopt">
- <span class="fixedwidth"><AttributeDependency / DataConnectorDependency requires="<id>"/></span>
+ <span class="fixed"><AttributeDependency / DataConnectorDependency requires="<id>"/></span>
</dd>
<dd class="valueopt">
<p>An element of the element <span
- class="fixedwidth">SimpleAttributeDefinition</span>, which may
+ class="fixed">SimpleAttributeDefinition</span>, which may
contain 0 or more of either <span
- class="fixedwidth">AttributeDependency</span> or <span
- class="fixedwidth">DataConnectorDependency</span>. These
+ class="fixed">AttributeDependency</span> or <span
+ class="fixed">DataConnectorDependency</span>. These
specify attributes and data connectors that can be utilized by
this attribute definition. Each of these elements must
- contain a <span class="fixedwidth">requires</span> statement
+ contain a <span class="fixed">requires</span> statement
which this attribute definition can then use to build its
value.</p>
</dd>
<dd class="attributeopt">
- <span class="fixedwidth">smartScope = "<domain>"</span>
+ <span class="fixed">smartScope = "<domain>"</span>
</dd>
<dd class="valueopt">
<p>Specifes a domain scope to be attached to the attribute. If
the value of the attribute as retrieved from the data
connector includes a pre-existing scope (<span
- class="fixedwidth">bob@foo.edu</span>), that scope is used
+ class="fixed">bob@foo.edu</span>), that scope is used
instead. Contained within the <span
- class="fixedwidth">SimpleAttributeDefinition</span>
+ class="fixed">SimpleAttributeDefinition</span>
element.</p>
</dd>
<dd class="attributeopt">
- <span class="fixedwidth">sourceName = "<string>"</span>
+ <span class="fixed">sourceName = "<string>"</span>
</dd>
<dd class="valueopt">
<p>Specifies a different source attribute name to be used in
calls to the data connector, while the name on the wire will
- be the specified <span class="fixedwidth">id</span>. This
+ be the specified <span class="fixed">id</span>. This
would be useful to send a local UniversityID attribute as
eduPersonPrincipalName. If not supplied, the connector
- tokenizes the <span class="fixedwidth">id</span> field and
+ tokenizes the <span class="fixed">id</span> field and
uses the section following the <span
- class="fixedwidth">#</span> to query data connectors.
+ class="fixed">#</span> to query data connectors.
Contained within the <span
- class="fixedwidth">SimpleAttributeDefinition</span>
+ class="fixed">SimpleAttributeDefinition</span>
element.</p>
</dd>
<dd class="attributeopt">
- <span class="fixedwidth"><cacheTime "<seconds>"/></span>
+ <span class="fixed"><cacheTime "<seconds>"/></span>
</dd>
<dd class="valueopt">
<p>An element of the element <span
- class="fixedwidth">SimpleAttributeDefinition</span>.
+ class="fixed">SimpleAttributeDefinition</span>.
Specifies an optional duration in <span
- class="fixedwidth">seconds</span> for which the attribute
+ class="fixed">seconds</span> for which the attribute
resolver may cache this attribute for use in additional
assertions.</p>
</dd>
<dd class="attributeopt">
- <span class="fixedwidth"><lifeTime "<seconds>"/></span>
+ <span class="fixed"><lifeTime "<seconds>"/></span>
</dd>
<dd class="valueopt">
<p>An element of the element <span
- class="fixedwidth">SimpleAttributeDefinition</span>.
+ class="fixed">SimpleAttributeDefinition</span>.
Specifies in the attribute assertion how long the attribute
should be cached and retained by the target upon receipt.
Federations and trust agreements may have some bearing on the
</dl>
<p>A representation of a properly constructed <span
- class="fixedwidth">SimpleAttributeDefinition</span> element would
+ class="fixed">SimpleAttributeDefinition</span> element would
look like:</p>
- <blockquote><span class="fixedwidth">
+ <blockquote><span class="fixed">
<SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonPrincipalName" smartScope="shibdev.edu" sourceName="universityPerson"><br>
<DataConnectorDependency requires="dataConnector"/><br>
<AttributeDependency requires="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"/><br>
</SimpleAttributeDefinition>
</span></blockquote>
- <p>A properly formed <span class="fixedwidth">resolver.xml</span>
+ <p>A properly formed <span class="fixed">resolver.xml</span>
file to automatically generate a simple response for EPPN may take
the form:</p>
- <blockquote><span class="fixedwidth">
+ <blockquote><span class="fixed">
<AttributeResolver xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mace:shibboleth:resolver:1.0" xsi:schemaLocation="urn:mace:shibboleth:resolver:1.0 shibboleth-resolver-1.0.xsd"><br>
<br>
<SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonPrincipalName" smartScope="shibdev.edu"><br>
</AttributeResolver>
</span></blockquote>
- <p>There are additional examples of <span class="fixed
width">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>
+ <p>There are additional examples of <span class="fixed">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>
<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
+ purposes. This data is sent through <span class="fixed">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,
+ <span class="fixed">/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
+ level of <span class="fixed">WARN</span>, but there is also a commented out
example in the file to give a possible alternate configuration.</p>
</blockquote>
projects / shibboleth / sp.git / commitdiff