-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
+<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <meta name="generator" content=
- "HTML Tidy for Mac OS X (vers 1st January 2002), see www.w3.org">
- <title>Shibboleth Origin Deployment Guide</title>
- <meta http-equiv="Content-Type" content=
- "text/html; charset=utf-8">
- <style type="text/css">
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<meta name="generator" content="Microsoft FrontPage 5.0">
+<meta name="ProgId" content="FrontPage.Editor.Document">
+<title>Shibboleth Origin Deployment Guide</title>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<style type="text/css">
html
{
}
dl
{
-background-color: #DDDDDD;
-background-image: none;
+border-width:2px; background-color: #DDDDDD;
+background-image: url('none');
margin: 5px;
padding: 0px;
border-style: solid;
-border-bottom-width: 2px;
-border-top-width: 2px;
-border-left-width: 2px;
-border-right-width: 2px;
+
}
dt
{
background-color: #DDDDDD;
-background-image: none;
+background-image: url('none');
margin: 1px;
-padding: 1px;
+padding: 1px
}
dd
{
background-color: #DDDDDD;
-background-image: none;
+background-image: url('none');
margin: 0px;
-padding: 1px;
+padding: 1px
}
.attribute
{
font-color: #000000;
text-align: left;
background-color: #DDDDDD;
-border: 1px black inset;
-background-image: none;
+border: 1px inset black;
+background-image: url('none');
margin: 0px;
-padding: 2px;
+padding: 2px
}
.value
{
font-color: #000000;
text-align: left;
background-color: #EEEEEE;
-background-image: none;
+background-image: url('none');
padding-top: 0em;
padding-bottom: 0.5em;
padding-right: 1em;
padding-left: 5em;
-border-style: solid;
border-bottom-width: none;
border-top-width: none;
border-left-width: 1px;
-border-right-width: 1px;
+border-right-width: 1px; border-left-style:solid; border-right-style:solid; border-top-style:solid; border-bottom-style:solid
}
.attributeopt
{
font-color: #000000;
text-align: left;
background-color: #BCBCEE;
-border: 1px black inset;
-background-image: none;
+border: 1px inset black;
+background-image: url('none');
margin: 0px;
-padding: 2px;
+padding: 2px
}
.valueopt
{
font-color: #000000;
text-align: left;
background-color: #DDDDFF;
-background-image: none;
+background-image: url('none');
padding-top: 0em;
padding-bottom: 0.5em;
padding-right: 1em;
padding-left: 5em;
-border-style: solid;
border-bottom-width: none;
border-top-width: none;
border-left-width: 1px;
-border-right-width: 1px;
+border-right-width: 1px; border-left-style:solid; border-right-style:solid; border-top-style:solid; border-bottom-style:solid
}
.attributelong
{
font-color: #000000;
text-align: left;
background-color: #DDDDDD;
-border: 1px black inset;
-background-image: none;
+border: 1px inset black;
+background-image: url('none');
margin: 0px;
-padding: 2px;
+padding: 2px
}
.attributeoptlong
{
font-color: #000000;
text-align: left;
background-color: #BCBCEE;
-border: 1px black inset;
-background-image: none;
+border: 1px inset black;
+background-image: url('none');
margin: 0px;
-padding: 2px;
+padding: 2px
}
.demo
{
font-size: 90%;
font-color: #121212;
}
-
- </style>
- </head>
-
- <body link="red" vlink="red" alink="black" bgcolor="white">
- <center>
- <h2>Shibboleth Origin Deployment Guide</h2>
- </center>
- Shibboleth Origin Deployment Guide<br>
- Shibboleth Version 1.0<br />
- June 19, 2003<br />
-
- <h3>This version of the deploy guide is for Shibboleth v1.0. For
- documentation related to prior versions of Shibboleth, please
- 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>
- This new release contains many improvements and enhancements, including:
-
- <h5>Federation Support</h5>
- <ol>
- <li>
- Federation and trust support has been substantially extended. Federation
- structures are now defined. The set of metadata collected and managed
- by each Federation is more fully defined. The configuration values
- assigned by a Federation are now identified. <br>
- </li>
- <li>
- There is some support for targets to be members of multiple federations;
- this support will continue to evolve. When a browser user arrives,
- a target will determine which federation their origin belongs to,
- and then use the trust fabric associated with that Federation. <br>
- </li>
- <li>
- Better support for flexible and bilateral trust agreements. A key
- specific to an origin site can be used to vallidate its signature.
- <br>
- </li>
-
- <li>
- This version contains a significantly more mature security implementation,
- and should meet the security requirements of typical sites. <p></p>
- </li>
- </ol>
-
- <h5>Origin</h5>
- <ol>
-
- <li> The Attribute Authority has a powerful new attribute resolver.
- Simple scenarios (using a string attribute stored in ldap) can be
- accomplished by merely editing a configuration file. Java classes
- may still be written for more complex evaluations (eg retrieving information
- from multiple disparate repositories, and computing the SAML attribute
- using business rules). This should greatly simplify the process of
- configuring the AA to support additional general attributes.<br>
- </li>
- </ol>
-
- <h5>Target</h5>
- <ol>
- <li> Significantly more flexibility in configuring targets to ensure
- robustness. Failover and redundant configurations are now supported.
- <br>
- <ol>
- <li>The SHAR may now optionally store its session and attribute
- cache in a back-end database in addition to the previously available
- in-memory option. This would allow a site to run an apache server
- farm, with multiple SHARs, supporting the same set of sessions.
- </li>
- <li>Federation supplied files (sites.xml and trust.xml) are now
- refreshed in a much more robust manner. <br>
- </li>
-
- </ol>
- </li>
- <li>Attribute acceptance policies have been greatly enhanced, and now
- supports filtering of attribute values by sites. <br>
- </li>
- <li>The SHAR can be configured to request specific attributes from the
- Origin. <br>
- </li>
- </ol>
- <h5>Miscellaneous</h5>
- <ol>
- <li>Origin sites can configure a value to describe the type of authentication
- mechanism used at the origin site(e.g. password, Kerberos, PKI, etc.).
- This value is made available on the target side as Shib-Authentication-Method.
- <br>
- </li>
- <li>Various improvements to error handling. Origin sites are now able
- to supply an "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>
- </ol>
-
- <p>Before starting, please sign up for all applicable <a href=
- "http://shibboleth.internet2.edu/shib-misc.html#mailinglist">
- mailing lists</a>. Announcements pertinent to Shibboleth
- deployments and developments and resources for deployment
- 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>.
- This should include, but not be limited to, questions about the
- documentation, undocumented problems, installation or
- operational issues, and anything else that arises. Please
- ensure that you have the <a href=
- "http://shibboleth.internet2.edu/release/shib-download.html">appropriate
- .tarball</a> for your operating system.</p>
- <br>
- <hr>
- <br>
- <br>
-
-
- <h3><a name="TOC"></a>Shibboleth Origin -- Table of
- Contents</h3>
+.feature
+{
+color: #00FF00
+}
+ </style>
+</head>
+
+<body link="red" vlink="red" alink="black" bgcolor="white">
+
+<center>
+<h2>Shibboleth Origin Deployment Guide</h2>
+</center>
+<p>Shibboleth Origin Deployment Guide<br>
+Shibboleth Version 1.1<br>
+July 28, 2003<br>
+</p>
+<h3>This version of the deploy guide is for Shibboleth v1.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.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.1 are marked with <span class="feature">
+[1.1]</span></p>
+<h4>Major New Features in 1.0 and 1.1</h4>
+<p>This new release contains several improvements and enhancements, including:
+</p>
+<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. </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>
+<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.</li>
+ <li>A sample resolver file for using standard LDAP person and inetOrgPerson
+ attributes is included. <span class="feature">[1.1]</span></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.1]</span></li>
+ <li>Specialized sites without privacy needs can configure identity-based
+ handles interoperable with other SAML deployments. <span class="feature">
+ [1.1]</span></li>
+</ol>
+<h5>Target</h5>
+<ol>
+ <li>Significantly more flexibility in configuring targets is provided 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.
+ </li>
+ <span class="feature">[1.1]</span> </li>
+ <li>Federation supplied files (sites.xml and trust.xml) are now refreshed in
+ a much more robust manner. </li>
+ </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.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.1]</span> </li>
+ <li>Support for Apache 1.3 on Windows NT/2000/XP/2003 has been added.
+ <span class="feature">[1.1]</span> </li>
+ <li>Microsoft IIS web server support has been added via an ISAPI filter and
+ extension. <span class="feature">[1.1]</span> </li>
+</ol>
+<h5>Miscellaneous</h5>
+<ol>
+ <li>Origin sites can configure a value to describe the type of
+ authentication mechanism used at the origin site (e.g. password, Kerberos,
+ PKI, etc.). This value is made available on the target side as Shib-Authentication-Method.
<br>
-
-
- <ol type="1">
- <li>
- <h4><a href="#1."><font color="black">Shibboleth
- Overview</font></a></h4>
-
- <ol type="a">
- <li><a href="#1.a."><font color=
- "black">Origin</font></a></li>
-
- <li><a href="#1.b."><font color=
- "black">Target</font></a></li>
-
- <li><a href="#1.c."><font color=
- "black">WAYF</font></a></li>
-
- <li><a href="#1.d."><font color=
- "black">Federations</font></a></li>
- </ol>
- </li>
-
- <li>
- <h4><a href="#2."><font color=
- "black">Planning</font></a></h4>
-
- <ol type="a">
- <li><a href="#2.a."><font color=
- "black">Requirements</font></a></li>
-
- <li><a href="#2.b."><font color="black">Join a
- Federation</font></a></li>
-
- <li><a href="#2.c."><font color="black">Security
- Considerations</font></a></li>
-
- <li><a href="#2.d."><font color="black">Server
- Certs</font></a></li>
-
- <li><a href="#2.e."><font color="black">Attribute Release
- Policies</font></a></li>
-
- <li><a href="#2.f."><font color="black">Designate
- Contacts</font></a></li>
-
- <li><a href="#2.g."><font color="black">Browser
- Requirements</font></a></li>
-
- <li><a href="#2.h."><font color=
- "black">Clocks</font></a></li>
-
- <li><a href="#2.i."><font color="black">Other
- Considerations</font></a></li>
+ </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>
+</ol>
+<p>Before starting, please sign up for all applicable
+<a href="http://shibboleth.internet2.edu/shib-misc.html#mailinglist">mailing
+lists</a>. Announcements pertinent to Shibboleth deployments and developments
+and resources for deployment 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>.
+This should include, but not be limited to, questions about the documentation,
+undocumented problems, installation or operational issues, and anything else
+that arises. Please ensure that you have the
+<a href="http://shibboleth.internet2.edu/release/shib-download.html">appropriate
+.tarball</a> for your operating system.</p>
+<p><br>
+</p>
+<hr>
+<p><br>
+<br>
+</p>
+<h3><a name="TOC"></a>Shibboleth Origin -- Table of Contents</h3>
+<p><br>
+</p>
+<ol type="1">
+ <li>
+ <h4><a href="#1."><font color="black">Shibboleth Overview</font></a></h4>
+ <ol type="a">
+ <li><a href="#1.a."><font color="black">Origin</font></a></li>
+ <li><a href="#1.b."><font color="black">Target</font></a></li>
+ <li><a href="#1.c."><font color="black">WAYF</font></a></li>
+ <li><a href="#1.d."><font color="black">Federations</font></a></li>
+ </ol>
+ </li>
+ <li>
+ <h4><a href="#2."><font color="black">Planning</font></a></h4>
+ <ol type="a">
+ <li><a href="#2.a."><font color="black">Requirements</font></a></li>
+ <li><a href="#2.b."><font color="black">Join a Federation</font></a></li>
+ <li><a href="#2.c."><font color="black">Security Considerations</font></a></li>
+ <li><a href="#2.d."><font color="black">Server Certs</font></a></li>
+ <li><a href="#2.e."><font color="black">Attribute Release Policies</font></a></li>
+ <li><a href="#2.f."><font color="black">Designate Contacts</font></a></li>
+ <li><a href="#2.g."><font color="black">Browser Requirements</font></a></li>
+ <li><a href="#2.h."><font color="black">Clocks</font></a></li>
+ <li><a href="#2.i."><font color="black">Other Considerations</font></a></li>
+ </ol>
+ </li>
+ <li>
+ <h4><a href="#3."><font color="black">Installation</font></a></h4>
+ <ol type="a">
+ <li><a href="#3.a."><font color="black">Software Requirements</font></a></li>
+ <li><a href="#3.b."><font color="black">Deploy HS and AA</font></a></li>
+ </ol>
+ </li>
+ <li>
+ <h4><a href="#4."><font color="black">Getting Running</font></a></h4>
+ <ol type="a">
+ <li><a href="#4.a."><font color="black">Basic Configuration</font></a>
+ <ol type="i">
+ <li><a href="#4.a.i"><font color="black">Modifying the default
+ Attribute Resolver configuration</font></a></li>
</ol>
- </li>
-
- <li>
- <h4><a href="#3."><font color=
- "black">Installation</font></a></h4>
-
- <ol type="a">
- <li><a href="#3.a."><font color="black">Software
- Requirements</font></a></li>
-
- <li><a href="#3.b."><font color="black">Deploy HS and
- AA</font></a></li>
-
+ </li>
+ <li><a href="#4.b."><font color="black">Key Generation and Certificate
+ Installation</font></a> </li>
+ <li><a href="#4.c."><font color="black">Linking the Authentication
+ System to the HS</font></a>
+ <ol type="i">
+ <li><a href="#4.c.i."><font color="black">Enabling client
+ certificate authentication</font> <font color="#5555EE">(optional)</font></a></li>
</ol>
- </li>
-
- <li>
- <h4><a href="#4."><font color="black">Getting
- Running</font></a></h4>
-
- <ol type="a">
- <li><a href="#4.a."><font color="black">Basic
- Configuration</font></a></li>
-
- <li>
- <a href="#4.b."><font color="black">Key Generation and
- Certificate Installation</font></a>
-
- </li>
-
- <li><a href="#4.c."><font color="black">Linking the
- Authentication System to the HS</font></a>
-
- <ol type="i">
- <li><a href="#4.c.i."><font color="black">Enabling client
- certificate authentication</font> <font color="#5555EE">(optional)</font></a></li>
- </ol>
- </li>
-
- <li><a href="#4.d."><font color="black">Establishing
- default ARP's for the origin community</font></a></li>
-
- <li><a href="#4.e."><font color="black">Modifying the
- default Attribute Resolver configuration</font></a></li>
-
+ </li>
+ <li><a href="#4.d."><font color="black">Establishing default ARP's for
+ the origin community</font></a></li>
+ </ol>
+ </li>
+ <li>
+ <h4><a href="#5."><font color="black">Advanced Configuration</font></a></h4>
+ <ol type="a">
+ <li><a href="#5.a."><font color="black"><span class="fixedwidth">
+ origin.properties</span></font></a></li>
+ <li><a href="#5.b."><font color="black">ARP Overview</font></a>
+ <ol type="i">
+ <li><a href="#5.b.i."><font color="black">ARP Processing</font></a></li>
+ <li><a href="#5.b.ii."><font color="black">ARP Syntax</font></a></li>
</ol>
- </li>
-
- <li>
- <h4><a href="#5."><font color="black">Advanced
- Configuration</font></a></h4>
-
- <ol type="a">
- <li>
- <a href="#5.a."><font color="black">ARP
- Overview</font></a>
-
- <ol type="i">
- <li><a href="#5.a.i."><font color="black">ARP
- Processing</font></a></li>
-
- <li><a href="#5.a.ii."><font color="black">ARP
- Syntax</font></a></li>
- </ol>
- <li><a href="#5.b."><font color="black">Sharing
- certificate/key pairs between Apache and Java
- keystores</font> <font color="#5555EE">(optional)</font></a></li>
- <li><a href="#5.c."><font color="black">The Attribute Resolver</font></a></li>
- <li><a href="#5.d."><font color="black">Local Error Page</font></a></li>
+ </li>
+ <li><a href="#5.c."><font color="black">Sharing certificate/key pairs
+ between Apache and Java keystores</font> <font color="#5555EE">
+ (optional)</font></a></li>
+ <li><a href="#5.d."><font color="black">The Attribute Resolver</font></a>
+ <ol type="i">
+ <li><a href="#5.d.i."><font color="black"><span class="fixedwidth">
+ resolvertest</span></font></a></li>
</ol>
- </li>
-
- <li>
- <h4><a href="#6."><font color=
- "black">Troubleshooting</font></a></h4>
-
- <ol type="a">
- <li><a href="#6.a."><font color="black">Basic
- Testing</font></a></li>
-
- <li><a href="#6.b."><font color=
- "black">Logging</font></a></li>
-
- <li><a href="#6.c."><font color="black">Common
- Problems</font></a></li>
+ </li>
+ <li><a href="#5.e."><font color="black">Local Error Page</font></a></li>
+ </ol>
+ </li>
+ <li>
+ <h4><a href="#6."><font color="black">Troubleshooting</font></a></h4>
+ <ol type="a">
+ <li><a href="#6.a."><font color="black">Basic Testing</font></a></li>
+ <li><a href="#6.b."><font color="black">Logging</font></a></li>
+ <li><a href="#6.c."><font color="black">Common Problems</font></a></li>
+ </ol>
+ </li>
+</ol>
+<p><br>
+</p>
+<hr>
+<p><br>
+</p>
+<h3><a name="1."></a>1. Shibboleth Overview</h3>
+<p>Shibboleth is a system designed to exchange attributes across realms for the
+primary purpose of authorization. It provides a secure framework for one
+organization to transmit attributes about a web-browsing individual across
+security domains to another institution. In the primary usage case, when a user
+attempts to access a resource at a remote domain, the user's own home security
+domain can send certain information about that user to the target site in a
+trusted exchange. These attributes can then be used by the resource to help
+determine whether to grant the user access to the resource. The user may have
+the ability to decide whether to release specific attributes to certain sites by
+specifying personal Attribute Release Policies (ARP's), effectively preserving
+privacy while still granting access based on trusted information.</p>
+<p>When a user first tries to access a resource protected by Shibboleth, they
+are redirected to a service which asks the user to specify the organization from
+which they want to authenticate. If the user has not yet locally authenticated
+to a WebISO service, the user will then be redirected to their home
+institution's authentication system. After the user authenticates, the
+Shibboleth components at the local institution will generate a temporary
+reference to the user, known as a handle, for the individual and send this to
+the target site. The target site can then use the handle to ask for attributes
+about this individual. Based on these attributes, the target can decide whether
+or not to grant access to the resource. The user may then be allowed to access
+the requested materials.</p>
+<p>There are several controls on privacy in Shibboleth, and mechanisms are
+provided to allow users to determine exactly which information about them is
+released. A user's actual identity isn't necessary for many access control
+decisions, so privacy often is needlessly compromised. Instead, the resource
+often utilizes other attributes such as faculty member or member of a certain
+class. While these are commonly determined using the identity of the user,
+Shibboleth provides a way to mutually refer to the same principal without
+revealing that principal's identity. Because the user is initially known to the
+target site only by a randomly generated temporary handle, if sufficient, the
+target site might know no more about the user than that the user is a member of
+the origin organization. This handle should never be used to decide whether or
+not to grant access, and is intended only as a temporary reference for
+requesting attributes.</p>
+<h4><a name="1.a."></a>1.a. Origin</h4>
+<blockquote>
+ <p>There are four primary components to the origin side in 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 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 designed such that programming interfaces
+ to other repositories should be readily implemented. Shibboleth relies on
+ standard web server mechanisms to trigger local authentication. A .htaccess
+ file can be easily used to trigger either the local WebISO system or the web
+ server's own Basic Auth mechanism, which will likely utilize an enterprise
+ authentication system, such as Kerberos.</p>
+ <p>From the origin site's point of view, the first contact will be the
+ redirection of a user to the handle service, which will then consult the SSO
+ system to determine whether the user has already been authenticated. If not,
+ then the browser user will be asked to authenticate, and then sent back to
+ the target URL with a handle bundled in an attribute assertion. Next, a
+ request from the Shibboleth Attribute Requester (SHAR) will arrive at the AA
+ which will include the previously mentioned handle. The AA then consults the
+ ARP's for the directory entry corresponding to the handle, queries the
+ directory for these attributes, and releases to the SHAR all attributes the
+ SHAR is entitled to know about that user.</p>
+</blockquote>
+<h4><a name="1.b."></a>1.b. Target</h4>
+<blockquote>
+ <p>There are three primary components to the target side in Shibboleth: the
+ Shibboleth Indexical Reference Establisher (SHIRE), the Shibboleth Attribute
+ Requester (SHAR), and the resource manager (RM). An implementation of each
+ of these is included in the standard Shibboleth distribution. These
+ components are intended to run on the same web server.</p>
+ <p>From the target's point of view, a browser will hit the RM with a request
+ for a Shibboleth-protected resource. The RM then allows the SHIRE to step
+ in, which will use the WAYF to acquire the name of a handle service to ask
+ about the user. The handle service (HS) will then reply with a SAML
+ authentication assertion containing a handle, which the SHIRE then hands off
+ to the SHAR. The SHAR uses the handle and the supplied address of the
+ corresponding attribute authority (AA) to request all attributes it is
+ allowed to know about the handle. The SHAR performs some basic validation
+ and analysis based on attribute acceptance policies (AAP's). These
+ attributes are then handed off to the RM, which is responsible for using
+ these attributes to decide whether to grant access.</p>
+</blockquote>
+<h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
+<blockquote>
+ <p>The WAYF service can be either outsourced and operated by a federation or
+ deployed as part of the SHIRE. It is responsible for allowing a user to
+ associate themself with an institution of their specification, then
+ redirecting the user to the known address for the handle service of that
+ institution.</p>
+</blockquote>
+<h4><a name="1.d."></a>1.d. Federations</h4>
+<blockquote>
+ <p>A Shibboleth federation provides part of the underlying trust required
+ for function of the Shibboleth architecture. A federation is a group of
+ organizations(universities, corporations, content providers, etc.) who agree
+ to exchange attributes using the SAML/Shibboleth protocols and abide by a
+ common set of policies and practices. In so doing, they must implicitly or
+ explicitly agree to a common set of guidelines. Joining a federation is not
+ explicitly necessary for operation of Shibboleth, but it dramatically
+ expands the number of targets and origins that can interact without defining
+ bilateral agreements between all these parties.</p>
+ <p>A federation can be created in a variety of formats and trust models, but
+ must provide a certain set of services to federation members. It needs to
+ supply a registry to process applications to the federation and distribute
+ membership information to the origin and target sites. This must include
+ distribution of the PKI components necessary for trust between origins and
+ targets. There also needs to be a set of agreements and best practices
+ defined by the federation governing the exchange, use, and population of
+ attributes before and after transit, and there should be a way to find
+ information on local authentication and authorization practices for
+ federation members.</p>
+</blockquote>
+<p><br>
+<br>
+<br>
+</p>
+<hr>
+<p><br>
+</p>
+<h3><a name="2."></a>2. Planning</h3>
+<p>There are several essential elements that must be present in the environment
+to ensure Shibboleth functions well, both political and technical. Shibboleth is
+entirely written in Java on the origin side. These are the recommendations and
+requirements for a successful implementation of a Shibboleth origin.</p>
+<h4><a name="2.a."></a>2.a. Requirements</h4>
+<ul>
+ <li>A common institutional directory service should be operational;
+ Shibboleth comes with LDAP capabilities built in, and the Attribute
+ Authority has a Java API which will allow specification of interfaces with
+ legacy directories. This is discussed further in <a href="#4.d.">section 4.d</a>.</li>
+ <li>A method to authenticate browser users must be in place, preferably in
+ the form of an enterprise authentication service. Some form of an SSO or a
+ WebISO service is not explicitly necessary for Shibboleth; however, it is
+ highly recommended. Implementation details of this are discussed in
+ <a href="#4.c.">section 4.c</a>.</li>
+ <li>Shibboleth is known to work on Linux and Solaris, but should function on
+ any platform that has a Tomcat implementation.</li>
+ <li>It is recommended that a web server must be deployed that can host Java
+ servlets and Tomcat, although not explicitly necessary, as Tomcat can still
+ host an origin without it.</li>
+</ul>
+<h4><a name="2.b."></a>2.b. Join a Federation</h4>
+<blockquote>
+ <p>While it is not necessary for a target or origin to join a federation,
+ doing so greatly facilitates the implementation of multilateral trust
+ relationships. Each federation will have a different application process.
+ When an origin is accepted into a federation, its information is added to
+ the sites file used by the WAYF and target sites.</p>
+ <p><b>It may be necessary to join multiple federations depending on the
+ sites with whom you wish to exchange attributes and the terms under which
+ these interactions will take place. An origin site exists within the context
+ of a single federation, while a single target may accept assertions issued
+ by multiple federations if they are all recognized by the SHAR. If an
+ organization wishes to be a member of multiple federations, it must run a
+ separate origin site for each federation, including a separate AA and HS.</b></p>
+ <p>Attribute release and acceptance policies, the use and caching of
+ attributes, and definition of commonly traded attributes are examples of
+ specifications a federation may make. For more information on federations,
+ please refer to the Deployer's Guide to Federations and the Shibboleth v1.0
+ architectural document.</p>
+</blockquote>
+<h4><a name="2.c."></a>2.c. Security Considerations</h4>
+<blockquote>
+ <p>Shibboleth's protocols and software have been extensively engineered to
+ provide protection against many attacks. However, the most secure protocol
+ can be compromised if it is placed in an insecure environment. To ensure
+ Shibboleth is as secure as possible, there are several recommended security
+ precautions which should be in place at local sites.</p>
+ <ol type="i">
+ <li>SSL use is optional for origin sites. Federation guidelines should
+ be considered when determining whether to implement SSL, and, in
+ general, SSL should be used for interactions with client machines to
+ provide the necessary authentication and encryption to ensure protection
+ from man-in-the-middle attacks. It is strongly suggested that all
+ password traffic or similarly sensitive data should be SSL-protected.
+ Assessment of the risk tradeoff against possible performance degradation
+ should be performed for all applications.</li>
+ <li>Many other attacks can be made on the several redirection steps that
+ Shibboleth takes to complete attribute transfer. The best protection
+ against this is safeguarding the WAYF service and ensuring that rogue
+ targets and origins are not used, generally by development of the trust
+ model underneath Shibboleth. Shibboleth also leverages DNS for security,
+ which is not uncommon, but attacks concerning bad domain information
+ should be considered.</li>
+ <li>Information regarding origin users is generally provided by the
+ authoritative enterprise directory, and the acceptance of requests from
+ target applications can be carefully restricted to ensure that all
+ requests the SHAR performs are authorized and all information the origin
+ provides is accurate. Proper security measures should also be in place
+ on directory access and population(see
+ <a href="http://www.georgetown.edu/giia/internet2/ldap-recipe/#AccessControl">
+ Access Control</a> in the
+ <a href="http://www.georgetown.edu/giia/internet2/ldap-recipe/">LDAP
+ recipe</a> for more information). Use of plaintext passwords is strongly
+ advised against.</li>
+ <li>Server platforms should be properly secured, commensurate with the
+ level that would be expected for a campus' other security services, and
+ cookie stores on client machines should be well protected.</li>
+ </ol>
+</blockquote>
+<h4><a name="2.d."></a>2.d. Server Certs</h4>
+<blockquote>
+ <p>In the Shibboleth architecture, the SHIRE, SHAR, HS, and AA must all have
+ various client and/or server certificates for use in signing assertions and
+ creating SSL channels. These should be issued by a commonly accepted CA,
+ which may be stipulated by some Federation rules. Different federations may
+ require the use of different CA's.</p>
+</blockquote>
+<h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
+<blockquote>
+ <p>The Attribute Authority maintains a set of policies called Attribute
+ Release Policies (or ARP's) that govern the sharing of user attributes with
+ Shibboleth target sites. When a user attempts to access a
+ Shibboleth-protected resource, that resource's SHAR queries the user's AA
+ for all attributes to which it is entitled. The SHAR provides its own name
+ and the URL of the resource on behalf of which it is making the request. The
+ AA finds the attributes associated with the browser user, determines an
+ "Effective ARP" for this user, and then sends to the SHAR only the
+ attributes/values allowed in this policy.</p>
+ <p>An ARP may be thought of as a sort of filter for outbound attributes; it
+ cannot create attributes or data that aren't originally present, but it can
+ limit the attributes released and the values those attributes may have when
+ released. It does not change the information in the data sources in any way.</p>
+ <p>Each ARP is comprised of one or more rules that specify which attributes
+ and values may be released to a target or set of targets. The assignment of
+ rules to various targets is quite flexible and includes mechanisms for
+ specifying: that a rule should affect all targets (default rule), exact SHAR
+ names for which a rule is applicable, regular expressions against which SHAR
+ names should be matched to determine if a rule is applicable, URL trees for
+ which a rule is applicable.</p>
+ <p>For each request, an Effective ARP is determined by locating all ARP's
+ applicable to the designated user and extracting each rule that matches the
+ querying SHAR and resource. Attributes and values that are specified for
+ release are included in the effective ARP, while those specified for denial
+ are blocked from release. See section <a href="#5.b.i.">5.b.i</a> for
+ details on how ARP's are processed.</p>
+ <p>Various ARP's may be combined in forming the Effective ARP. For instance,
+ the Site ARP is administratively maintained and applies to all users for
+ which the AA is answerable. User ARP's apply to a specific user only, and
+ can be maintained either administratively or by the users themselves. All
+ ARP's are specified using the same syntax and semantics.</p>
+</blockquote>
+<h4><a name="2.f."></a>2.f. Designate Contacts</h4>
+<blockquote>
+ <p>Since Shibboleth deals both with daily technical and operational issues
+ and also with contractual issues, a set of contacts should be set up to
+ support the user base and to facilitate interactions with other Shibboleth
+ sites and federation members. It is recommended that at least technical and
+ administrative contacts be designated.</p>
+</blockquote>
+<h4><a name="2.g."></a>2.g. Browser Requirements</h4>
+<blockquote>
+ <p>A primary Shibboleth design consideration was to require very little or
+ no modification to client machines. The only requirement is that a browser
+ is used which supports cookies, redirection and SSL. Browser users will have
+ to perform an additional click to submit the authentication assertion if
+ JavaScript is not functional.</p>
+</blockquote>
+<h4><a name="2.h."></a>2.h. Clocks</h4>
+<blockquote>
+ <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should be run on all
+ web servers. Shibboleth employs a short handle issuance time to protect
+ against replay attacks. Because of this, any significant degree of clock
+ skew can hinder the ability of users to access sites successfully.</p>
+</blockquote>
+<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>
+<p><br>
+<br>
+</p>
+<hr>
+<p><br>
+</p>
+<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>Ensure you have already obtained the proper
+ <a href="http://shibboleth.internet2.edu/release/shib-download.html">.tarball</a>.</li>
+ <li>The archive will expand into a <span class="fixedwidth">
+ shibboleth-origin-1.1/</span> directory(<span class="fixedwidth">/opt/</span>
+ recommended).</li>
+ <li>Run the following command to move the Java files into Tomcat's tree:<blockquote>
+ <p><span class="fixedwidth">cp /opt/shibboleth-origin-1.1/dist/shibboleth.war
+ /usr/local/tomcat/webapps/</span> </p>
+ </blockquote>
+ </li>
+ <li>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:<blockquote>
+ <p><span class="fixedwidth">$ cp
+ /opt/shibboleth-origin-1.1/endorsed/*.jar /usr/local/tomcat/common/endorsed</span>
+ </p>
+ </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.</li>
+ <li>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>.</li>
+ <li>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>:<blockquote>
+ <p><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> </p>
+ </blockquote>
+ </li>
+ <li>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:<ol type="A">
+ <li>Add <span class="fixedwidth">address="127.0.0.1"</span> inside
+ the <span class="fixedwidth"><Ajp13Connector></span> configuration
+ element to prevent off-host access.</li>
+ <li>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.</li>
</ol>
- </li>
+ </li>
+ <li>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>:<blockquote>
+ <p><span class="fixedwidth"><Location /shibboleth/AA>
+ SSLVerifyClient optional SSLOptions +StdEnvVars +ExportCertData
+ </Location> </span></p>
+ </blockquote>
+ </li>
</ol>
- <br>
- <hr>
- <br>
-
-
- <h3><a name="1."></a>1. Shibboleth Overview</h3>
-
- <p>Shibboleth is a system designed to exchange attributes
- across realms for the primary purpose of authorization. It
- provides a secure framework for one organization to transmit
- attributes about a web-browsing individual across security
- domains to another institution. In the primary usage case, when
- a user attempts to access a resource at a remote domain, the
- user's own home security domain can send certain information
- about that user to the target site in a trusted exchange. These
- attributes can then be used by the resource to help determine
- whether to grant the user access to the resource. The user may
- have the ability to decide whether to release specific
- attributes to certain sites by specifying personal Attribute
- Release Policies (ARP's), effectively preserving privacy while
- still granting access based on trusted information.</p>
-
- <p>When a user first tries to access a resource protected by
- Shibboleth, they are redirected to a service which asks the
- user to specify the organization from which they want to
- authenticate. If the user has not yet locally authenticated to
- a WebISO service, the user will then be redirected to their
- home institution's authentication system. After the user
- authenticates, the Shibboleth components at the local
- institution will generate a temporary reference to the user,
- known as a handle, for the individual and send this to the
- target site. The target site can then use the handle to ask for
- attributes about this individual. Based on these attributes,
- the target can decide whether or not to grant access to the
- resource. The user may then be allowed to access the requested
- materials.</p>
-
- <p>There are several controls on privacy in Shibboleth, and
- mechanisms are provided to allow users to determine exactly
- which information about them is released. A user's actual
- identity isn't necessary for many access control decisions, so
- privacy often is needlessly compromised. Instead, the resource
- often utilizes other attributes such as faculty member or member
- of a certain class. While these are commonly determined using
- the identity of the user, Shibboleth provides a way to mutually
- refer to the same principal without revealing that principal's
- identity. Because the user is initially known to the target site
- only by a randomly generated temporary handle, if sufficient,
- the target site might know no more about the user than that the
- user is a member of the origin organization. This handle should
- never be used to decide whether or not to grant access, and is
- intended only as a temporary reference for requesting
- attributes.</p>
-
- <h4><a name="1.a."></a>1.a. Origin</h4>
-
+</blockquote>
+<p><br>
+</p>
+<hr>
+<p><br>
+</p>
+<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>
+ <p>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.</p>
+ </blockquote>
+ </li>
+ <li><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName = <URI></span>
+ <blockquote>
+ <p>The value of this must entered as assigned by the federation used
+ for testing or initial operation.</p>
+ </blockquote>
+ </li>
+ <li><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl = <url></span>
+ <blockquote>
+ <p>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.</p>
+ </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>
+ <p>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.</p>
+ </blockquote>
+ </li>
+ <li><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.aa.AAServlet.authorityName = <domain
+ name></span>
+ <blockquote>
+ <p>Specifies the name of the AA, which is typically the domain name
+ of the server running it.</p>
+ </blockquote>
+ </li>
+ <li><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.audiences = <URI></span>
+ <blockquote>
+ <p>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.</p>
+ </blockquote>
+ </li>
+ </ol>
+</blockquote>
+<p><br>
+</p>
+<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>
+<p><br>
+</p>
+<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>
- <p>There are four primary components to the origin side in
- 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
- 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
- designed such that programming interfaces to other
- repositories should be readily implemented. Shibboleth relies
- on standard web server mechanisms to trigger local
- authentication. A .htaccess file can be easily used to trigger
- either the local WebISO system or the web server's own Basic
- Auth mechanism, which will likely utilize an enterprise
- authentication system, such as Kerberos.</p>
-
- <p>From the origin site's point of view, the first contact
- will be the redirection of a user to the handle service,
- which will then consult the SSO system to determine whether
- the user has already been authenticated. If not, then the
- browser user will be asked to authenticate, and then sent
- back to the target URL with a handle bundled in an attribute
- assertion. Next, a request from the Shibboleth Attribute
- Requester (SHAR) will arrive at the AA which will include the
- previously mentioned handle. The AA then consults the ARP's
- for the directory entry corresponding to the handle, queries
- the directory for these attributes, and releases to the SHAR
- all attributes the SHAR is entitled to know about that
- user.</p>
+ <p><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></p>
</blockquote>
-
- <h4><a name="1.b."></a>1.b. Target</h4>
-
+ <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>
- <p>There are three primary components to the target side in
- Shibboleth: the Shibboleth Indexical Reference Establisher
- (SHIRE), the Shibboleth Attribute Requester (SHAR), and the
- resource manager (RM). An implementation of each of these is
- included in the standard Shibboleth distribution. These
- components are intended to run on the same web server.</p>
-
- <p>From the target's point of view, a browser will hit the RM
- with a request for a Shibboleth-protected resource. The RM
- then allows the SHIRE to step in, which will use the WAYF to
- acquire the name of a handle service to ask about the user.
- The handle service (HS) will then reply with a SAML
- authentication assertion containing a handle, which the SHIRE
- then hands off to the SHAR. The SHAR uses the handle and the
- supplied address of the corresponding attribute authority
- (AA) to request all attributes it is allowed to know about
- the handle. The SHAR performs some basic validation and
- analysis based on attribute acceptance policies (AAP's).
- These attributes are then handed off to the RM, which is
- responsible for using these attributes to decide whether to
- grant access.</p>
+ <p><span class="fixedwidth">$ keytool -certreq -keystore keystore.jks
+ -alias hs -file <csr-file><br>
+ </span></p>
</blockquote>
-
- <h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
-
+ <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>
- <p>The WAYF service can be either outsourced and operated by
- a federation or deployed as part of the SHIRE. It is responsible
- for allowing a user to associate themself with an institution
- of their specification, then redirecting the user to the
- known address for the handle service of that institution.</p>
+ <p><span class="fixedwidth">$ keytool -import -keystore keystore.jks
+ -alias hs -file <cert-file></span> </p>
</blockquote>
-
- <h4><a name="1.d."></a>1.d. Federations</h4>
-
+ <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>
- <p>A Shibboleth federation provides part of the underlying trust
- required for function of the Shibboleth architecture. A federation
- is a group of organizations(universities, corporations,
- content providers, etc.) who agree to exchange attributes
- using the SAML/Shibboleth protocols and abide by a common set
- of policies and practices. In so doing, they must implicitly
- or explicitly agree to a common set of guidelines. Joining a
- federation is not explicitly necessary for operation of Shibboleth,
- but it dramatically expands the number of targets and origins
- that can interact without defining bilateral agreements
- between all these parties.</p>
-
- <p>A federation can be created in a variety of formats and trust
- models, but must provide a certain set of services to federation
- members. It needs to supply a registry to process
- applications to the federation and distribute membership
- information to the origin and target sites. This must include
- distribution of the PKI components necessary for trust
- between origins and targets. There also needs to be a set of
- agreements and best practices defined by the federation governing
- the exchange, use, and population of attributes before and
- after transit, and there should be a way to find information
- on local authentication and authorization practices for federation
- members.</p>
+ <p><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></p>
</blockquote>
- <br>
- <br>
- <br>
- <hr>
- <br>
-
-
- <h3><a name="2."></a>2. Planning</h3>
-
- <p>There are several essential elements that must be present in
- the environment to ensure Shibboleth functions well, both
- political and technical. Shibboleth is entirely written in
- Java on the origin side. These are the recommendations and
- requirements for a successful implementation of a Shibboleth
- origin.</p>
-
- <h4><a name="2.a."></a>2.a. Requirements</h4>
-
- <ul>
- <li>
- <p>A common institutional directory service should be
- operational; Shibboleth comes with LDAP capabilities
- built in, and the Attribute Authority has a Java API which
- will allow specification of interfaces with legacy
- directories. This is discussed further in <a href=
- "#4.d.">section 4.d</a>.</p>
- </li>
-
- <li>
- <p>A method to authenticate browser users must be in place,
- preferably in the form of an enterprise authentication
- service. Some form of an SSO or a WebISO service is not
- explicitly necessary for Shibboleth; however, it is highly
- recommended. Implementation details of this are discussed in
- <a href="#4.c.">section 4.c</a>.</p>
- </li>
-
- <li>
- <p>Shibboleth is known to work on Linux and Solaris, but
- should function on any platform that has a Tomcat
- implementation.</p>
- </li>
-
- <li>
- <p>It is recommended that a web server must be deployed that
- can host Java servlets and Tomcat, although not explicitly
- necessary, as Tomcat can still host an origin without it.</p>
- </li>
- </ul>
-
- <h4><a name="2.b."></a>2.b. Join a Federation</h4>
-
+ <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>While it is not necessary for a target or origin to join a
- federation, doing so greatly facilitates the implementation of
- multilateral trust relationships. Each federation will have a
- different application process. When an origin is accepted into a
- federation, its information is added to the sites file used by the
- WAYF and target sites.</p>
-
- <p><b>It may be necessary to join multiple federations
- depending on the sites with whom you wish to exchange
- attributes and the terms under which these interactions will
- take place. An origin site exists within the context of a
- single federation, while a single target may accept assertions
- issued by multiple federations if they are all recognized by
- the SHAR. If an organization wishes to be a member of
- multiple federations, it must run a separate origin site for
- each federation, including a separate AA and HS.</b></p>
-
- <p>Attribute release and acceptance policies, the use and
- caching of attributes, and definition of commonly traded
- attributes are examples of specifications a federation may
- make. For more information on federations, please refer to
- the Deployer's Guide to Federations and the Shibboleth v1.0
- architectural document.</p>
+ <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>
+ <p><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></p>
+ </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>
+ <p><span class="fixedwidth">regex: '.*CN=([^,/]+).*' match group: 1</span>
+ </p>
+ </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>
-
- <h4><a name="2.c."></a>2.c. Security Considerations</h4>
-
+</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>
+<p><br>
+</p>
+<hr>
+<p><br>
+</p>
+<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>
+ <p><br>
+ </p>
+ <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">Specifies the DNS name the HS should use for itself in
+ issuing assertions.</dd>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName = <URI></span>
+ </dd>
+ <dd class="value">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.</dd>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl = <url></span>
+ </dd>
+ <dd class="value">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.</dd>
+ <dd class="attributeoptlong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.username = <var></span>
+ </dd>
+ <dd class="valueopt">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>.</dd>
+ <dd class="attributeoptlong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.authMethod = <uri></span>
+ </dd>
+ <dd class="valueopt">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.<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>
+ <p><br>
+ </p>
+ <p>Assertion Signing:</p>
+ <dl>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath =
+ <pathname></span> </dd>
+ <dd class="value">Specifies the location of the Java keystore containing
+ the x.509 certificate and matching private key to be used by the HS.</dd>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword =
+ <password></span> </dd>
+ <dd class="value">Specifies the password to the referenced keystore.</dd>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias =
+ <alias></span> </dd>
+ <dd class="value">Specifies the alias used for accessing the private
+ key.</dd>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword
+ = <password></span> </dd>
+ <dd class="value">Specifies the password used to retrieve the private
+ key.</dd>
+ <dd class="attributeoptlong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias = <alias></span>
+ </dd>
+ <dd class="valueopt">Specifies the alias for the certificate
+ corresponding to the private key used by the HS. Defaults to the private
+ key's alias.</dd>
+ </dl>
+ <p><br>
+ </p>
+ <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">Specifies the name of the AA, which is typically the
+ domain name of the server running it.</dd>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.aa.AAServlet.passThruErrors =
+ <true/false></span> </dd>
+ <dd class="value">Specifies whether the AA should pass on internal
+ errors to the SHAR for debugging purposes. Defaults to
+ <span class="fixedwidth">false</span>.</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">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>.</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">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>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.</dd>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path
+ = <pathname></span> </dd>
+ <dd class="value">Specifies the relative or absolute path to the folder
+ containing the ARP files.</dd>
+ <dd class="attributeoptlong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.ArpTTL
+ = <seconds></span> </dd>
+ <dd class="valueopt">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.</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">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>.</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>
- <p>Shibboleth's protocols and software have been extensively
- engineered to provide protection against many attacks.
- However, the most secure protocol can be compromised if it is
- placed in an insecure environment. To ensure Shibboleth is as
- secure as possible, there are several recommended security
- precautions which should be in place at local sites.</p>
-
- <ol type="i">
- <li>
- <p>SSL use is optional for origin sites. Federation guidelines
- should be considered when determining whether to
- implement SSL, and, in general, SSL should be used for
- interactions with client machines to provide the
- necessary authentication and encryption to ensure
- protection from man-in-the-middle attacks. It is strongly
- suggested that all password traffic or similarly
- sensitive data should be SSL-protected. Assessment of the
- risk tradeoff against possible performance degradation
- should be performed for all applications.</p>
- </li>
-
- <li>
- <p>Many other attacks can be made on the several
- redirection steps that Shibboleth takes to complete
- attribute transfer. The best protection against this is
- safeguarding the WAYF service and ensuring that rogue
- targets and origins are not used, generally by
- development of the trust model underneath Shibboleth.
- Shibboleth also leverages DNS for security, which is not
- uncommon, but attacks concerning bad domain information
- should be considered.</p>
- </li>
-
- <li>
- <p>Information regarding origin users is generally
- provided by the authoritative enterprise directory, and
- the acceptance of requests from target applications can
- be carefully restricted to ensure that all requests the
- SHAR performs are authorized and all information the
- origin provides is accurate. Proper security measures
- should also be in place on directory access and
- population(see <a href=
- "http://www.georgetown.edu/giia/internet2/ldap-recipe/#AccessControl">
- Access Control</a> in the <a href=
- "http://www.georgetown.edu/giia/internet2/ldap-recipe/">LDAP
- recipe</a> for more information). Use of plaintext
- passwords is strongly advised against.</p>
- </li>
-
- <li>
- <p>Server platforms should be properly secured,
- commensurate with the level that would be expected for a
- campus' other security services, and cookie stores on
- client machines should be well protected.</p>
- </li>
- </ol>
+ <dl>
+ <dd class="attributeoptlong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.BaseHandleRepository.handleTTL
+ = <seconds></span> </dd>
+ <dd class="valueopt">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.</dd>
+ </dl>
</blockquote>
-
- <h4><a name="2.d."></a>2.d. Server Certs</h4>
-
+ <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>
- <p>In the Shibboleth architecture, the SHIRE, SHAR, HS, and AA
- must all have various client and/or server certificates for use in
- signing assertions and creating SSL channels. These should be
- issued by a commonly accepted CA, which may be stipulated by some
- Federation rules. Different federations may require the use of
- different CA's.</p>
+ <dl>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePath
+ = <pathname></span> </dd>
+ <dd class="value">Specifies the path to the keystore containing the
+ key used to encrypt passed principal identifiers.</dd>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePassword
+ = <password></span> </dd>
+ <dd class="value">Specifies the password for the keystore.</dd>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyAlias
+ = <password></span> </dd>
+ <dd class="value">Specifies the alias for the appropriate encryption
+ key within the keystore.</dd>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyPassword
+ = <password></span> </dd>
+ <dd class="valueopt">Specifies the password used to retrieve the
+ key.</dd>
+ <dd class="attributeoptlong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.hs.CryptoHandleRepository.handleTTL
+ = <seconds></span> </dd>
+ <dd class="valueopt">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.</dd>
+ </dl>
</blockquote>
-
- <h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
-
+ <p>Federation Configuration:</p>
+ <dl>
+ <dd class="attributelong"><span class="fixedwidth">
+ edu.internet2.middleware.shibboleth.audiences = <URI's></span> </dd>
+ <dd class="value">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>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>
+<p><br>
+</p>
+<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>The Attribute Authority maintains a set of policies called
- Attribute Release Policies (or ARP's) that govern the sharing
- of user attributes with Shibboleth target sites. When a user
- attempts to access a Shibboleth-protected resource, that
- resource's SHAR queries the user's AA for all attributes to
- which it is entitled. The SHAR provides its own name and the
- URL of the resource on behalf of which it is making the
- request. The AA finds the attributes associated with the
- browser user, determines an "Effective ARP" for this user, and
- then sends to the SHAR only the attributes/values allowed in
- this policy.</p>
-
- <p>An ARP may be thought of as a sort of filter for outbound
- attributes; it cannot create attributes or data that aren't
- originally present, but it can limit the attributes released
- and the values those attributes may have when released. It
- does not change the information in the data sources in any
- way.</p>
-
- <p>Each ARP is comprised of one or more rules that specify
- which attributes and values may be released to a target or set
- of targets. The assignment of rules to various targets is
- quite flexible and includes mechanisms for specifying: that a
- rule should affect all targets (default rule), exact SHAR
- names for which a rule is applicable, regular expressions
- against which SHAR names should be matched to determine if a
- rule is applicable, URL trees for which a rule is
- applicable.</p>
-
- <p>For each request, an Effective ARP is determined by
- locating all ARP's applicable to the designated user and
- extracting each rule that matches the querying SHAR and
- resource. Attributes and values that are specified for
- release are included in the effective ARP, while those
- specified for denial are blocked from release. See section <a
- href="#5.a.i.">5.a.i</a> for details on how ARP's are
- processed.</p>
-
-
- <p>Various ARP's may be combined in forming the Effective ARP.
- For instance, the Site ARP is administratively maintained and
- applies to all users for which the AA is answerable. User
- ARP's apply to a specific user only, and can be maintained
- either administratively or by the users themselves. All ARP's
- are specified using the same syntax and semantics.</p>
+ <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>
-
- <h4><a name="2.f."></a>2.f. Designate Contacts</h4>
-
+</blockquote>
+<h4><a name="5.b.ii."></a>5.b.ii. ARP Syntax</h4>
+<blockquote>
<blockquote>
- <p>Since Shibboleth deals both with daily technical and
- operational issues and also with contractual issues, a set of
- contacts should be set up to support the user base and to
- facilitate interactions with other Shibboleth sites and federation
- members. It is recommended that at least technical and
- administrative contacts be designated.</p>
+ <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>
+ <p><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></p>
+ </blockquote>
</blockquote>
-
- <h4><a name="2.g."></a>2.g. Browser Requirements</h4>
-
+ <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>A primary Shibboleth design consideration was to require
- very little or no modification to client machines. The only
- requirement is that a browser is used which supports cookies,
- redirection and SSL. Browser users will have to perform an
- additional click to submit the authentication assertion if
- JavaScript is not functional.</p>
+ <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><span class="fixedwidth">
+ urn:mace:shibboleth:arp:matchFunction:exactShar </span>
+ <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><span class="fixedwidth">
+ urn:mace:shibboleth:arp:matchFunction:resourceTree </span>
+ <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><span class="fixedwidth">
+ urn:mace:shibboleth:arp:matchFunction:regexMatch </span>
+ <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/%20%20%20%20%20%20%20%20%20%20%20%20%20%20regex/Pattern.html#sum">
+ Java 1.4 Pattern API</a>.</p>
+ </blockquote>
+ </li>
+ </ul>
</blockquote>
-
- <h4><a name="2.h."></a>2.h. Clocks</h4>
-
+ <p>The <span class="fixedwidth">Attribute</span> element:</p>
<blockquote>
- <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should
- be run on all web servers. Shibboleth employs a short handle
- issuance time to protect against replay attacks. Because of
- this, any significant degree of clock skew can hinder the
- ability of users to access sites successfully.</p>
+ <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>
+ <p><span class="fixedwidth"><Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName"><br>
+ <AnyValue release="Permit"><br>
+ </Attribute><br>
+ </span><br>
+ </p>
+ <p>Permits the release of <span class="fixedwidth">
+ eduPersonPrincipalName</span> with any value.</p>
+ </blockquote>
+ <blockquote>
+ <p><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>
+ <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.
+
+ <p>There is also a special <span class="fixedwidth">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>
- <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 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>
- </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 two 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">/usr/local/</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 /usr/local/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 /usr/local/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>
- </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>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.</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="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.b.">5.b.</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.a.i.">5.a.i</a>.</p>
- </blockquote>
-
- <h4><a name="4.e."></a>4.e. 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.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> 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>
- <hr>
- <br>
-
- <h3><a name="5."></a>5. Advanced Configuration</h3>
-
- <h4><a name="5.a."></a>5.a. 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>
-
- <!-- ##To be included in future releases of the deploy guide.
-
- <dl>
- <dd class="demo">
- <img src="arp.gif">
- </dd>
- <dd class="demo">
- <p>In this picture, meant to demonstrate the structure
- of ARP's, if all ARP's are taken to mean "Release this
- attribute," then attributes 1-4 will be released if that
- principal tries to access site A. ARP #1 could not
- restrict the release of attribute 4 to site A.</p>
- </dd>
- </dl>
-
- -->
-
- </blockquote>
-
- <h4><a name="5.a.i."></a>5.a.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.a.ii."></a>5.a.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.
-
- <p>There is also a special <span class="fixedwidth">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">
- <Rule><br>
-
- <Target><br>
-
- <AnyTarget/><br>
-
- </Target><br>
-
- <Attribute
- name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"><br>
+ <blockquote>
+ <span class="fixedwidth">
+ <Rule><br>
+
+ <Target><br>
+
+ <AnyTarget/><br>
+
+ </Target><br>
+
+ <Attribute
+ name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"><br>
<Value
release="permit">member@example.edu</Value
</Attribute><br>
</span>
-->
-
- </blockquote>
- <h4><a name="5.b."></a>5.b. Sharing certificate/key pairs
- between Apache and Java keystores <font color="#5555EE">(optional)</font></h4>
-
+</blockquote>
+<h4><a name="5.c."></a>5.c. Sharing certificate/key pairs between Apache and
+Java keystores <font color="#5555EE">(optional)</font></h4>
+<blockquote>
<blockquote>
- <blockquote>
- <p>The JDK includes the command line program
- <span class="fixedwidth">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
- 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
- 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>
-
- <p><b>If you have a pre-exiting RSA key/certificate
- combination in a keystore and you would like to use it with
- Apache:</b></p>
-
+ <p>The JDK includes the command line program <span class="fixedwidth">
+ 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 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 SHIB_HOME must be set to the path to the directory where the
+ Shibboleth tarball was exploded(typically /opt/shibboleth-origin-1.1/).</p>
+ <p><b>If you have a pre-exiting RSA key/certificate combination in a
+ keystore and you would like to use it with Apache:</b></p>
<ol type="1">
- <li>
- <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
- present a list of the entries in the keystore.</p>
-
- <blockquote>
- <p><span class="fixedwidth">$ keytool -list -v -keystore
- yourstore</span></p>
+ <li>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 present a list of the entries in the
+ keystore.<blockquote>
+ <p><span class="fixedwidth">$ 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
- export the key in Base64-encoded pkcs8 format.</p>
-
- <blockquote>
- <p><span class="fixedwidth">$ extkeytool -exportkey -keystore yourstore
- -alias youralias -storepass yourpass -rfc -file
- yourkey.pkcs8</span></p>
+ </li>
+ <li>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 export the key in Base64-encoded pkcs8 format.<blockquote>
+ <p><span class="fixedwidth">$ extkeytool -exportkey -keystore
+ yourstore -alias youralias -storepass yourpass -rfc -file
+ yourkey.pkcs8</span></p>
</blockquote>
- </li>
-
- <li>
- <p>In order to use this key with Apache, you must
- convert it to PEM-encoded RSA native format. You have
- the option of storing the key unencrypted or
- encrypted:</p>
-
- <ol type="A">
- <li>
- <p>To use the unencrypted format, enter the
- following command for the conversion:</p>
-
- <blockquote>
- <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.pkcs8
- -nocrypt|openssl rsa -out yourkey.key</span></p>
+ </li>
+ <li>In order to use this key with Apache, you must convert it to PEM-encoded
+ RSA native format. You have the option of storing the key
+ unencrypted or encrypted:<ol type="A">
+ <li>To use the unencrypted format, enter the following command
+ for the conversion:<blockquote>
+ <p><span class="fixedwidth">$ openssl pkcs8 -in
+ yourkey.pkcs8 -nocrypt|openssl rsa -out yourkey.key</span></p>
</blockquote>
- </li>
-
- <li>
- <p>To use the encrypted format, enter the following
- command for the conversion:</p>
-
- <blockquote>
- <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.pkcs8
- -nocrypt|openssl rsa -des3 -out
- yourkey.enckey</span></p>
+ </li>
+ <li>To use the encrypted format, enter the following command for
+ the conversion:<blockquote>
+ <p><span class="fixedwidth">$ openssl pkcs8 -in
+ yourkey.pkcs8 -nocrypt|openssl rsa -des3 -out yourkey.enckey</span></p>
</blockquote>
- </li>
+ </li>
</ol>
- </li>
-
- <li>
- <p>The following command will export the corresponding
- certificate.</p>
-
- <blockquote>
- <p><span class="fixedwidth">$ keytool -export -keystore yourstore -alias
- youralias -rfc -file yourcert</span></p>
+ </li>
+ <li>The following command will export the corresponding certificate.<blockquote>
+ <p><span class="fixedwidth">$ keytool -export -keystore
+ yourstore -alias youralias -rfc -file yourcert</span></p>
</blockquote>
- </li>
-
- <li>
- <p>Set the <span class="fixedwidth">mod_ssl</span>
+ </li>
+ <li>Set the <span class="fixedwidth">mod_ssl</span>
<span class="fixedwidth">SSLCertificateKeyFile</span> and
- <span class="fixedwidth">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
- permissions, especially if you chose to store the key
- in an unencrypted format.</p>
- </li>
+ <span class="fixedwidth">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 permissions,
+ especially if you chose to store the key in an unencrypted format.</li>
</ol>
-
- <p><b>If you have a pre-existing RSA key/certificate
- combination that you use with Apache and would like to
- import it into a java keystore:</b></p>
-
+ <p><b>If you have a pre-existing RSA key/certificate combination that
+ you use with Apache and would like to import it into a java keystore:</b></p>
<ol type="1">
- <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
- following command.</p>
-
- <blockquote>
- <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.enckey -topk8
- -nocrypt -outform DER -out yourkey.der.pkcs8</span></p>
+ <li>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 following
+ command.<blockquote>
+ <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.enckey
+ -topk8 -nocrypt -outform DER -out yourkey.der.pkcs8</span></p>
</blockquote>
- </li>
-
- <li>
- <p>Create a certificate bundle file. This file should
- include a series of PEM-encoded X509 certificates
- 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
- enter the following command to create the bundle.</p>
-
- <blockquote>
- <p><span class="fixedwidth">$ cat mycert ca.cert > cert.bundle</span></p>
+ </li>
+ <li>Create a certificate bundle file. This file should include a
+ series of PEM-encoded X509 certificates 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 enter the following command to create the
+ bundle.<blockquote>
+ <p><span class="fixedwidth">$ cat mycert ca.cert > cert.bundle</span></p>
</blockquote>
-
- <b>Note: <span class="fixedwidth">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>
- 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>
-
- <blockquote>
- <p><span class="fixedwidth">$ ./extkeytool -importkey -keystore yourstore
- -alias youralias -storepass yourpass -keyfile
- yourkey.der.pkcs8 -certfile cert.bundle -provider
- org.bouncycastle.jce.provider.BouncyCastleProvider</span></p>
+ <p><b>Note: <span class="fixedwidth">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>
+ directory.</b> </li>
+ <li>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>.<blockquote>
+ <p><span class="fixedwidth">$ ./extkeytool -importkey -keystore
+ yourstore -alias youralias -storepass yourpass -keyfile
+ yourkey.der.pkcs8 -certfile cert.bundle -provider
+ org.bouncycastle.jce.provider.BouncyCastleProvider</span></p>
</blockquote>
- </li>
-
- <li>
- <p>You can verify that the import was successful by
- listing entry. Use the command below.</p>
-
- <blockquote>
- <p><span class="fixedwidth">$ keytool -list -v -keystore yourstore -alias
- youralias</span></p>
+ </li>
+ <li>You can verify that the import was successful by listing entry.
+ Use the command below.<blockquote>
+ <p><span class="fixedwidth">$ 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
- contains your unencrypted private key.</p>
- </li>
+ </li>
+ <li>Remember to delete <span class="fixedwidth">yourkey.der.pkcs8</span>,
+ as it contains your unencrypted private key.</li>
</ol>
-
- <p><b>If you are starting from scratch and do not yet have
- a certificate/key pair:</b></p>
-
+ <p><b>If you are starting from scratch and do not yet have a
+ certificate/key pair:</b></p>
<ol type="1">
- <li>
- <p>Generate an RSA private key. Use the command below,
- substituting <span class="fixedwidth">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
- 1024</span></p>
+ <li>Generate an RSA private key. Use the command below, substituting
+ <span class="fixedwidth">yourkey</span> with an appropriate name to
+ use to refer to the key.<blockquote>
+ <p><span class="fixedwidth">$ openssl genrsa -des3 -out
+ yourkey.enckey 1024</span></p>
</blockquote>
- </li>
-
- <li>
- <p>The following command generates a Certificate
- Signing Request, which should be communicated to a
- Certificate Authority.</p>
-
- <blockquote>
- <p><span class="fixedwidth">$ openssl req -new -key
- yourkey.enckey</span></p>
+ </li>
+ <li>The following command generates a Certificate Signing Request,
+ which should be communicated to a Certificate Authority.<blockquote>
+ <p><span class="fixedwidth">$ 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
- the key file you just created and the
- <span class="fixedwidth">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>
- </li>
+ </li>
+ <li>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 the key file you just created and the
+ <span class="fixedwidth">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.</li>
</ol>
- </blockquote>
</blockquote>
-
- <br>
- <h4><a name="5.c."></a>5.c. The Attribute Resolver</h4>
-
+</blockquote>
+<p><br>
+</p>
+<h4><a name="5.d."></a>5.d. The Attribute Resolver</h4>
+<blockquote>
+ <p>Shibboleth provides a powerful attribute resolver that allows 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.
+ attrresolv.AttributeResolver.ResolverConfig</span> propety in
+ <span class="fixedwidth">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, consult the programmer's guide.</p>
+ <p>The resolver is essentially a directed graph from attribute definitions
+ to data connectors. The data connectors pull data, in the form of
+ attributes, from external data sources. The attribute definitions then
+ process this data into a from suitable for use by Shibboleth. This procedure
+ can be as simple as taking an 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> 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 references to data connectors on which it
+ depends. Each data connector consists of a string identifier which is used
+ by attribute definitions that refer to it, and one or more elements specific
+ to the configuration of that data connector.</p>
+ <p>Shibboleth comes with two attribute definitions provided in version 1.1:
+ the <span class="fixedwidth">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 used to configure
+ user-created attribute definition plugins. Similarly, Shibboleth 1.1 comes
+ with two data connectors: the <span class="fixedwidth">
+ 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 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>
+ <dl>
+ <dd class="attribute"><span class="fixedwidth">id = <string></span> </dd>
+ <dd class="value">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> element.</dd>
+ <dd class="attribute"><span class="fixedwidth"><Property name="<name>"
+ value="<value>"/></span> </dd>
+ <dd class="value">An element of the element <span class="fixedwidth">
+ 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="fixedwidth">resolver.xml</span>. Refer to the
+ <a href="http://http://marsalis.internet2.edu/cgi-bin/viewcvs.cgi%20%20%20%20%20%20%20%20%20%20/shibboleth/java/src/conf/resolver.ldap.xml">
+ Shibboleth CVS</a> for an example of names and values used to connect to
+ an LDAP directory.</dd>
+ <dd class="attributeopt"><span class="fixedwidth"><Search></span> </dd>
+ <dd class="valueopt">An element of the element <span class="fixedwidth">
+ JNDIDirectoryDataConnector</span>. This element defines the DN filter
+ used to perform the LDAP search. The search string must return no more
+ than one result.</dd>
+ <dd class="attributeopt"><span class="fixedwidth"><Controls></span> </dd>
+ <dd class="valueopt">An element of the element <span class="fixedwidth">
+ Search</span>. This element grants some fine-grained control over the
+ LDAP API calls.</dd>
+ <dd class="attributeopt"><span class="fixedwidth"><cacheTime
+ "<seconds>"/></span> </dd>
+ <dd class="valueopt">An element of the element <span class="fixedwidth">
+ JNDIDirectoryDataConnector</span>. Specifies an optional duration in
+ <span class="fixedwidth">seconds</span> for which the attribute resolver
+ may cache information retrieved from this connector.</dd>
+ </dl>
+ <p>A representation of a properly constructed <span class="fixedwidth">
+ JNDIDirectoryDataConnector</span> element would look like:</p>
<blockquote>
- <p>Shibboleth provides a powerful attribute resolver that allows
- 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.
- attrresolv.AttributeResolver.ResolverConfig</span> propety in <span
- class="fixedwidth">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,
- consult the programmer's guide.</p>
-
- <p>The resolver is essentially a directed graph from attribute
- definitions to data connectors. The data connectors pull data, in
- the form of attributes, from external data sources. The attribute
- definitions then process this data into a from suitable for use
- by Shibboleth. This procedure can be as simple as taking an
- 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>
- 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
- references to data connectors on which it depends. Each data connector
- consists of a string identifier which is used by attribute
- definitions that refer to it, and one or more elements specific to
- the configuration of that data connector.</p>
-
- <p>Shibboleth comes with two attribute definitions provided in
- version 1.0: the <span
- class="fixedwidth">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
- used to configure user-created attribute definition plugins.
- Similarly, Shibboleth 1.0 comes with two data connectors: the
- <span class="fixedwidth">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
- 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>
-
- <dl>
- <dd class="attribute">
- <span class="fixedwidth">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>
- element.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth"><Property name="<name>" value="<value>"/></span>
- </dd>
-
- <dd class="value">
- <p>An element of the element <span
- class="fixedwidth">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="fixedwidth">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
- an LDAP directory.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth"><Search></span>
- </dd>
-
- <dd class="valueopt">
- <p>An element of the element <span
- class="fixedwidth">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>
- </dd>
-
- <dd class="valueopt">
- <p>An element of the element <span
- class="fixedwidth">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>
- </dd>
-
- <dd class="valueopt">
- <p>An element of the element <span
- class="fixedwidth">JNDIDirectoryDataConnector</span>.
- Specifies an optional duration in <span
- class="fixedwidth">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
- look like:</p>
-
- <blockquote><span class="fixedwidth">
- <JNDIDirectoryDataConnector id="directory"><br>
- <Search filter="cn=%PRINCIPAL%"><br>
- <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" /><br>
- </Search><br>
- <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" /><br>
- <cacheTime="2400"/><br>
- </JNDIDirectoryDataConnector>
- </span></blockquote>
-
- <p><span class="fixedwidth">SimpleAttributeDefinition</span>:</p>
-
- <dl>
- <dd class="attribute">
- <span class="fixedwidth">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>
- element.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth"><AttributeDependency / DataConnectorDependency requires="<id>"/></span>
- </dd>
-
- <dd class="valueopt">
- <p>An element of the element <span
- class="fixedwidth">SimpleAttributeDefinition</span>, which may
- contain 0 or more of either <span
- class="fixedwidth">AttributeDependency</span> or <span
- class="fixedwidth">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
- which this attribute definition can then use to build its
- value.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth">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
- instead. Contained within the <span
- class="fixedwidth">SimpleAttributeDefinition</span>
- element.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth">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
- 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
- uses the section following the <span
- class="fixedwidth">#</span> to query data connectors.
- Contained within the <span
- class="fixedwidth">SimpleAttributeDefinition</span>
- element.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth"><cacheTime "<seconds>"/></span>
- </dd>
-
- <dd class="valueopt">
- <p>An element of the element <span
- class="fixedwidth">SimpleAttributeDefinition</span>.
- Specifies an optional duration in <span
- class="fixedwidth">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>
- </dd>
-
- <dd class="valueopt">
- <p>An element of the element <span
- class="fixedwidth">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
- population and use of this field.</p>
- </dd>
- </dl>
-
- <p>A representation of a properly constructed <span
- class="fixedwidth">SimpleAttributeDefinition</span> element would
- look like:</p>
-
- <blockquote><span class="fixedwidth">
- <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>
- <cacheTime="600"/><br><br>
- <lifeTime="3600"/><br><br>
- </SimpleAttributeDefinition>
- </span></blockquote>
-
- <p>A properly formed <span class="fixedwidth">resolver.xml</span>
- file to automatically generate a simple response for EPPN may take
- the form:</p>
-
- <blockquote><span class="fixedwidth">
- <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>
- <DataConnectorDependency requires="echo"/><br>
- </SimpleAttributeDefinition><br>
- <br>
- <CustomDataConnector id="echo"
- class="edu.internet2.middleware.shibboleth.aa.attrresolv.provider.SampleConnector" /><br>
- </AttributeResolver>
- </span></blockquote>
-
- <p>There are additional examples of <span class="fixedwidth">resolver.xml</span> files provided in the <a href="http://marsalis.internet2.edu/cgi-bin/viewcvs.cgi/shibboleth/java/src/conf/">Shibboleth CVS</a>.</p>
-
+ <p><span class="fixedwidth"><JNDIDirectoryDataConnector id="directory"><br>
+ <Search filter="cn=%PRINCIPAL%"><br>
+ <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" /><br>
+ </Search><br>
+ <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"
+ /><br>
+ <cacheTime="2400"/><br>
+ </JNDIDirectoryDataConnector> </span></p>
</blockquote>
- <br>
- <h4><a name="5.d."></a>5.d. Local Error Page</h4>
+ <p><span class="fixedwidth">SimpleAttributeDefinition</span>:</p>
+ <dl>
+ <dd class="attribute"><span class="fixedwidth">id = <string></span> </dd>
+ <dd class="value">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> element.</dd>
+ <dd class="attributeopt"><span class="fixedwidth"><AttributeDependency /
+ DataConnectorDependency requires="<id>"/></span> </dd>
+ <dd class="valueopt">An element of the element <span class="fixedwidth">
+ SimpleAttributeDefinition</span>, which may contain 0 or more of either
+ <span class="fixedwidth">AttributeDependency</span> or
+ <span class="fixedwidth">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 which this attribute
+ definition can then use to build its value.</dd>
+ <dd class="attributeopt"><span class="fixedwidth">smartScope =
+ "<domain>"</span> </dd>
+ <dd class="valueopt">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 instead. Contained within the
+ <span class="fixedwidth">SimpleAttributeDefinition</span> element.</dd>
+ <dd class="attributeopt"><span class="fixedwidth">sourceName =
+ "<string>"</span> </dd>
+ <dd class="valueopt">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 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 uses the section following the <span class="fixedwidth">#</span>
+ to query data connectors. Contained within the <span class="fixedwidth">
+ SimpleAttributeDefinition</span> element.</dd>
+ <dd class="attributeopt"><span class="fixedwidth"><cacheTime
+ "<seconds>"/></span> </dd>
+ <dd class="valueopt">An element of the element <span class="fixedwidth">
+ SimpleAttributeDefinition</span>. Specifies an optional duration in
+ <span class="fixedwidth">seconds</span> for which the attribute resolver
+ may cache this attribute for use in additional assertions.</dd>
+ <dd class="attributeopt"><span class="fixedwidth"><lifeTime
+ "<seconds>"/></span> </dd>
+ <dd class="valueopt">An element of the element <span class="fixedwidth">
+ 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
+ population and use of this field.</dd>
+ </dl>
+ <p>A representation of a properly constructed <span class="fixedwidth">
+ SimpleAttributeDefinition</span> element would look like:</p>
<blockquote>
- <p>Origin sites are encouraged to provide federations with the
- URL of a local Shibboleth error page. If a browser user from the
- origin site encounters a problem at a shibbolized target, the target
- is likely to display an error page that includes a link back to this
- origin provided page.</p>
-
- <p>The page should provide information on how to obtain local support
- for using Shibbolized resources. It might also include suggestions on
- what information should be recorded before beginning the problem
- resolution process.</p>
+ <p><span class="fixedwidth"><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>
+ <cacheTime="600"/><br><br>
+ <lifeTime="3600"/><br><br>
+ </SimpleAttributeDefinition> </span></p>
</blockquote>
-
- <br>
- <br>
- <hr>
- <br>
-
-
- <h3><a name="6."></a>6. Troubleshooting</h3>
-
- <p>This section provides basic information about testing,
- logging, and error handling for Shibboleth origins. This
- information is not intended to be comprehensive, but instead
- rudimentary guidelines for basic configuration tests and
- problems. For more detailed information or answers to specific
- problems not addressed in this section, please mail <a href=
- "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>
- with a thorough description of errors and configurations
- used.</p>
-
- <h4><a name="6.a."></a>6.a. Basic Testing</h4>
-
+ <p>A properly formed <span class="fixedwidth">resolver.xml</span> file to
+ automatically generate a simple response for EPPN may take the form:</p>
<blockquote>
- <p>Internet2 provides a basic target that can be used to test
- origin setup functionality. After your origin is recognized
- by InQueue, simply use any browser to access <a href=
- "https://wayf.internet2.edu/InQueue/sample.jsp">https://wayf.internet2.edu/InQueue/sample.jsp</a>.
- Select your origin's name and follow the login process as a
- user would. Note that SSL must be used, and both the HS and
- AA must be fully configured.</p>
-
- <p>The test target will then display a simple page which
- includes the basic information sent to it by your origin and
- the authentication rules it is using.</p>
-
- <p><b>For information regarding specific error messages that
- may be generated if the origin does not work successfully,
- please refer to section <a href="#6.c.">6.c</a>.</b></p>
+ <p><span class="fixedwidth"><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>
+ <DataConnectorDependency requires="echo"/><br>
+ </SimpleAttributeDefinition><br>
+ <br>
+ <CustomDataConnector id="echo"
+ class="edu.internet2.middleware.shibboleth.aa.attrresolv.provider.SampleConnector"
+ /><br>
+ </AttributeResolver> </span></p>
</blockquote>
-
- <h4><a name="6.b."></a>6.b. Logging</h4>
-
+ <p>There are additional examples of <span class="fixedwidth">resolver.xml</span>
+ files provided in the
+ <a href="http://marsalis.internet2.edu/cgi-bin/viewcvs.cgi/shibboleth/java/src/conf/">
+ Shibboleth CVS</a>.</p>
+</blockquote>
+<p><br>
+</p>
+<h4><a name="5.d.i."></a>5.d.i <span class="fixedwidth">resolvertest</span></h4>
+<blockquote>
+ <p>Shibboleth comes bundled with the command line utility
+ <span class="fixedwidth">resolvertest</span> for testing Attribute Resolver
+ configurations. This program takes as input <span class="fixedwidth">
+ resolver.xml</span>, the name of a user, and optionally the name of a
+ requesting SHAR. It outputs the resulting SAML <Attribute /> elements. This
+ allows administrators to view the results of tweaking the resolver
+ configuration without having to continually reload the origin web
+ application. Initially, the following two steps must be performed:</p>
+ <ol>
+ <li>Set the shell variable <span class="fixedwidth">SHIB_HOME</span> to
+ the directory path where the Shibboleth tarball was exploded (typically
+ <span class="fixedwidth">/opt/shibboleth-origin-1.1/</span>).</li>
+ <li>Move to $SHIB_HOME/bin</li>
+ </ol>
+ <p><span class="fixedwidth">resolvertest</span> may then be used by
+ executing the shell script, passing the name of a user and a URL to the
+ Attribute Resolver configuration file as parameters. For example:</p>
<blockquote>
- <p>Shibboleth's origin components log various operations
- which may prove useful for auditing, testing, and security
- purposes. This data is sent through <span class="fixedwidth">log4j</span>'s
- standard mechanism. The location of
- the log file, the level at which the log is output, the
- formatting of the logs, and many more options may be
- configured by editing
- <span class="fixedwidth">/WEB-INF/classes/conf/log4j.properties</span>. By default,
- it is setup to log to the console of the servlet container, with a
- level of <span class="fixedwidth">WARN</span>, but there is also a commented out
- example in the file to give a possible alternate configuration.</p>
+ <p><span class="fixedwidth">$ ./resolvertest --user=wassa
+ --file=file:///$SHIB_HOME/src/conf/resolver.xml</span></p>
</blockquote>
+ <h5>NOTE: This program does not filter the resulting attributes through the
+ applicable ARP's. Although it does show the attributes generated by the
+ resolver for a particular user or URL, it does not necessarily reflect what
+ will be released by the AA to a requesting SHAR.</h5>
+</blockquote>
+<p><br>
+</p>
+<h4><a name="5.e."></a>5.e. Local Error Page</h4>
+<blockquote>
+ <p>Origin sites are encouraged to provide federations with the URL of a
+ local Shibboleth error page. If a browser user from the origin site
+ encounters a problem at a shibbolized target, the target is likely to
+ display an error page that includes a link back to this origin provided
+ page.</p>
+ <p>The page should provide information on how to obtain local support for
+ using Shibbolized resources. It might also include suggestions on what
+ information should be recorded before beginning the problem resolution
+ process.</p>
+</blockquote>
+<p><br>
+<br>
+</p>
+<hr>
+<p><br>
+</p>
+<h3><a name="6."></a>6. Troubleshooting</h3>
+<p>This section provides basic information about testing, logging, and error
+handling for Shibboleth origins. This information is not intended to be
+comprehensive, but instead rudimentary guidelines for basic configuration tests
+and problems. For more detailed information or answers to specific problems not
+addressed in this section, please mail
+<a href="mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>
+with a thorough description of errors and configurations used.</p>
+<h4><a name="6.a."></a>6.a. Basic Testing</h4>
+<blockquote>
+ <p>Internet2 provides a basic target that can be used to test origin setup
+ functionality. After your origin is recognized by InQueue, simply use any
+ browser to access <a href="https://wayf.internet2.edu/InQueue/sample.jsp">
+ https://wayf.internet2.edu/InQueue/sample.jsp</a>. Select your origin's name
+ and follow the login process as a user would. Note that SSL must be used,
+ and both the HS and AA must be fully configured.</p>
+ <p>The test target will then display a simple page which includes the basic
+ information sent to it by your origin and the authentication rules it is
+ using.</p>
+ <p><b>For information regarding specific error messages that may be
+ generated if the origin does not work successfully, please refer to section
+ <a href="#6.c.">6.c</a>.</b></p>
+</blockquote>
+<h4><a name="6.b."></a>6.b. Logging</h4>
+<blockquote>
+ <p>Shibboleth's origin components log various operations which may prove
+ useful for auditing, testing, and security purposes. This data is sent
+ through <span class="fixedwidth">log4j</span>'s standard mechanism. The
+ location of the log file, the level at which the log is output, the
+ formatting of the logs, and many more options may be configured by editing
+ <span class="fixedwidth">/WEB-INF/classes/conf/log4j.properties</span>. By
+ default, it is setup to log to the console of the servlet container, with a
+ level of <span class="fixedwidth">WARN</span>, but there is also a commented
+ out example in the file to give a possible alternate configuration.</p>
+</blockquote>
+<h4><a name="6.c."></a>6.c. Common Problems</h4>
+<blockquote>
+ <p>A knowledge base is being developed in the
+ <a href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.html">
+ Shibboleth Deployer's FAQ</a>. Please mail
+ <a href="mailto:mace-shib-users@internet2.edu">mace-shib-users@
+ internet2.edu</a> with any additional questions or problems encountered that
+ are not answered by this basic guide.</p>
+</blockquote>
+
+</body>
- <h4><a name="6.c."></a>6.c. Common Problems</h4>
-
- <blockquote>
- <p>A knowledge base is being developed in the <a
- href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.html">
- Shibboleth Deployer's FAQ</a>. Please mail <a href=
- "mailto:mace-shib-users@internet2.edu">mace-shib-users@
- internet2.edu</a> with any additional questions or problems
- encountered that are not answered by this basic guide.</p>
- </blockquote>
- </body>
</html>
-
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
+<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <title>Shibboleth Target Deployment Guide</title>
- <meta http-equiv="Content-Type" content=
- "text/html; charset=utf-8">
- <style type="text/css">
+
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
+<meta name="ProgId" content="FrontPage.Editor.Document">
+<title>Shibboleth Target Deployment Guide</title>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<style type="text/css">
html
{
}
dl
{
-background-color: #DDDDDD;
-background-image: none;
+border-width:2px; background-color: #DDDDDD;
+background-image: url('none');
margin: 5px;
padding: 0px;
border-style: solid;
-border-bottom-width: 2px;
-border-top-width: 2px;
-border-left-width: 2px;
-border-right-width: 2px;
+
}
dt
{
background-color: #DDDDDD;
-background-image: none;
+background-image: url('none');
margin: 1px;
-padding: 1px;
+padding: 1px
}
dd
{
background-color: #DDDDDD;
-background-image: none;
+background-image: url('none');
margin: 0px;
-padding: 1px;
+padding: 1px
}
.attribute
{
font-size: 115%;
-font-color: #000000;
+color: #000000;
text-align: left;
background-color: #DDDDDD;
-border: 1px black inset;
-background-image: none;
+border: 1px inset black;
+background-image: url('none');
margin: 0px;
-padding: 2px;
+padding: 2px
}
.value
{
-font-color: #000000;
+color: #000000;
text-align: left;
background-color: #EEEEEE;
-background-image: none;
+background-image: url('none');
padding-top: 0em;
padding-bottom: 0.5em;
padding-right: 1em;
padding-left: 5em;
-border-style: solid;
border-bottom-width: none;
border-top-width: none;
border-left-width: 1px;
-border-right-width: 1px;
+border-right-width: 1px; border-left-style:solid; border-right-style:solid; border-top-style:solid; border-bottom-style:solid
}
.attributeopt
{
font-size: 115%;
-font-color: #000000;
+color: #000000;
text-align: left;
background-color: #BCBCEE;
-border: 1px black inset;
-background-image: none;
+border: 1px inset black;
+background-image: url('none');
margin: 0px;
-padding: 2px;
+padding: 2px
}
.valueopt
{
-font-color: #000000;
+color: #000000;
text-align: left;
background-color: #DDDDFF;
-background-image: none;
+background-image: url('none');
padding-top: 0em;
padding-bottom: 0.5em;
padding-right: 1em;
padding-left: 5em;
-border-style: solid;
border-bottom-width: none;
border-top-width: none;
border-left-width: 1px;
-border-right-width: 1px;
+border-right-width: 1px; border-left-style:solid; border-right-style:solid; border-top-style:solid; border-bottom-style:solid
}
.attributelong
{
font-size: 85%;
-font-color: #000000;
+color: #000000;
text-align: left;
background-color: #DDDDDD;
-border: 1px black inset;
-background-image: none;
+border: 1px inset black;
+background-image: url('none');
margin: 0px;
-padding: 2px;
+padding: 2px
}
.attributeoptlong
{
font-size: 85%;
-font-color: #000000;
+color: #000000;
text-align: left;
background-color: #BCBCEE;
-border: 1px black inset;
-background-image: none;
+border: 1px inset black;
+background-image: url('none');
margin: 0px;
-padding: 2px;
+padding: 2px
}
.demo
{
background-color: #EEEEEE;
padding: 3px;
}
-.fixedwidth
+.fixed
{
font-family: monospace;
font-size: 90%;
-font-color: #121212;
+color: #121212;
+}
+.feature
+{
+color: #00FF00
}
- </style>
- </head>
-
- <body link="red" vlink="red" alink="black" bgcolor="white">
- <center>
- <h2>Shibboleth Target Deployment Guide</h2>
- </center>
-
- Shibboleth Target Deployment Guide<br>
- Shibboleth Version 1.0<br />
- June 19, 2003<br />
-
-
- <h3>This version of the deploy guide is for Shibboleth v1.0. For
- documentation related to prior versions of Shibboleth, please
- 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>
- This new release contains many improvements and enhancements, including:
-
- <h5>Federation Support</h5>
- <ol>
- <li>
- Federation and trust support has been substantially extended. Federation
- structures are now defined. The set of metadata collected and managed
- by each Federation is more fully defined. The configuration values
- assigned by a Federation are now identified. <br>
- </li>
- <li>
- There is some support for targets to be members of multiple federations;
- this support will continue to evolve. When a browser user arrives,
- a target will determine which federation their origin belongs to,
- and then use the trust fabric associated with that Federation. <br>
- </li>
- <li>
- Better support for flexible and bilateral trust agreements. A key
- specific to an origin site can be used to vallidate its signature.
- <br>
- </li>
-
- <li>
- This version contains a significantly more mature security implementation,
- and should meet the security requirements of typical sites. <p></p>
- </li>
- </ol>
-
- <h5>Origin</h5>
- <ol>
-
- <li> The Attribute Authority has a powerful new attribute resolver.
- Simple scenarios (using a string attribute stored in ldap) can be
- accomplished by merely editing a configuration file. Java classes
- may still be written for more complex evaluations (eg retrieving information
- from multiple disparate repositories, and computing the SAML attribute
- using business rules). This should greatly simplify the process of
- configuring the AA to support additional general attributes.<br>
- </li>
- </ol>
-
- <h5>Target</h5>
- <ol>
- <li> Significantly more flexibility in configuring targets to ensure
- robustness. Failover and redundant configurations are now supported.
- <br>
- <ol>
- <li>The SHAR may now optionally store its session and attribute
- cache in a back-end database in addition to the previously available
- in-memory option. This would allow a site to run an apache server
- farm, with multiple SHARs, supporting the same set of sessions.
- </li>
- <li>Federation supplied files (sites.xml and trust.xml) are now
- refreshed in a much more robust manner. <br>
- </li>
-
- </ol>
- </li>
- <li>Attribute acceptance policies have been greatly enhanced, and now
- supports filtering of attribute values by sites. <br>
- </li>
- <li>The SHAR can be configured to request specific attributes from the
- Origin. <br>
- </li>
- </ol>
- <h5>Miscellaneous</h5>
- <ol>
- <li>Origin sites can configure a value to describe the type of authentication
- mechanism used at the origin site(e.g. password, Kerberos, PKI, etc.).
- This value is made available on the target side as Shib-Authentication-Method.
- <br>
- </li>
- <li>Various improvements to error handling. Origin sites are now able
- to supply an "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>
- </ol>
-
- <p>Before starting, please sign up for all applicable <a href=
- "http://shibboleth.internet2.edu/shib-misc.html#mailinglist">
- mailing lists</a>. Announcements pertinent to Shibboleth
- deployments and developments and resources for deployment
- 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>.
- This should include, but not be limited to, questions about the
- documentation, undocumented problems, installation or
- operational issues, and anything else that arises. Please
- ensure that you have the <a href=
- "http://shibboleth.internet2.edu/release/shib-download.html">appropriate
- tarball</a> for your operating system.</p>
- <br>
- <hr>
- <br>
- <br>
-
-
- <h3><a name="TOC"></a>Shibboleth Target -- Table of
- Contents</h3>
+ </style>
+</head>
+
+<body link="red" vlink="red" alink="black" bgcolor="white">
+
+<center>
+<h2>Shibboleth Target Deployment Guide</h2>
+</center>
+<p>Shibboleth Target Deployment Guide<br>
+Shibboleth Version 1.1<br />
+July 25, 2003<br />
+</p>
+<h3>This version of the deploy guide is for Shibboleth v1.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.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.1 are marked with <span class="feature">
+[1.1]</span></p>
+<h4>Major New Features in 1.0 and 1.1</h4>
+<p>This new release contains several improvements and enhancements, including:
+</p>
+<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. </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>
+<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.</li>
+ <li>A sample resolver file for using standard LDAP person and inetOrgPerson
+ attributes is included. <span class="feature">[1.1]</span></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.1]</span></li>
+ <li>Specialized sites without privacy needs can configure identity-based
+ handles interoperable with other SAML deployments. <span class="feature">
+ [1.1]</span></li>
+</ol>
+<h5>Target</h5>
+<ol>
+ <li>Significantly more flexibility in configuring targets is provided 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.
+ </li>
+ <span class="feature">[1.1]</span> </li>
+ <li>Federation supplied files (sites.xml and trust.xml) are now refreshed in
+ a much more robust manner. </li>
+ </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.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.1]</span> </li>
+ <li>Support for Apache 1.3 on Windows NT/2000/XP/2003 has been added.
+ <span class="feature">[1.1]</span> </li>
+ <li>Microsoft IIS web server support has been added via an ISAPI filter and
+ extension. <span class="feature">[1.1]</span> </li>
+</ol>
+<h5>Miscellaneous</h5>
+<ol>
+ <li>Origin sites can configure a value to describe the type of
+ authentication mechanism used at the origin site (e.g. password, Kerberos,
+ PKI, etc.). This value is made available on the target side as Shib-Authentication-Method.
<br>
-
-
- <ol type="1">
- <li>
- <h4><a href="#1."><font color="black">Shibboleth
- Overview</font></a></h4>
-
- <ol type="a">
- <li><a href="#1.a."><font color=
- "black">Origin</font></a></li>
-
- <li><a href="#1.b."><font color=
- "black">Target</font></a></li>
-
- <li><a href="#1.c."><font color=
- "black">WAYF</font></a></li>
-
- <li><a href="#1.d."><font color=
- "black">Federations</font></a></li>
- </ol>
- </li>
-
- <li>
- <h4><a href="#2."><font color=
- "black">Planning</font></a></h4>
-
- <ol type="a">
- <li><a href="#2.a."><font color=
- "black">Requirements</font></a></li>
-
- <li><a href="#2.b."><font color="black">Join a
- Federation</font></a></li>
-
- <li><a href="#2.c."><font color="black">Security
- Considerations</font></a></li>
-
- <li><a href="#2.d."><font color="black">Server
- Certs</font></a></li>
-
- <li><a href="#2.e."><font color="black">Attribute Release
- Policies</font></a></li>
-
- <li><a href="#2.f."><font color="black">Designate
- Contacts</font></a></li>
-
- <li><a href="#2.g."><font color="black">Browser
- Requirements</font></a></li>
-
- <li><a href="#2.h."><font color=
- "black">Clocks</font></a></li>
-
- <li><a href="#2.i."><font color="black">Other
- Considerations</font></a></li>
- </ol>
- </li>
-
- <li>
- <h4><a href="#3."><font color=
- "black">Installation</font></a></h4>
-
- <ol type="a">
- <li><a href="#3.a."><font color="black">Software
- Requirements</font></a></li>
-
- <li><a href="#3.b."><font color="black">Deploy the
- Shibboleth Package</font></a></li>
-
- <li><a href="#3.c."><font color="black">Configure
- Apache</font></a></li>
- </ol>
- </li>
-
- <li>
- <h4><a href="#4."><font color="black">Getting
- Running</font></a></h4>
-
- <ol type="a">
- <li><a href="#4.a."><font color="black">Configuring
- <span class="fixedwidth">shibboleth.ini</span></font></a></li>
-
- <li><a href="#4.b."><font color="black">Dynamic Error
- Page Generation</font></a></li>
-
- <li><a href="#4.c."><font color="black">Key Generation
- and Certificate Installation</font></a></li>
-
- <li><a href="#4.d."><font color="black">Protecting
- Webpages</font></a></li>
-
- <li><a href="#4.e."><font color="black">Designing
- AAP's</font></a></li>
-
- <li><a href="#4.f."><font color="black">Using Attributes
- in Applications</font></a></li>
-
- <li><a href="#4.g."><font color="black"><span
- class="fixedwidth">siterefresh</span></font></a></li>
- </ol>
- </li>
-
- <li>
- <h4><a href="#5."><font color=
- "black">Troubleshooting</font></a></h4>
-
- <ol type="a">
- <li><a href="#5.a."><font color="black">Basic
- Testing</font></a></li>
-
- <li><a href="#5.b."><font color="black">Common
- Problems</font></a></li>
- </ol>
- </li>
+ </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>
+</ol>
+<p>Before starting, please sign up for all applicable
+<a href="http://shibboleth.internet2.edu/shib-misc.html#mailinglist">mailing
+lists</a>. Announcements pertinent to Shibboleth deployments and developments
+and resources for deployment 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>.
+This should include, but not be limited to, questions about the documentation,
+undocumented problems, installation or operational issues, and anything else
+that arises. Please ensure that you have the
+<a href="http://shibboleth.internet2.edu/release/shib-download.html">appropriate
+tarball</a> for your operating system.</p>
+<p><br>
+</p>
+<hr>
+<p><br>
+<br>
+</p>
+<h3><a name="TOC"></a>Shibboleth Target -- Table of Contents</h3>
+<ol type="1">
+ <li>
+ <h4><a href="#1."><font color="black">Shibboleth Overview</font></a></h4>
+ <ol type="a">
+ <li><a href="#1.a."><font color="black">Origin</font></a></li>
+ <li><a href="#1.b."><font color="black">Target</font></a></li>
+ <li><a href="#1.c."><font color="black">WAYF</font></a></li>
+ <li><a href="#1.d."><font color="black">Federations</font></a></li>
</ol>
- <br>
- <hr>
- <br>
-
-
- <h3><a name="1."></a>1. Shibboleth Overview</h3>
-
- <p>Shibboleth is a system designed to exchange attributes
- across realms for the primary purpose of authorization. It
- provides a secure framework for one organization to transmit
- attributes about a web-browsing individual across security
- domains to another institution. In the primary usage case, when
- a user attempts to access a resource at a remote domain, the
- user's own home security domain can send certain information
- about that user to the target site in a trusted exchange. These
- attributes can then be used by the resource to help determine
- whether to grant the user access to the resource. The user may
- have the ability to decide whether to release specific
- attributes to certain sites by specifying personal Attribute
- Release Policies (ARP's), effectively preserving privacy while
- still granting access based on trusted information.</p>
-
- <p>When a user first tries to access a resource protected by
- Shibboleth, they are redirected to a service which asks the
- user to specify the organization from which they want to
- authenticate. If the user has not yet locally authenticated to
- a WebISO service, the user will then be redirected to their
- home institution's authentication system. After the user
- authenticates, the Shibboleth components at the local
- institution will generate a temporary reference to the user,
- known as a handle, for the individual and send this to the
- target site. The target site can then use the handle to ask for
- attributes about this individual. Based on these attributes,
- the target can decide whether or not to grant access to the
- resource. The user may then be allowed to access the requested
- materials.</p>
-
- <p>There are several controls on privacy in Shibboleth, and
- mechanisms are provided to allow users to determine exactly
- which information about them is released. A user's actual
- identity isn't necessary for many access control decisions, so
- privacy often is needlessly compromised. Instead, the resource
- often utilizes other attributes such as faculty member or member
- of a certain class. While these are commonly determined using
- the identity of the user, Shibboleth provides a way to mutually
- refer to the same principal without revealing that principal's
- identity. Because the user is initially known to the target site
- only by a randomly generated temporary handle, if sufficient,
- the target site might know no more about the user than that the
- user is a member of the origin organization. This handle should
- never be used to decide whether or not to grant access, and is
- intended only as a temporary reference for requesting
- attributes.</p>
-
- <h4><a name="1.a."></a>1.a. Origin</h4>
-
- <blockquote>
- <p>There are four primary components to the origin side in
- 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 is also supplied; the
- directory is provided by the origin site. Shibboleth is able
- to interface with a directory exporting an LDAP interface or a
- SQL database containing user attributes, and is designed such
- that programming interfaces to other repositories should be
- readily implemented. Shibboleth relies on standard web server
- mechanisms to trigger local authentication. A .htaccess file
- can be easily used to trigger either the local WebISO system
- or the web server's own Basic Auth mechanism, which will
- likely utilize an enterprise authentication system, such as
- Kerberos.</p>
-
- <p>From the origin site's point of view, the first contact
- will be the redirection of a user to the handle service,
- which will then consult the SSO system to determine whether
- the user has already been authenticated. If not, then the
- browser user will be asked to authenticate, and then sent
- back to the target URL with a handle bundled in an attribute
- assertion. Next, a request from the Shibboleth Attribute
- Requester (SHAR) will arrive at the AA which will include the
- previously mentioned handle. The AA then consults the ARP's
- for the directory entry corresponding to the handle, queries
- the directory for these attributes, and releases to the SHAR
- all attributes the SHAR is entitled to know about that
- user.</p>
- </blockquote>
-
- <h4><a name="1.b."></a>1.b. Target</h4>
-
- <blockquote>
- <p>There are three primary components to the target side in
- Shibboleth: the Shibboleth Indexical Reference Establisher
- (SHIRE), the Shibboleth Attribute Requester (SHAR), and the
- resource manager (RM). An implementation of each of these is
- included in the standard Shibboleth distribution. These
- components are intended to run on the same web server.</p>
-
- <p>From the target's point of view, a browser will hit the RM
- with a request for a Shibboleth-protected resource. The RM
- then allows the SHIRE to step in, which will use the WAYF to
- acquire the name of a handle service to ask about the user.
- The handle service (HS) will then reply with a SAML
- authentication assertion containing a handle, which the SHIRE
- then hands off to the SHAR. The SHAR uses the handle and the
- supplied address of the corresponding attribute authority
- (AA) to request all attributes it is allowed to know about
- the handle. The SHAR performs some basic validation and
- analysis based on attribute acceptance policies (AAP's).
- These attributes are then handed off to the RM, which is
- responsible for using these attributes to decide whether to
- grant access.</p>
- </blockquote>
-
- <h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
-
- <blockquote>
- <p>The WAYF service can be either outsourced and operated by a
- federation or deployed as part of the SHIRE. It is responsible for
- allowing a user to associate themself with an institution of their
- specification, then redirecting the user to the known address for
- the handle service of that institution.</p>
- </blockquote>
-
- <h4><a name="1.d."></a>1.d. Federations</h4>
-
- <blockquote>
- <p>A federation provides part of the underlying trust required for
- function of the Shibboleth architecture. A federation in the
- context of Shibboleth is a group of organizations(universities,
- corporations, content providers, etc.) who agree to exchange
- attributes using the SAML/Shibboleth protocols and abide by a
- common set of policies and practices. In so doing, they must
- implicitly or explicitly agree to a common set of guidelines.
- Joining a federation is not explicitly necessary for operation of
- Shibboleth, but it dramatically expands the number of targets and
- origins that can interact without defining bilateral agreements
- between all these parties.</p>
-
- <p>A federation can be created in a variety of formats and trust
- models, but to support Shibboleth, it must provide a certain set
- of services to federation members. It needs to supply a registry
- to process applications to the federation and distribute
- membership information to the origin and target sites. This must
- include distribution of the PKI components necessary for trust
- between origins and targets. There also needs to be a set of
- agreements and best practices defined by the federation governing
- the exchange, use, and population of attributes before and after
- transit, and there should be a way to find information on local
- authentication and authorization practices for federation
- members.</p>
- </blockquote>
- <br>
- <br>
- <br>
- <hr>
- <br>
-
-
- <h3><a name="2."></a>2. Planning</h3>
-
- <p>There are several essential elements that must be present in
- the environment to ensure Shibboleth functions well, both
- political and technical. Shibboleth currently runs on a
- specific range of platforms and web server environments. The
- SHAR and SHIRE are implemented entirely in C/C++. These are the
- recommendations and requirements for a successful implementation
- of a Shibboleth target.</p>
-
- <h4><a name="2.a."></a>2.a. Requirements</h4>
-
- <blockquote>
- <p>Shibboleth currently only supports Linux and Solaris. At
- present, Shibboleth consists of Apache plugins and a separate SHAR
- process. The plugins use the ONC RPC mechanism to communicate with
- the SHAR. The target's web servers must be running <a href=
- "http://http://www.apache.org/dist/httpd/">Apache</a> 1.3.26+, but
- not Apache 2. More precise technical details are discussed in <a
- href="#3.a.">3.a</a>.</p>
- </blockquote>
-
- <h4><a name="2.b."></a>2.b. Join a Federation</h4>
-
- <blockquote>
- <p>While it is not necessary for a target or origin to join a
- federation, doing so greatly facilitates the implementation of
- multilateral trust relationships. Each federation will have a
- different application process.</p>
-
- <p>For more information on federations, refer to <a href=
- "#1.d.">1.d</a> or the Shibboleth v1.0 architectural
- document.</p>
- </blockquote>
-
- <h4><a name="2.c."></a>2.c. Security Considerations</h4>
-
- <blockquote>
- <p>Shibboleth's protocols and software have been extensively
- engineered to provide protection against many attacks.
- However, the most secure protocol can be compromised if it is
- placed in an insecure environment. To ensure Shibboleth is as
- secure as possible, there are several recommended security
- precautions which should be in place at local sites.</p>
-
- <ol type="i">
- <li>
- <p>SSL use is optional for target sites. Federation guidelines
- should be considered when determining whether to
- implement SSL, and, in general, SSL should be used for
- interactions with client machines to provide the
- necessary authentication and encryption to ensure
- protection from man-in-the-middle attacks. It is strongly
- suggested that all password traffic or similarly
- sensitive data should be SSL-protected. Assessment of the
- risk tradeoff against possible performance degradation
- should be performed for all applications.</p>
- </li>
-
- <li>
- <p>Many other attacks can be made on the several
- redirection steps that Shibboleth takes to complete
- attribute transfer. The best protection against this is
- safeguarding the WAYF service and ensuring that rogue
- targets and origins are not used, generally by
- development of the trust model underneath Shibboleth.
- Shibboleth also leverages DNS for security, which is not
- uncommon, but attacks concerning bad domain information
- should be considered.</p>
- </li>
-
- <li>
- <p>Information regarding origin users is generally
- provided by the authoritative enterprise directory, and
- the acceptance of requests from target applications can
- be carefully restricted to ensure that all requests the
- SHAR performs are authorized and all information the
- origin provides is accurate. Use of plaintext passwords
- is strongly advised against.</p>
- </li>
-
- <li>
- <p>Server platforms should be properly secured,
- commensurate with the level that would be expected for a
- campus' other security services, and cookie stores on
- client machines should be well protected.</p>
- </li>
- </ol>
- </blockquote>
-
- <h4><a name="2.d."></a>2.d. Server Certs</h4>
-
- <blockquote>
- <p>In the Shibboleth architecture, the SHAR, HS, and AA must
- all have various client and/or server certificates for use in
- signing assertions and creating SSL channels. These should be
- issued by a commonly accepted CA, which may be stipulated by
- your federation. After understanding the CA's acceptible to your
- federations, consult chapter <a href="#4.c.">4.c</a> for
- information on certificate and key generation.</p>
- </blockquote>
-
- <h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
-
- <blockquote>
- <p>The Attribute Authority maintains a set of rules called
- Attribute Release Policies (ARP's) that define which
- attributes are released to which targets. When a browser user
- tries to access a resource, the SHAR asks the origin site AA
- to release all the attributes it is allowed to know. The SHAR
- provides its own name and an optional URL on behalf of which
- the attribute request is made which can further refine the
- information the SHAR is allowed to know. The AA processes this
- request using all applicable ARP's, determines which
- attributes and values it will release, and then obtains the
- values actually associated with the browser user. The AA sends
- these attributes and values back to the SHAR.</p>
-
- <p>Targets should work together with expected origin sites to
- ensure that the sets of attributes that both sites expect to
- correspond using are congruent.</p>
- </blockquote>
-
- <h4><a name="2.f."></a>2.f. Designate Contacts</h4>
-
- <blockquote>
- <p>Since Shibboleth deals both with daily technical and
- operational issues and also with contractual issues, a set of
- contacts should be set up to support the user base and to
- facilitate interactions with other Shibboleth sites and federation
- members. It is recommended that at least technical and
- administrative contacts be designated. Names, titles, e-mail
- addresses, and phone numbers may all be useful information to
- provide.</p>
- </blockquote>
-
- <h4><a name="2.g."></a>2.g. Browser Requirements</h4>
-
- <blockquote>
- <p>A primary Shibboleth design consideration was to require
- very little or no modification to client machines. The only
- requirement is that a browser is used which supports cookies,
- redirection and SSL. Browser users will have to perform an
- additional click to submit the authentication assertion if
- JavaScript is not functional.</p>
- </blockquote>
-
- <h4><a name="2.h."></a>2.h. Clocks</h4>
-
- <blockquote>
- <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should
- be run on all web servers. Shibboleth employs a short handle
- issuance time to protect against replay attacks. Because of
- this, any significant degree of clock skew can hinder the
- ability of users to access sites successfully.</p>
- </blockquote>
-
- <h4><a name="2.h."></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>The Shibboleth project makes binary packages available for
- Solaris and Linux that are precompiled against recent releases
- of various required libraries such as OpenSSL. It is highly
- advisable to build from source when using Shibboleth in a
- production environment in order to permit patching or updating
- of packages as security holes and bugs are fixed. Building from
- source is necessary to give you complete control over your
- deployment platform. The binary packages represent a snapshot in
- time only. To build from source, see the <span class="fixedwidth">INSTALL.txt</span>
- files in the root of the OpenSAML and Shibboleth source
- distributions.</p>
-
- <blockquote>
- <b>Operating System:</b>
-
- <ul type="circle">
- <li>
- RedHat 7.2-7.3:
-
- <ul type="disc">
+ </li>
+ <li>
+ <h4><a href="#2."><font color="black">Planning</font></a></h4>
+ <ol type="a">
+ <li><a href="#2.a."><font color="black">Requirements</font></a></li>
+ <li><a href="#2.b."><font color="black">Join a Federation</font></a></li>
+ <li><a href="#2.c."><font color="black">Security Considerations</font></a></li>
+ <li><a href="#2.d."><font color="black">Server Certificates</font></a></li>
+ <li><a href="#2.e."><font color="black">Attribute Release Policies</font></a></li>
+ <li><a href="#2.f."><font color="#000000">Attribute Acceptance Policies</font></a></li>
+ <li><a href="#2.g."><font color="black">Browser Requirements</font></a></li>
+ <li><a href="#2.h."><font color="black">Clocks</font></a></li>
+ <li><a href="#2.i."><font color="black">Other Considerations</font></a></li>
+ </ol>
+ </li>
+ <li>
+ <h4><a href="#3."><font color="black">Installation</font></a></h4>
+ <ol type="a">
+ <li><a href="#3.a."><font color="black">Software Requirements</font></a></li>
+ <li><a href="#3.b."><font color="black">Deploy the Shibboleth Package</font></a></li>
+ <li><a href="#3.c."><font color="black">Configuring Apache 1.3.x</font></a></li>
+ <li><a href="#3.d."><font color="black">Configuring IIS</font></a></li>
+ <li><a href="#3.e."><font color="black">Running the SHAR on Windows</font></a></li>
+ </ol>
+ </li>
+ <li>
+ <h4><a href="#4."><font color="black">Getting Running</font></a></h4>
+ <ol type="a">
+ <li><a href="#4.a."><font color="black">Configuring <span class="fixed">
+ shibboleth.ini</span></font></a></li>
+ <li><a href="#4.b."><font color="black">Dynamic Error Page Generation</font></a></li>
+ <li><a href="#4.c."><font color="black">Key Generation and Certificate
+ Installation</font></a></li>
+ <li><a href="#4.d."><font color="black">Protecting Web Pages</font></a></li>
+ <li><a href="#4.e."><font color="black">Defining Attributes and
+ Acceptance Policies</font></a></li>
+ <li><a href="#4.f."><font color="black">Using Attributes in Applications</font></a></li>
+ <li><a href="#4.g."><font color="black"><span class="fixed">siterefresh</span></font></a></li>
+ <li><a href="#4.h."><font color="black">MySQL Session Cache</font></a></li>
+ </ol>
+ </li>
+ <li>
+ <h4><a href="#5."><font color="black">Troubleshooting</font></a></h4>
+ <ol type="a">
+ <li><a href="#5.a."><font color="black">Basic Testing</font></a></li>
+ <li><a href="#5.b."><font color="black">Common Problems</font></a></li>
+ </ol>
+ </li>
+</ol>
+<p><br>
+</p>
+<hr>
+<p><br>
+</p>
+<h3><a name="1."></a>1. Shibboleth Overview</h3>
+<p>Shibboleth is a system designed to exchange attributes across realms for the
+primary purpose of authorization. It provides a secure framework for one
+organization to transmit attributes about a web-browsing individual across
+security domains to another institution. In the primary usage case, when a user
+attempts to access a resource at a remote domain, the user's own home security
+domain can send certain information about that user to the target site in a
+trusted exchange. These attributes can then be used by the resource to help
+determine whether to grant the user access to the resource. The user may have
+the ability to decide whether to release specific attributes to certain sites by
+specifying personal Attribute Release Policies (ARP's), effectively preserving
+privacy while still granting access based on trusted information.</p>
+<p>When a user first tries to access a resource protected by Shibboleth, they
+are redirected to a service which asks the user to specify the organization from
+which they want to authenticate. If the user has not yet locally authenticated
+to a WebISO service, the user will then be redirected to their home
+institution's authentication system. After the user authenticates, the
+Shibboleth components at the local institution will generate a temporary
+reference to the user, known as a handle, for the individual and send this to
+the target site. The target site can then use the handle to ask for attributes
+about this individual. Based on these attributes, the target can decide whether
+or not to grant access to the resource. The user may then be allowed to access
+the requested materials.</p>
+<p>There are several controls on privacy in Shibboleth, and mechanisms are
+provided to allow users to determine exactly which information about them is
+released. A user's actual identity isn't necessary for many access control
+decisions, so privacy often is needlessly compromised. Instead, the resource
+often utilizes other attributes such as faculty member or member of a certain
+class. While these are commonly determined using the identity of the user,
+Shibboleth provides a way to mutually refer to the same principal without
+revealing that principal's identity. Because the user is initially known to the
+target site only by a randomly generated temporary handle, if sufficient, the
+target site might know no more about the user than that the user is a member of
+the origin organization. This handle should never be used to decide whether or
+not to grant access, and is intended only as a temporary reference for
+requesting attributes.</p>
+<h4><a name="1.a."></a>1.a. Origin</h4>
+<blockquote>
+ <p>There are four primary components to the origin side in 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 is also supplied;
+ the directory is provided by the origin site. Shibboleth is able to
+ interface with a directory exporting an LDAP interface or a SQL database
+ containing user attributes, and is designed such that programming interfaces
+ to other repositories should be readily implemented. Shibboleth relies on
+ standard web server mechanisms to trigger local authentication. A .htaccess
+ file can be easily used to trigger either the local WebISO system or the web
+ server's own Basic Auth mechanism, which will likely utilize an enterprise
+ authentication system, such as Kerberos.</p>
+ <p>From the origin site's point of view, the first contact will be the
+ redirection of a user to the handle service, which will then consult the SSO
+ system to determine whether the user has already been authenticated. If not,
+ then the browser user will be asked to authenticate, and then sent back to
+ the target URL with a handle bundled in an attribute assertion. Next, a
+ request from the Shibboleth Attribute Requester (SHAR) will arrive at the AA
+ which will include the previously mentioned handle. The AA then consults the
+ ARP's for the directory entry corresponding to the handle, queries the
+ directory for these attributes, and releases to the SHAR all attributes the
+ SHAR is entitled to know about that user.</p>
+</blockquote>
+<h4><a name="1.b."></a>1.b. Target</h4>
+<blockquote>
+ <p>There are three primary components to the target side in Shibboleth: the
+ Shibboleth Indexical Reference Establisher (SHIRE), the Shibboleth Attribute
+ Requester (SHAR), and the resource manager (RM). An implementation of each
+ of these is included in the standard Shibboleth distribution. These
+ components are intended to run on the same web server.</p>
+ <p>From the target's point of view, a browser will hit the RM with a request
+ for a Shibboleth-protected resource. The RM then allows the SHIRE to step
+ in, which will use the WAYF to acquire the name of a handle service to ask
+ about the user. The handle service (HS) will then reply with a SAML
+ authentication assertion containing a handle, which the SHIRE then hands off
+ to the SHAR. The SHAR uses the handle and the supplied address of the
+ corresponding attribute authority (AA) to request all attributes it is
+ allowed to know about the handle. The SHAR performs some basic validation
+ and analysis based on attribute acceptance policies (AAP's). These
+ attributes are then handed off to the RM, which is responsible for using
+ these attributes to decide whether to grant access.</p>
+</blockquote>
+<h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
+<blockquote>
+ <p>The WAYF service can be either outsourced and operated by a federation or
+ deployed as part of the SHIRE. It is responsible for allowing a user to
+ associate themself with an institution of their specification, then
+ redirecting the user to the known address for the handle service of that
+ institution.</p>
+</blockquote>
+<h4><a name="1.d."></a>1.d. Federations</h4>
+<blockquote>
+ <p>A federation is one way to provide part of the underlying trust required
+ for function of the Shibboleth architecture. A federation in the context of
+ Shibboleth is a group of organizations(universities, corporations, content
+ providers, etc.) who agree to exchange attributes using the SAML/Shibboleth
+ protocols and abide by a common set of policies and practices. In so doing,
+ they must implicitly or explicitly agree to a common set of guidelines.
+ Joining a federation is not explicitly necessary for operation of
+ Shibboleth, but it dramatically expands the number of targets and origins
+ that can interact without defining bilateral agreements between all these
+ parties.</p>
+ <p>A federation can be created in a variety of formats and trust models, but
+ to support Shibboleth, it must provide a certain set of services to
+ federation members. It needs to supply a registry to process applications to
+ the federation and distribute membership information to the origin and
+ target sites. This must include distribution of the PKI components necessary
+ for trust between origins and targets. There also needs to be a set of
+ agreements and best practices defined by the federation governing the
+ exchange, use, and population of attributes before and after transit, and
+ there should be a way to find information on local authentication and
+ authorization practices for federation members.</p>
+</blockquote>
+<hr>
+<h3><a name="2."></a>2. Planning</h3>
+<p>There are several essential elements that must be present in the environment
+to ensure Shibboleth functions well, both political and technical. Shibboleth
+currently runs on a specific range of platforms and web server environments. The
+SHAR and SHIRE are implemented entirely in C/C++. These are the recommendations
+and requirements for a successful implementation of a Shibboleth target.</p>
+<h4><a name="2.a."></a>2.a. Requirements</h4>
+<blockquote>
+ <p>Shibboleth currently supports Windows NT/2000/XP/2003, Linux, and
+ Solaris. At present, Shibboleth consists of Apache (or IIS) plugins and a
+ separate SHAR process. The plugins use the ONC RPC mechanism to communicate
+ with the SHAR over Unix domain or TCP sockets. The target's web servers must
+ be running <a href="http://http://www.apache.org/dist/httpd/">Apache</a>
+ 1.3.26+, or Microsoft IIS 4.0+, but not Apache 2. More precise technical
+ details are discussed in <a href="#3.a.">3.a</a>.</p>
+</blockquote>
+<h4><a name="2.b."></a>2.b. Join a Federation</h4>
+<blockquote>
+ <p>While it is not necessary for a target or origin to join a federation,
+ doing so greatly facilitates the implementation of multilateral trust
+ relationships. Each federation will have a different application process.</p>
+ <p>For more information on federations, refer to <a href="#1.d.">1.d</a> or
+ the Shibboleth v1.0 architectural document.</p>
+ <p>To use Shibboleth without a federation, manual configuration of target
+ and origin trust and site information will be needed to insure that sites
+ interoperate. Most identifiers, such as site names, should be URI-based, and
+ should be chosen in accordance with DNS domains under the control of the
+ parties involved, much as Java package naming is coordinated. In other
+ words, don't use a URI containing a DNS domain or hostname that you do not
+ control.</p>
+</blockquote>
+<h4><a name="2.c."></a>2.c. Security Considerations</h4>
+<blockquote>
+ <p>Shibboleth's protocols and software have been extensively engineered to
+ provide protection against many attacks. However, the most secure protocol
+ can be compromised if it is placed in an insecure environment. To ensure
+ Shibboleth is as secure as possible, there are several recommended security
+ precautions which should be in place at local sites.</p>
+ <ol type="i">
+ <li>SSL use is optional for target sites, but should be used if at all
+ possible, at least in the processing of incoming sessions (called the
+ SHIRE URL or assertion consumer service). Federation guidelines should
+ be considered when determining whether to implement SSL, and, in
+ general, SSL should be used for interactions with client machines to
+ provide the necessary authentication and encryption to ensure protection
+ from man-in-the-middle attacks. It is strongly suggested that all
+ password traffic or similarly sensitive data should be SSL-protected.
+ Assessment of the risk tradeoff against possible performance degradation
+ should be performed for all applications.</li>
+ <li>Many other attacks can be made on the several redirection steps that
+ Shibboleth takes to complete attribute transfer. The best protection
+ against this is safeguarding the WAYF service and ensuring that rogue
+ targets and origins are not used, generally by development of the trust
+ model underneath Shibboleth. Shibboleth also leverages DNS for security,
+ which is not uncommon, but attacks concerning bad domain information
+ should be considered.</li>
+ <li>Information regarding origin users is generally provided by the
+ authoritative enterprise directory, and the acceptance of requests from
+ target applications can be carefully restricted to ensure that all
+ requests the SHAR performs are authorized and all information the origin
+ provides is accurate. Use of plaintext passwords is strongly advised
+ against.</li>
+ <li>Server platforms should be properly secured, commensurate with the
+ level that would be expected for an organization's other security
+ services, and cookie stores on client machines should be well protected.</li>
+ </ol>
+</blockquote>
+<h4><a name="2.d."></a>2.d. Server Certs</h4>
+<blockquote>
+ <p>In the Shibboleth architecture, the SHAR, HS, and AA must all have
+ various client and/or server certificates for use in signing assertions and
+ creating SSL channels. These should be issued by a commonly accepted CA,
+ which may be stipulated by your federation. After understanding the CA's
+ acceptible to your federations, consult chapter <a href="#4.c.">4.c</a> for
+ information on certificate and key generation.</p>
+</blockquote>
+<h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
+<blockquote>
+ <p>The Attribute Authority maintains a set of rules called Attribute Release
+ Policies (ARP's) that define which attributes are released to which targets.
+ When a browser user tries to access a resource, the SHAR asks the origin
+ site AA to release all the attributes it is allowed to know, possibly
+ restricted to specifically desired subset. The SHAR provides its own name
+ and an optional URL on behalf of which the attribute request is made which
+ can further refine the information the SHAR is allowed to know. The AA
+ processes this request using all applicable ARP's, determines which
+ attributes and values it will release, and then obtains the values actually
+ associated with the browser user. The AA sends these attributes and values
+ back to the SHAR.</p>
+ <p>Targets should work together with expected origin sites to ensure that
+ the sets of attributes that both sites expect to correspond using are
+ congruent.</p>
+</blockquote>
+<h4><a name="2.f."></a>2.f. Attribute Acceptance Policies</h4>
+<blockquote>
+ <p>When a target receives a set of attributes, it must evaluate them in the
+ context of the Attribute Authority that is providing them, to assess their
+ "reasonableness". For example, if the value of an attribute is expected to
+ be from a small set of enumerated choices, the value should be compared
+ against that list. If a particular attribute or value is only trusted when
+ asserted by specific origins, that too should be checked.</p>
+ <p>Targets are configured to accept specific attributes that they understand
+ and care about, and are also configured with the rules to apply before
+ accepting the attributes for use by the RM or an application. Attributes and
+ values that don't meet the target's requirements are filtered out. The set
+ of configuration rules to make these decisions is called an Attribute
+ Acceptance Policy (AAP).</p>
+</blockquote>
+<h4><a name="2.g."></a>2.g. Browser Requirements</h4>
+<blockquote>
+ <p>A primary Shibboleth design consideration was to require very little or
+ no modification to client machines. The only requirement is that a browser
+ is used which supports cookies, redirection and SSL. Browser users will have
+ to perform an additional click to submit the authentication assertion if
+ JavaScript is not functional.</p>
+</blockquote>
+<h4><a name="2.h."></a>2.h. Clocks</h4>
+<blockquote>
+ <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should be run on all
+ web servers. Shibboleth employs a short handle issuance time to protect
+ against replay attacks. Because of this, any significant degree of clock
+ skew can hinder the ability of users to access sites successfully.</p>
+</blockquote>
+<h4><a name="2.h."></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>
+<p><br>
+</p>
+<hr>
+<h3><a name="3."></a>3. Installation</h3>
+<h4><a name="3.a."></a>3.a. Software Requirements</h4>
+<p>The Shibboleth project makes binary packages available for Solaris and Linux
+that are precompiled against recent releases of various required libraries such
+as OpenSSL. It is highly advisable to build from source when using Shibboleth in
+a production environment in order to permit patching or updating of packages as
+security holes and bugs are fixed. Building from source is necessary to give you
+complete control over your deployment platform. The binary packages represent a
+snapshot in time only. To build from source, see the <span class="fixed">
+INSTALL.txt</span> files in the doc folder of the OpenSAML and Shibboleth source
+distributions.</p>
+<p>The software requirements listed correspond to the binary distributions. In
+general, source builds should work against all recent versions of the operating
+systems and software dependencies listed below. For specific questions, inquire
+to the support mailing list, or give it a try. Note that OpenSSL releases
+frequent security updates; the version listed may not be the most current, but
+most minor "letter" updates should be usable.</p>
+<blockquote>
+ <p><b>Operating System:</b> </p>
+ <ul type="circle">
+ <li>Windows NT/2000/XP/2003<ul type="disc">
+ <li><a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a> or
+ IIS 4.0+<blockquote>
+ <p>Apache must be compiled with mod_so for DSO module support,
+ and must include SSL support (preferably using
+ <span class="fixed">mod_ssl</span>), and EAPI support (which
+ <span class="fixed">mod_ssl</span> requires and provides).
+ Shibboleth can coexist with <span class="fixed">mod_auth</span>,
+ which may be compiled or loaded into the server for use
+ elsewhere, but Shibboleth does not need or use it.</p>
+ <p>Any Apache modules used, and Apache itself, must be compiled
+ with the Microsoft DLL-based runtime, selected by compiling with
+ the /MD switch.</p>
+ </blockquote>
+ </li>
<li>
- <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
-
- <blockquote>
- <p>Apache must be compiled with mod_so for DSO
- module support, and must include SSL
- support (preferably using <span class="fixedwidth">mod_ssl</span>), and
- EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
- provides). Shibboleth can coexist with
- <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
- into the server for use elsewhere, but Shibboleth
- does not need or use it. The most recent Red Hat
- RPM (1.3.23-14 as of this writing) is sufficient.
- </p>
- </blockquote>
-
- <blockquote>
- <p>On Linux, Shibboleth requires that Apache and
- Apache-SSL be built with <span
- class="fixedwidth">libpthread</span>, or loading the
- <span class="fixedwidth">mod_shibrm</span> or <span
- class="fixedwidth">mod_shire</span> modules will
- cause Apache to stop. While RedHat's Apache is
- compatible, Debian's Apache must be rebuilt with
- <span class="fixedwidth">libpthread</span>:</p>
+ <a href="http://shibboleth.internet2.edu/release/shib-download.html">
+ Shibboleth v1.1 Target for Windows</a><blockquote>
+ <p>Available in both self-installer and ZIP format, the
+ installer will prompt for an install path, change default
+ configuration files as appropriate for Windows, and set various
+ environment variables for you. A default SHAR service can also
+ be installed for you, or you can install it manually using the
+ instructions in this guide.</p>
+ <p>Note that debug/symbol versions of the libraries and software
+ are included, and may be used by appending "debug" to the
+ Shibboleth library path and using the corresponding modules and
+ binaries. If you do so, be aware that Apache and other modules
+ must also be compiled with Microsoft's debug runtime (via the /MDd
+ compiler option). In most cases, you can safely ignore or even
+ delete the debug versions.</p>
+ </blockquote>
+ </li>
+ </ul>
+ </li>
+ <p> </li>
+ <li>RedHat 7.2-7.3:<ul type="disc">
+ <li><a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a><blockquote>
+ <p>Apache must be compiled with mod_so for DSO module support,
+ and must include SSL support (preferably using
+ <span class="fixed">mod_ssl</span>), and EAPI support (which
+ <span class="fixed">mod_ssl</span> requires and provides).
+ Shibboleth can coexist with <span class="fixed">mod_auth</span>,
+ which may be compiled or loaded into the server for use
+ elsewhere, but Shibboleth does not need or use it. The most
+ recent Red Hat RPM (1.3.27-2 as of this writing) is sufficient.</p>
+ </blockquote>
+ <blockquote>
+ <p>On Linux, Shibboleth requires that Apache and Apache-SSL be
+ built with <span class="fixed">libpthread</span>, or loading the
+ <span class="fixed">mod_shibrm</span> or <span class="fixed">
+ mod_shire</span> modules will cause Apache to stop. While
+ RedHat's Apache is compatible, Debian's Apache must be rebuilt
+ with <span class="fixed">libpthread</span>:</p>
<blockquote>
- <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
- $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
+ <p><span class="fixed">$ export LDFLAGS=-lpthread<br>
+ $ apt-build --rebuild --reinstall install \<br>
+ apache-common apache apache-ssl</span></p>
</blockquote>
- </blockquote>
+ </blockquote>
</li>
-
- <li><a href=
- "http://shibboleth.internet2.edu/release/shib-download.html">
- Shibboleth v1.0 Target for RedHat</a></li>
-
- <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
- revision <span class="fixedwidth">i</span> or newer</a></li>
-
<li>
- libstdc++3-3.0.4-1.i386.rpm and
- libgcc-3.0.4-1.i386.rpm
-
- <blockquote>
- <p>Shibboleth binaries are currently built with <a href=
- "http://www.gnu.org/software/gcc/gcc.html">GCC
- 3.04</a>, and require these specific library
- versions. They are available as RPMs and are
- available in the RedHat 7.2 updates directory on
- any <a href=
- "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
- RedHat mirror</a>. They can be installed alongside
- earlier and later GCC libraries.</p>
- </blockquote>
+ <a href="http://shibboleth.internet2.edu/release/shib-download.html">
+ Shibboleth v1.1 Target for RedHat</a></li>
+ <li><a href="http://www.openssl.org/source/">openssl-0.9.6, revision
+ <span class="fixed">i</span> or newer</a></li>
+ <li>libstdc++3-3.0.4-1.i386.rpm and libgcc-3.0.4-1.i386.rpm<blockquote>
+ <p>Shibboleth binaries are currently built with
+ <a href="http://www.gnu.org/software/gcc/gcc.html">GCC 3.04</a>,
+ and require these specific library versions. They are available
+ as RPMs and are available in the RedHat 7.2 updates directory on
+ any
+ <a href="ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
+ RedHat mirror</a>. They can be installed alongside earlier and
+ later GCC libraries.</p>
+ </blockquote>
</li>
-
- <li><b>Portions of the <span
- class="fixedwidth">libphp4</span> Apache plugin are written
- in C++, as is Shibboleth. There is a known conflict between
- the PHP extensions <span
- class="fixedwidth">libpspell.so</span> and <span
- class="fixedwidth">libsablot.so</span> which will manifest
- itself as segmentation faults when starting Apache. If a
- site wants to use <span class="fixedwidth">libphp4.so</span>
- and Shibboleth at once, then one of the following may be
- done:</b>
- <ol>
- <li>
- Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
- </li>
- <li>
- Rebuild these two modules using
- the same version of GCC that was used to compile Shibboleth.
- </li>
- </ol>
+ <li><b>Portions of the <span class="fixed">libphp4</span> Apache
+ plugin are written in C++, as is Shibboleth. There is a known
+ conflict between the PHP extensions <span class="fixed">libpspell.so</span>
+ and <span class="fixed">libsablot.so</span> which will manifest
+ itself as segmentation faults when starting Apache. If a site wants
+ to use <span class="fixed">libphp4.so</span> and Shibboleth at once,
+ then one of the following may be done:</b><ol>
+ <li>Remove the options <span class="fixed">--with-pspell</span>
+ and <span class="fixed">--with-xslt-sablot</span> from PHP's
+ configuration.</li>
+ <li>Rebuild these two modules using the same version of GCC that
+ was used to compile Shibboleth.</li>
+ </ol>
</li>
- </ul>
+ </ul>
</li>
- <br>
- <li>
- Solaris 2.8:
-
- <ul type="disc">
- <li><a href=
- "ftp://ftp.openssl.org/source/openssl-0.9.7a.tar.gz">
- openssl-0.9.7a</a>
-
- <blockquote>
- <p>The shared library version of OpenSSL is required
- by Shibboleth. The static libraries may be installed as
- well if necessary for other applications, but cannot be
- used within mod_ssl or any other Apache modules.</p>
- </blockquote>
+ <p><br>
+ </li>
+ <li>Solaris 2.8:<ul type="disc">
+ <li><a HREF="ftp://ftp.openssl.org/source/openssl-0.9.7b.tar.gz">
+ openssl-0.9.7</a>
+ <blockquote>
+ <p>The shared library version of OpenSSL is required by
+ Shibboleth. The static libraries may be installed as well if
+ necessary for other applications, but cannot be used within
+ mod_ssl or any other Apache modules. openssl-0.9.7b, the latest
+ security fix release, has been tested, but any 0.9.7 version
+ should work.</p>
+ </blockquote>
+ </li>
+ <li><a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a><blockquote>
+ <p>Apache must be compiled with mod_so for DSO module support,
+ and must include SSL support (preferably using
+ <span class="fixed">mod_ssl</span>) and EAPI support (which
+ <span class="fixed">mod_ssl</span> requires and provides).
+ Shibboleth can coexist with <span class="fixed">mod_auth</span>,
+ which may be compiled or loaded into the server for use
+ elsewhere, but Shibboleth does not need or use it.</p>
+ <p><span class="fixed">mod_ssl</span>'s loadable module,
+ <span class="fixed">libssl.so</span>, must be compiled against
+ <span class="fixed">OpenSSL 0.9.7b</span>'s shared libraries.
+ Other versions or a statically linked build of
+ <span class="fixed">libssl.so</span> will cause failures such as
+ bus errors when used with Shibboleth.</p>
+ <p>To check how OpenSSL was built, run the <span class="fixed">
+ ldd</span> command against <span class="fixed">libssl.so</span>
+ in the Apache <span class="fixed">/libexec/</span> folder and
+ check the output for references to <span class="fixed">
+ libssl.so.0.9.7b</span>. If you see an earlier version
+ mentioned, or no mention of it at all, then <span class="fixed">
+ OpenSSL 0.9.7b</span> must be built with shared libraries from
+ source, and the Apache module rebuilt with it.</p>
+ </blockquote>
</li>
-
<li>
- <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
-
- <blockquote>
- <p>Apache must be compiled with mod_so for DSO
- module support, and must include SSL
- support (preferably using <span class="fixedwidth">mod_ssl</span>) and EAPI
- support (which <span class="fixedwidth">mod_ssl</span> requires and
- provides). Shibboleth can coexist with
- <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
- into the server for use elsewhere, but Shibboleth
- does not need or use it.</p>
-
- <p><span class="fixedwidth">mod_ssl</span>'s
- loadable module, <span class="fixedwidth">libssl.so</span>, must be
- compiled against <span class="fixedwidth">OpenSSL
- 0.9.7a</span>'s shared libraries. Other versions or
- a statically linked build of <span
- class="fixedwidth">libssl.so</span> will cause
- failures such as bus errors when used with
- Shibboleth.</p>
-
- <p>To check how OpenSSL was built, run the <span
- class="fixedwidth">ldd</span> command against <span
- class="fixedwidth">libssl.so</span> in the Apache
- <span class="fixedwidth">/libexec/</span> folder and
- check the output for references to <span
- class="fixedwidth">libssl.so.0.9.7a</span>. If you
- see an earlier version mentioned, or no mention of
- it at all, then <span class="fixedwidth">OpenSSL
- 0.9.7a</span> must be rebuilt with shared libraries
- from source.</p>
- </blockquote>
+ <a href="ftp://ftp.sunfreeware.com/pub/freeware/sparc/8/libgcc-3.2.2-sol8-sparc-local.gz">
+ libgcc v3.2.2+ and libstdc++ v3.2.2+</a><blockquote>
+ <p>Shibboleth binaries are currently built with
+ <a HREF="http://www.gnu.org/software/gcc/gcc.html">GCC 3.2.2</a>,
+ and require these specific library versions or newer. They are
+ available as Sun freeware packages and can be installed
+ alongside earlier and later GCC libraries.</p>
+ </blockquote>
</li>
-
- <li><a href=
- "ftp://ftp.sunfreeware.com/pub/freeware/sparc/8/libgcc-3.2.2-sol8-sparc-local.gz">
- libgcc v3.2.2+ and libstdc++ v3.2.2+</a></li>
-
- <li><a href=
- "http://shibboleth.internet2.edu/release/shib-download.html">
- Shibboleth v1.0 Target for Solaris</a></li>
-
- <li><b>Portions of the <span
- class="fixedwidth">libphp4</span> Apache plugin are written
- in C++, as is Shibboleth. There is a known conflict with
- the PHP extensions <span
- class="fixedwidth">libpspell.so</span> and <span
- class="fixedwidth">libsablot.so</span> which will manifest
- itself as segmentation faults when starting Apache. If a
- site wants to use <span class="fixedwidth">libphp4.so</span>
- and Shibboleth at once, then one of the following may be
- done:</b>
- <ol>
- <li>
- Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
- </li>
- <li>
- Rebuild these two modules using the same version of GCC
- that was used to compile Shibboleth.
- </li>
- </ol>
+ <li>
+ <a href="http://shibboleth.internet2.edu/release/shib-download.html">
+ Shibboleth v1.1 Target for Solaris</a></li>
+ <li><b>Portions of the <span class="fixed">libphp4</span> Apache
+ plugin are written in C++, as is Shibboleth. There is a known
+ conflict with the PHP extensions <span class="fixed">libpspell.so</span>
+ and <span class="fixed">libsablot.so</span> which will manifest
+ itself as segmentation faults when starting Apache. If a site wants
+ to use <span class="fixed">libphp4.so</span> and Shibboleth at once,
+ then one of the following may be done:</b><ol>
+ <li>Remove the options <span class="fixed">--with-pspell</span>
+ and <span class="fixed">--with-xslt-sablot</span> from PHP's
+ configuration.</li>
+ <li>Rebuild these two modules using the same version of GCC that
+ was used to compile Shibboleth.</li>
+ </ol>
</li>
- </ul>
+ </ul>
</li>
- <br>
- <li>
- RedHat 8:
- <blockquote>
- <p>RedHat 8 ships with Apache 2, which is not supported by
- Shibboleth. To run Shibboleth under this OS, <a
- href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
- must be installed.</p>
- </blockquote>
- <blockquote>
- <p>Apache must be compiled with mod_so for DSO
- module support, and must include SSL
- support (preferably using <span class="fixedwidth">mod_ssl</span>), and
- EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
- provides). Shibboleth can coexist with
- <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
- into the server for use elsewhere, but Shibboleth
- does not need or use it. The most recent Red Hat
- RPM (1.3.23-14 as of this writing) is sufficient.
- </p>
- </blockquote>
-
- <blockquote>
- <p>On Linux, Shibboleth requires that Apache and
- Apache-SSL be built with <span
- class="fixedwidth">libpthread</span>, or loading the
- <span class="fixedwidth">mod_shibrm</span> or <span
- class="fixedwidth">mod_shire</span> modules will
- cause Apache to stop. While RedHat's Apache is
- compatible, Debian's Apache must be rebuilt with
- <span class="fixedwidth">libpthread</span>:</p>
- <blockquote>
- <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
- $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
- </blockquote>
- </blockquote>
-
- <ul type=disc>
-
- <li><a href=
- "http://shibboleth.internet2.edu/release/shib-download.html">
- Shibboleth 1.0 Target for RedHat</a></li>
-
- <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
- revision <span class="fixedwidth">i</span> or newer</a></li>
-
+ <p><br>
+ </li>
+ <li>RedHat 8 and 9:<blockquote>
+ <p>RedHat 8 and 9 ship with Apache 2, which is not yet supported by
+ Shibboleth. To run Shibboleth under this OS,
+ <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a> must
+ be installed.</p>
+ </blockquote>
+ <blockquote>
+ <p>Apache must be compiled with mod_so for DSO module support, and
+ must include SSL support (preferably using <span class="fixed">
+ mod_ssl</span>), and EAPI support (which <span class="fixed">mod_ssl</span>
+ requires and provides). Shibboleth can coexist with
+ <span class="fixed">mod_auth</span>, which may be compiled or loaded
+ into the server for use elsewhere, but Shibboleth does not need or
+ use it. The most recent Red Hat RPM (1.3.23-14 as of this writing)
+ is sufficient.</p>
+ </blockquote>
+ <blockquote>
+ <p>On Linux, Shibboleth requires that Apache and Apache-SSL be built
+ with <span class="fixed">libpthread</span>, or loading the
+ <span class="fixed">mod_shibrm</span> or <span class="fixed">
+ mod_shire</span> modules will cause Apache to stop. While RedHat's
+ Apache is compatible, Debian's Apache must be rebuilt with
+ <span class="fixed">libpthread</span>:</p>
+ <blockquote>
+ <p><span class="fixed">$ export LDFLAGS=-lpthread<br>
+ $ apt-build --rebuild --reinstall install apache-common \<br>
+ apache apache-ssl</span></p>
+ </blockquote>
+ </blockquote>
+ <ul type="disc">
<li>
- libstdc++3-3.0.4-1.i386.rpm and
- libgcc-3.0.4-1.i386.rpm
-
- <blockquote>
- <p>Shibboleth binaries are currently built with <a href=
- "http://www.gnu.org/software/gcc/gcc.html">GCC
- 3.04</a>, and require these specific library
- versions. They are available as RPMs and are
- available in the RedHat 7.2 updates directory on
- any <a href=
- "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
- RedHat mirror</a>. They can be installed alongside
- earlier and later GCC libraries.</p>
- </blockquote>
+ <a href="http://shibboleth.internet2.edu/release/shib-download.html">
+ Shibboleth 1.1 Target for RedHat</a></li>
+ <li><a href="http://www.openssl.org/source/">openssl-0.9.6, revision
+ <span class="fixed">i</span> or newer</a></li>
+ <li>libstdc++3-3.0.4-1.i386.rpm and libgcc-3.0.4-1.i386.rpm
+ <blockquote>
+ <p>Shibboleth binaries are currently built with
+ <a href="http://www.gnu.org/software/gcc/gcc.html">GCC 3.04</a>,
+ and require these specific library versions. They are available
+ as RPMs and are available in the RedHat 7.2 updates directory on
+ any
+ <a href="ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
+ RedHat mirror</a>. They can be installed alongside earlier and
+ later GCC libraries.</p>
+ </blockquote>
</li>
-
- <li><b>Portions of the <span
- class="fixedwidth">libphp4</span> Apache plugin are written
- in C++, as is Shibboleth. There is a known conflict with
- the PHP extensions <span
- class="fixedwidth">libpspell.so</span> and <span
- class="fixedwidth">libsablot.so</span> which will manifest
- itself as segmentation faults when starting Apache. If a
- site wants to use <span class="fixedwidth">libphp4.so</span>
- and Shibboleth at once, then one of the following may be
- done:</b>
- <ol>
- <li>
- Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
- </li>
- <li>
- Rebuild these two modules using
- the same version of GCC that was used to compile Shibboleth.
- </li>
- </ol>
+ <li><b>Portions of the <span class="fixed">libphp4</span> Apache
+ plugin are written in C++, as is Shibboleth. There is a known
+ conflict with the PHP extensions <span class="fixed">libpspell.so</span>
+ and <span class="fixed">libsablot.so</span> which will manifest
+ itself as segmentation faults when starting Apache. If a site wants
+ to use <span class="fixed">libphp4.so</span> and Shibboleth at once,
+ then one of the following may be done:</b>
+ <ol>
+ <li>Remove the options <span class="fixed">--with-pspell</span>
+ and <span class="fixed">--with-xslt-sablot</span> from PHP's
+ configuration. </li>
+ <li>Rebuild these two modules using the same version of GCC that
+ was used to compile Shibboleth. </li>
+ </ol>
</li>
- </ul>
- </li>
- </ul>
- </blockquote>
-
- <h4><a name="3.b."></a>3.b. Deploy the Shibboleth Package</h4>
-
- <blockquote>
- <p>For the sake of clarity, this deployment guide assumes
- that standard directories are used for all installations.
- These directories may be changed for local implementations,
- but must be done so consistently.</p>
-
- <ol type="1">
- <li>
- <p>Ensure that you have obtained the proper <a href=
- "http://shibboleth.internet2.edu/release/shib-download.html">
- tarball</a> for your operating system.</p>
+ </ul>
</li>
-
- <li>
- <p>The tarballs expand into <span class="fixedwidth">/opt/shibboleth</span>,
- and should be expanded as <span class="fixedwidth">root</span> from <span class="fixedwidth">/</span>.
- You should see the following directory structure:</p>
-
- <blockquote>
- <span class="fixedwidth">$ ls -al<br>
- drwxr-xr-x 10 root root 4096 Oct 24 03:54 .<br>
- drwxr-xr-x 3 root root 4096 Oct 24 00:37 ..<br>
+ </ul>
+</blockquote>
+<h4><a name="3.b."></a>3.b. Deploy the Shibboleth Package</h4>
+<blockquote>
+ <p>For the sake of clarity, this deployment guide assumes that standard
+ directories are used for all installations. These directories may be changed
+ for local implementations, but must be done so consistently.</p>
+ <ol type="1">
+ <li>Ensure that you have obtained the proper
+ <a href="http://shibboleth.internet2.edu/release/shib-download.html">
+ tarball</a> or installer for your operating system.</li>
+ <li>On Unix, the tarballs expand into <span class="fixed">
+ /opt/shibboleth</span>, and should be expanded as <span class="fixed">
+ root</span> from <span class="fixed">/</span>. If you use a different
+ layout or location, you will need to adjust your configuration files.
+ You should see the following directory structure (date and size details
+ notwithstanding):<blockquote>
+ <p><span class="fixed">$ ls -l<br>
drwxr-xr-x 2 root root 4096 Oct 24 03:54 bin<br>
+ drwxr-xr-x 2 root root 4096 Oct 24 03:54 data<br>
drwxr-xr-x 2 root root 4096 Oct 24 03:54 doc<br>
drwxr-xr-x 4 root root 4096 Oct 24 03:54 etc<br>
- drwxr-xr-x 13 root root 4096 Oct 24 03:54 include<br>
+ drwxr-xr-x 9 root root 4096 Oct 24 03:54 include<br>
drwxr-xr-x 4 root root 4096 Oct 24 03:55 lib<br>
drwxr-xr-x 2 root root 4096 Oct 24 03:55 libexec<br>
- drwxr-xr-x 4 root root 4096 Oct 24 02:02 share<br>
- </span>
- </blockquote>
- </li>
- </ol>
- </blockquote>
-
- <h4><a name="3.c."></a>3.c. Configure Apache</h4>
-
- <blockquote>
- <ol type="1">
- <li>
- <p>Shibboleth includes configuration directives in the
- file <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/apache.config</span>
- which must be added to the httpd.conf file used locally.
- It is recommended that these directives simply be added
- to the end of the existing <span class="fixedwidth">httpd.conf</span> file
- rather than trying to merge it in-line;
- <a href="#3.c.2.">step 2</a> describes the necessary
- modifications to the Apache startup script. The default
- configuration will often work, but if customization is
- necessary, these options may be modified:</p>
-
- <dl>
-
- <dd class="attribute">
- <span class="fixedwidth">LoadModule <module>
- <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the title and location of the
- <span class="fixedwidth">shibrm_module</span> resource manager and
- <span class="fixedwidth">shire_module</span> SHIRE modules. These are
- installed by default at
- <span class="fixedwidth">/opt/shibboleth/libexec/mod_shibrm.so</span>
- and
- <span class="fixedwidth">/opt/shibboleth/libexec/mod_shire.so</span></p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">SHIREConfig <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the <span class="fixedwidth">pathname</span> of the SHIRE's
- configuration file. Defaults to
- <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span>.</p>
- </dd>
-
- <dd class="attribute"><span class="fixedwidth">SHIREURL <url><br>
- <Location <url>><br>
- SetHandler <method><br>
- </Location></span></dd>
-
- <dd class="value">
- <p>Specifies the <span class="fixedwidth">URL</span> and the
- <span class="fixedwidth">method</span> the target uses to handle
- requests for Shibboleth-protected resources.
- Currently, <span class="fixedwidth">shib-shire-post</span> is the only
- available handler <span class="fixedwidth">method</span>.
- <span class="fixedwidth">SHIREURL</span> is used by Shibboleth when
- re-directing the user to the WAYF and
- <span class="fixedwidth"><Location></span> by Apache; for this
- reason, both <span class="fixedwidth">URL</span> specifications must
- match. Note that the configuration file itself
- contains <>'s, and <span class="fixedwidth">Location</span> should
- not be replaced.</p>
-
- <p>The referenced <span class="fixedwidth">URL</span> can be either a
- partial path or an absolute URL. The partial path
- allows each virtual server to use its own
- hostname and port in the SHIRE for session cookie
- purposes, while the absolute URL forces HTTP
- virtual servers to use HTTPS for the SHIRE. Use
- of a full <span class="fixedwidth">https://</span> URL is advised.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">ShibMapAttribute <attribute-uri>
- <HTTP-header> [alias]</span>
- </dd>
-
- <dd class="value">
- <p>Registers attributes to be recognized and maps
- them to an authorization <span class="fixedwidth">alias</span> for use
- in <span class="fixedwidth">.htaccess</span> files or Location Blocks
- with <span class="fixedwidth">require</span> directives.
- <span class="fixedwidth">REMOTE_USER</span> is a special case, suggested
- for use with <span class="fixedwidth">eduPersonPrincipalName</span>, and
- is automatically checked by a <span class="fixedwidth">require
- user</span> rule.</p>
- </dd>
- </dl>
-
- </li>
-
- <li>
- <a name="3.c.2."></a>
-
- <p>These modifications must be made to the Apache startup
- script:</p>
-
- <p>Add the following environment variables:</p>
-
- <blockquote>
- <span class="fixedwidth">
- SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.ini;
- export SHIBCONFIG</span>
- </blockquote>
-
- <p>If the OpenSSL libraries are not in the system's search
- path, they should be added to <span class="fixedwidth">LD_LIBRARY_PATH</span> as
- well.</p>
-
- <p>If the SHIBCONFIG environment variable is not
- specified, Shibboleth will use
- <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span> by
- default.</p>
- </li>
-
- <li>
- <p>The SHAR must be started before Apache. Among other
- methods, this can be done either by creating a separate
- SHAR startup script or by modifying Apache's RC script to
- start/stop the <span class="fixedwidth">SHAR</span> <b>before</b>
- <span class="fixedwidth">httpd</span>. It is suggested that Apache's script be
- modified by adding:</p>
-
- <blockquote>
- <span class="fixedwidth">/opt/shibboleth/bin/shar -f &</span>
- </blockquote>
-
- <p>Sample <span class="fixedwidth">init.d</span> scripts may be included with
- future releases. Ensure that the environment variables
- referenced in <a href="#3.c.2">3.c.2</a> are in
- place.</p>
-
+ drwxr-xr-x 4 root root 4096 Oct 24 02:02 share</span></p>
+ </blockquote>
+ <p>On Windows, if the installer is not used, the zip file should be
+ unpacked beneath the root of the system drive, where it will create an
+ <span class="fixed">\opt\shibboleth</span> tree that resembles the Unix
+ layout above. This will allow the standard configuration options to
+ work. <b>The <span class="fixed">C:\opt\shibboleth\lib</span> directory
+ MUST be added to the system path to enable proper operation.</b> If you
+ use a different location, changes to various configuration files must be
+ made by hand. The installer can do this for you, and is recommended in
+ such cases.</li>
+ </ol>
+</blockquote>
+<h4><a name="3.c."></a>3.c. Configure Apache 1.3.x</h4>
+<blockquote>
+ <ol type="1">
+ <li>Shibboleth includes configuration directives in the file
+ <span class="fixed">/opt/shibboleth/etc/shibboleth/apache.config</span>
+ which must be added to the httpd.conf file used locally. It is
+ recommended that these directives simply be added to the end of the
+ existing <span class="fixed">httpd.conf</span> file rather than trying
+ to merge it in-line; <a href="#3.c.2.">step 2</a> describes the
+ necessary modifications to the Apache startup script. The default
+ configuration will often work, but if customization is necessary, these
+ options may be modified:<dl>
+ <dd class="attribute"><span class="fixed">LoadModule <module>
+ <pathname></span> </dd>
+ <dd class="value">Specifies the title and location of the
+ <span class="fixed">shibrm_module</span> resource manager and
+ <span class="fixed">shire_module</span> SHIRE modules. These are
+ installed by default at <span class="fixed">/opt/shibboleth/libexec/mod_shibrm.so</span>
+ and <span class="fixed">/opt/shibboleth/libexec/mod_shire.so</span></dd>
+ <dd class="attribute"><span class="fixed">SHIREConfig <pathname></span>
+ </dd>
+ <dd class="value">Specifies the <span class="fixed">pathname</span>
+ of the SHIRE's configuration file. Defaults to <span class="fixed">
+ /opt/shibboleth/etc/shibboleth/shibboleth.ini</span>.</dd>
+ <dd class="attribute"><span class="fixed">SHIREURL <url><br>
+ <Location <url>><br>
+ SetHandler <method><br>
+ </Location></span></dd>
+ <dd class="value">Specifies the <span class="fixed">URL</span> and
+ the <span class="fixed">method</span> the target uses to handle
+ requests for Shibboleth-protected resources. Currently,
+ <span class="fixed">shib-shire-post</span> is the only available
+ handler <span class="fixed">method</span>. <span class="fixed">
+ SHIREURL</span> is used by Shibboleth when re-directing the user to
+ the WAYF and <span class="fixed"><Location></span> by Apache; for
+ this reason, both <span class="fixed">URL</span> specifications must
+ match. Note that the configuration file itself contains <>'s, and
+ <span class="fixed">Location</span> should not be replaced.<p>The
+ referenced <span class="fixed">URL</span> can be either a partial
+ path or an absolute URL. The partial path allows each virtual server
+ to use its own hostname and port in the SHIRE for session cookie
+ purposes, while the absolute URL forces HTTP virtual servers to use
+ HTTPS for the SHIRE. Use of a full <span class="fixed">https://</span>
+ URL is advised.</dd>
+ <dd class="attribute"><span class="fixed">ShibMapAttribute
+ <attribute-uri> <HTTP-header> [alias]</span> </dd>
+ <dd class="value"><b>This command has been deprecated in favor of
+ the configuration support available in the Attribute Acceptance
+ Policy file. See <a href="#4.e.">section 4.e.</a> It may be removed
+ in a future release.</b></dd>
+ </dl>
</li>
-
- <li>
- <p>The options in <span class="fixedwidth">shibboleth.ini</span> must be
- configured as documented in <a href="#4.a.">4.a</a>.
- Apache content will then need to be modified for
- Shibboleth authentication. This is discussed in <a href=
- "#4.d.">4.d</a>. It is recommended that the target then
- be tested as detailed in section <a href=
- "#5.a.">5.a</a>.</p>
+ <li><a name="3.c.2."></a>These modifications must be made to the Apache
+ startup script on Unix:<p>Add the following environment variable:</p>
+ <blockquote>
+ <p><span class="fixed">SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.ini<br>
+ export SHIBCONFIG</span></p>
+ </blockquote>
+ <p>If the SHIBCONFIG environment variable is not specified, Shibboleth
+ will use <span class="fixed">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span>
+ by default.</p>
+ <p>On Windows, the installer will set the path and SHIBCONFIG variable
+ for you in the system path, enabling Apache or IIS to be used.</li>
+ <li>If the OpenSSL libraries are not in the system's search path, they
+ should be added to <span class="fixed">LD_LIBRARY_PATH</span>. Generally
+ libtool's linker options will insure that the modules can locate the
+ Shibboleth libraries, but if not, you may need to add
+ <span class="fixed">/opt/shibboleth/lib</span> to <span class="fixed">
+ LD_LIBRARY_PATH</span> as well.</li>
+ <li>The SHAR must be started along with Apache. Among other methods on
+ Unix, this can be done either by creating a separate SHAR startup script
+ or by modifying Apache's RC script to start/stop the <span class="fixed">
+ SHAR</span> <b>before</b> <span class="fixed">httpd</span>. It is
+ suggested that Apache's script be modified by adding:<blockquote>
+ <p><span class="fixed">/opt/shibboleth/bin/shar -f &</span> </p>
+ </blockquote>
+ <p>Sample <span class="fixed">init.d</span> scripts may be included with
+ future releases. Ensure that the environment variable referenced in
+ <a href="#3.c.2">3.c.2</a> are in place.</p>
+ <p>On Windows, the SHAR is a service and is managed separately.</li>
+ <li>By default, the Shibboleth modules are configured to log information
+ on behalf of Apache to the file <span class="fixed">
+ /opt/shibboleth/etc/shibboleth/shire.log</span>, though this can be
+ changed. For this log to be created, Apache must have permission to
+ write to this file, which may require that the file be manually created
+ and permissions assigned to whatever user Apache is configured to run
+ under. If the file does not appear when Apache runs with the modules
+ loaded, check for permission problems. </li>
+ <li>The options in <span class="fixed">shibboleth.ini</span> must be
+ configured as documented in <a href="#4.a.">4.a</a>. Apache content will
+ then need to be modified for Shibboleth authentication. This is
+ discussed in <a href="#4.d.">4.d</a>. It is recommended that the target
+ then be tested as detailed in section <a href="#5.a.">5.a</a>.</li>
+ </ol>
+</blockquote>
+<h4><a name="3.d."></a>3.d. Configure Microsoft IIS</h4>
+<blockquote>
+ <ol type="1">
+ <li>The package includes an ISAPI filter and bundled extension for SHIRE
+ POST processing in a single library, <span class="fixed">libexec\isapi_shib.dll</span>.
+ This filter is configured using commands in <span class="fixed">
+ C:\opt\shibboleth\etc\shibboleth\shibboleth.ini</span>. Make sure you've
+ added the library directory to the path as directed in <a href="#3.b.">
+ section 3.b.</a><p>Installing the extension into IIS is a two step
+ process:<ol type="1">
+ <li type="a">First, add the filter using the Internet Services
+ Manager MMC console. Right click on the machine icon on the left,
+ and edit the WWW Service master properties. On the "ISAPI Filters"
+ tab, add a new filter called Shibboleth and specify the DLL named
+ above. The priority should be High, and once the filter is loaded,
+ make sure it appears in the list <b>below</b> the "sspifilt" entry.
+ Restart IIS and make sure the filter shows up with a green arrow.
+ Check the Windows event log if it fails to load. The default
+ configuration options are sparse, but they should allow the filter
+ to at least initialize.</li>
+ <li type="a">Secondly, map a special file extension, such as
+ <span class="fixed">.shire</span>, to the ISAPI library so that
+ virtual URLs can be specified to invoke the SHIRE handler for each
+ web site. Right click on the machine icon on the left, and edit the
+ WWW Service master properties. On the "Home Directory" tab, add a
+ script mapping using the "Configuration" button. The "Executable"
+ box should point to the filter/extension library, and the
+ "Extension" can be set to anything unlike to conflict, but
+ <span class="fixed">.shire</span> is assumed (and the dot must be
+ included). You should select the option to limit verbs to POST, and
+ you must uncheck the "Check that file exists" box.</li>
+ </ol>
</li>
- </ol>
- </blockquote>
- <br>
- <hr>
- <br>
-
-
- <h3><a name="4."></a>4. Getting Running</h3>
-
- <h4><a name="4.a."></a>4.a. Configuring
- <span class="fixedwidth">shibboleth.ini</span></h4>
-
- <blockquote>
- <p>Most of the configuration for the SHAR, SHIRE, and RM is stored
- in the file <span class="fixedwidth">shibboleth.ini</span>. This
- file is split into several pre-defined sections. The first
- sections, <span class="fixedwidth">general</span>, <span
- class="fixedwidth">shire</span>, and <span
- class="fixedwidth">shar</span>, define the operational parameters
- for the <span class="fixedwidth">SHIRE</span> and <span
- class="fixedwidth">SHAR</span>. The <span
- class="fixedwidth">general</span> section holds global tags, used
- by all pieces. The <span class="fixedwidth">shire</span> and <span
- class="fixedwidth">shar</span> sections can override the <span
- class="fixedwidth">general</span> tags with SHIRE- or
- SHAR-specific configuration. For example, if the SHAR is looking
- for a tag, it will look first in the <span
- class="fixedwidth">shar</span> section; if it does not find the
- tag there, it will proceed to look in the <span
- class="fixedwidth">general</span> section. The following
- sections, <span class="fixedwidth">metadata_shire</span>, <span
- class="fixedwidth">metadata_shar</span>, <span
- class="fixedwidth">attributes</span>, and <span
- class="fixedwidth">policies</span>, define the trust framework
- within the SHIRE and SHAR operate. Example configuration files
- are bundled with the Shibboleth distribution.</p>
-
- <p>There is also information that must be configured in
- <span class="fixedwidth">/usr/local/apache/conf/httpd.conf</span>; for more
- information, refer to <a href="#3.c.2.">3.c</a>.</p>
-
- <p>Information in the logger files referenced by
- <span class="fixedwidth">shibboleth.ini</span> may require additional configuration.
- It is recommended that after initial installation is
- completed, the log level in both files be changed to either
- <span class="fixedwidth">INFO</span> or <span class="fixedwidth">WARN</span>.</p>
-
- <p>Fields that are purple are optional; grey fields are
- mandatory.</p>
-
- <p><span class="fixedwidth">[general]</span>:</p>
-
- <dl>
- <dd class="attribute">
- <span class="fixedwidth">logger = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
- configuration file for most Shibboleth events. This
- element may also be optionally specified for each of
- the components individually. Default logging settings (using local log files)
- should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
- daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
- <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
- to <span class="fixedwidth">enable logging from remote machines.</span> The
- logging level is also defined in the logger configuration.
- The configuration format and log levels are similar to that of the
- <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
- property format.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">schemadir = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the directory in which the XML schema
- files are located; defaults to
- <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">sharsocket = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the location of the socket the SHAR uses to
- form connections. Note that if you change this, the SHAR and Apache
- should both be restarted immediately, since new Apache child processes will
- use the changed value as soon as they start up.</p>
- </dd>
- </dl>
-
- <p>The next segment of the <span class="fixedwidth">[general]</span> configuration
- section defines server-specific tags in sections defined by
- the server name for use by the SHIRE and RM. For example, if
- you have a web server at www.example.edu, you can define a
- section <span class="fixedwidth">[www.example.edu]</span> and override global tags
- with tags for that server only.</p>
-
- <p>The following table lists the server-specific tags. It is
- broken into mandatory tags, and optional tags. Tags in the <span
- class="fixedwidth">[general]</span> section correspond to all
- servers; to override specific tags on a per-server basis, use
- <span class="fixedwidth">[<FQDN>]</span> as the header for a
- section.</p>
-
- <span class="fixedwidth">[<general>]</span>:
-
- <dl>
-
- <dd class="attributeopt">
- <span class="fixedwidth">normalizeRequest = <true/false></span>
- </dd>
-
- <dd class="valueopt">
- <p>If true, all redirects generated by
- <span class="fixedwidth">mod_shire</span> will be created using the virtual
- server name assigned to the server containing this
- command. If <span class="fixedwidth">false</span>, the browser's supplied
- URL is used to compute the redirect back.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth">checkIPAddress = <true/false></span>
- </dd>
-
- <dd class="valueopt">
- <p>If <span class="fixedwidth">true</span>, Shibboleth will check client
- addresses for impersonation protection. In most
- circumstances, this should be enabled to prevent
- certain attacks concerning stolen cookies. Defaults
- to <span class="fixedwidth">false</span>.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth">supportContact = <e-mail></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the e-mail address used in the
- generation of error pages.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth">logoLocation = <pathname></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the location of the logo used in the
- generation of error pages. This logo can be in any
- format that the web browser will understand.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">wayfURL = <url></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the URL of the WAYF service the user is
- redirected to. Federations will generally provide this URL
- or provide information on how to locally host WAYF's with
- a distributed hosts file.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">cookieName = <string></span>
- </dd>
-
- <dd class="value">
- <p>Defines the name to be used for session cookies.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">shireSSLOnly = <true/false></span>
- </dd>
-
- <dd class="value">
- <p>If <span class="fixedwidth">true</span>, the SHIRE will reject HTTP
- connections that are not SSL-protected. This guards the initial session
- sign-on from the browser, but does not preclude non-SSL content. Use of
- SSL is strongly recommended; see section <a href=
- "#2.c.">2.c</a> for more information.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">shireError = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the location of the template for the
- error page generated when there is an error
- re-directing the user to the WAYF or processing a
- SHIRE POST.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">rmError = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the location of the template for the
- error page generated if internal errors occur in the
- RM.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">accessError = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the location of the template for the
- page displayed to users when access to a protected
- resource is denied by the RM.</p>
- </dd>
- </dl>
-
- <span class="fixedwidth">[shire]</span>:
-
- <dl>
- <dd class="attribute">
- <span class="fixedwidth">logger = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
- configuration file for most Shibboleth events. This
- element may also be optionally specified for each of
- the components individually. Default logging settings (using local log files)
- should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
- daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
- <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
- to <span class="fixedwidth">enable logging from remote machines.</span> The
- logging level is also defined in the logger configuration.
- The configuration format and log levels are similar to that of the
- <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
- property format.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth">aap-uri = <uri></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the URI of an attribute acceptance policy XML
- file. Attributes must be listed in the <span
- class="fixedwidth">aap-uri</span> file if they are to be
- visible to the Apache server. Unlisted or rejected attributes are
- filtered out and hidden from the web server (but also see the
- <b>ShibExportAssertion</b> Apache command).
- For more information, refer to section <a href="#4.e.">4.e</a>.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth">metadata = <tag></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the tag that defines the section of <span
- class="fixedwidth">shibboleth.ini</span> the SHIRE should
- use to acquire its metadata. The SHIRE does not need trust
- metadata, and so generally it will only need sites data to
- enforce attribute policies like scope limitations(e.g. MIT
- not asserting @brown.edu attributes.)</p>
- </dd>
- </dl>
-
- <span class="fixedwidth">[shar]</span>:
- <dl>
-
- <dd class="attribute">
- <span class="fixedwidth">logger = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
- configuration file for most Shibboleth events. This
- element may also be optionally specified for each of
- the components individually. Default logging settings (using local log files)
- should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
- daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
- <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
- to <span class="fixedwidth">enable logging from remote machines.</span> The
- logging level is also defined in the logger configuration.
- The configuration format and log levels are similar to that of the
- <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
- property format.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth">metadata = <tag></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the tag that defines the section of <span
- class="fixedwidth">shibboleth.ini</span> the SHAR should
- use to acquire its site and trust metadata.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth">certFile = <pathname></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the location of the PEM-format certificate used by
- the SHAR to communicate in authenticated fashion with
- origin site Attribute Authorities.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth">keyFile = <pathname></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the location of the PEM-format private key used by
- the SHAR to communicate in authenticated fashion with
- origin site Attribute Authorities.</p>
- </dd>
-
- <dd class="attributeopt">
- <span class="fixedwidth">keyPass = <password></span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies the <span class="fixedwidth">password</span> used to access the
- <span class="fixedwidth">keyFile</span>, if any.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">calist = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies a single file of PEM-format certificates containing
- the root CAs the SHAR will consider to be valid signers of AA server
- certificates. Currently applies globally to all communication with AAs.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">AATimeout = <seconds></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the number of seconds that the SHAR will wait
- for attributes to be sent from an AA. Defaults to <span
- class="fixedwidth">60</span>.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">AAConnectTimeout = <seconds></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the number of seconds that the SHAR will wait
- for a connection to be established with an AA.
- Defaults to <span class="fixedwidth">30</span>.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">cacheType = <method></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the method used by the SHAR to cache received
- attributes. The default is <span
- class="fixedwidth">memory</span>, which indicates that
- the SHAR should store received attributes in its memory.
- Another option is <span class="fixedwidth">mysql</span>,
- which will use the MySQL Credential Cache. The steps to using this are described
- in the MySQL Credential Cache guide.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">cacheClean = <seconds></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the duration in seconds between cleanups of
- the SHAR's cached but expired attributes. Defaults to <span
- class="fixedwidth">300</span>, or 5 minutes.</p>
- </dd>
-
- <dd class="attribute">
- <span class="fixedwidth">cacheTimeout = <seconds></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the duration in <span
- class="fixedwidth">seconds</span> that must elapse
- between user accesses before that user's session is
- destroyed, including the associated handle and all
- cached attributes. Defaults to <span
- class="fixedwidth">28800</span> seconds, or 8 hours.</p>
- </dd>
- </dl>
-
- <p><span class="fixedwidth">[metadata]</span> sections must be
- created and named in accordance with the value of the <span
- class="fixedwidth">metadata</span> parameter in the <span
- class="fixedwidth">[shire]</span> and <span
- class="fixedwidth">[shar]</span> sections. Metadata sections may
- be shared or defined for each component. Two providers are
- supported by Shibboleth, but additional providers may be
- specified with name/value pairs consisting of <span
- class="fixedwidth"><metadata provider type>=<source></span>.</p>
-
- <p><span class="fixedwidth">[<metadata>]</span>:</p>
-
- <dl>
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.metadata.XML = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the location of the file to load site
- metadata from. This will often be a <span
- class="fixedwidth">sites.xml</span> file stored locally,
- and may be used by both the SHIRE and SHAR.</p>
-
- <p>Shibboleth provides a simple utility called <span
- class="fixedwidth">siterefresh</span> for updating the
- metadata file as described in section <a
- href="#4.g.">4.g</a>.</p>
- </dd>
-
- <dd class="attributelong">
- <span class="fixedwidth">edu.internet2.middleware.shibboleth.trust.XML = <pathname></span>
- </dd>
-
- <dd class="value">
- <p>Specifies the location of the trust database of
- certificates and/or CA roots used by the SHAR during
- session initiation. The SHIRE module generally does not need trust
- data.</p>
- </dd>
- </dl>
-
- <p>In order for an attribute to be used by Shibboleth, it must be
- recognized as valid by the SHAR and implemented with any specific
- rules for how to understand and express its value based on the XML
- from the AA. Additional string-valued attributes may be added to
- the SHAR using the <span class="fixedwidth">[attributes]</span>
- section.</p>
-
- <p><span class="fixedwidth">[attributes]</span>:</p>
-
- <dl>
- <dd class="attribute">
- <span class="fixedwidth"><attribute_URI>=<type></span>
- </dd>
-
- <dd class="value">
- <p>Attribute names are URI's that are assigned by the
- parties standardizing the attribute. Frequently, a
- federation or standard object class may define these URI's.
- The attribute type may be either <span
- class="fixedwidth">scoped</span> or <span
- class="fixedwidth">simple</span>, which defines how
- the attribute is processed as described in section <a
- href="#4.e.">4.e</a>.</p>
- </dd>
- </dl>
-
- <p>The <span class="fixedwidth">[policies]</span> section contains the policy URI
- values that control acceptance of assertions from origin
- sites. This may eventually have multiple elements associated
- it for targets that are members of multiple federations.</p>
-
- <p><span class="fixedwidth">[policies]</span>:</p>
-
- <dl>
- <dd class="attribute">
- <span class="fixedwidth"><federation> = <URI></span>
- </dd>
-
- <dd class="value">
- <p>The name of the <span
- class="fixedwidth">federation</span> and its
- associated policy <span class="fixedwidth">URI</span>.
- These URI's will be provided by federations.</p>
-
- <p>This set of URI values is matched against the SAML
- <span class="fixedwidth">Audience</span> fields of
- assertions received from HS's and AA's. One of the
- URI's specified by the origin in <span
- class="fixedwidth">edu.internet2.middleware.shibboleth.audiences</span>
- must match one of these URIs or the
- assertion will not be accepted by design.</p>
- </dd>
- </dl>
-
- <p>Additional sections for individual servers may be defined with
- either parameters overriding those found in <span
- class="fixedwidth">[general]</span>, or the following additional
- parameters:</p>
-
- <p><span class="fixedwidth">[<FQDN>]</span>:</p>
-
- <dl>
- <dd class="attributeopt">
- <span class="fixedwidth">requestAttributes = <attr1> <attr2>
- <attr3>...</span>
- </dd>
-
- <dd class="valueopt">
- <p>Specifies a space-delimited list of attributes named by
- URI that the SHAR will request of an AA. If the parameter
- does not exist or is null, then the SHAR will receive all
- attributes the AA is willing to release to it.</p>
- </dd>
- </dl>
-
- </blockquote>
-
- <h4><a name="4.b."></a>4.b. Dynamic Error Page Generation</h4>
-
+ <li>All other aspects of configuration are handled via the
+ <span class="fixed">shibboleth.ini</span> file and associated XML-based
+ policy files described in subsequent sections. Particular use is made of
+ the per-hostname section feature that allows global settings to be
+ overridden per-site, and this permits different IIS instances to be
+ separately configured.</li>
+ <li>A special section must be added/uncommented in the
+ <span class="fixed">shibboleth.ini</span> file to support IIS usage. The
+ <span class="fixed">[isapi]</span> section must be used to map IIS
+ Instance ID numbers to fully-qualified hostnames that correspond to
+ named sections later in the file. Instance IDs are used in the IIS
+ metabase to identify web sites. They are applied starting with the
+ number 1 and number the web sites in order in the Internet Services
+ Manager from top to bottom. In the <span class="fixed">[isapi]</span>
+ section, add lines in the following form:
+ <blockquote class="fixed">
+ <p>1=hostname.domain.com<br>
+ 2=hostname2.domain.com<br>
+ (etc...)</p>
+ </blockquote>
+ <p>At least an empty configuration section named <span class="fixed">
+ hostname.domain.com</span> should then be added to the end of the file.
+ Any options specific to that web site can be added as documented in
+ later sections.</li>
+ <li>See the following section for information on running the SHAR
+ service on Windows.</li>
+ <li>The options in <span class="fixed">shibboleth.ini</span> must be
+ configured as documented in <a href="#4.a.">4.a</a>. It is recommended
+ that the target then be tested as detailed in section <a href="#5.a.">
+ 5.a</a>.</li>
+ </ol>
+</blockquote>
+<h4><a name="3.e."></a>3.e. Running the SHAR on Windows</h4>
+<blockquote>
+ <p>The SHAR is a console application that is primarily designed to be
+ installed as a Windows service. To run the process in console mode for
+ testing, the <span class="fixed">-console</span> parameter is used.
+ Otherwise, parameters are used to install (or remove) the SHAR from the
+ service database and subsequent control is via the Service Control Manager
+ applet. The following command line parameters can be used:</p>
+ <dl>
+ <dd class="attribute"><span class="fixed">-console</span></dd>
+ <dd class="value">Allows the process to be started from a command
+ prompt. Since the console will exit if the desktop user logs out, this
+ is not suitable for production use, but may be useful for testing.</dd>
+ <dd class="attribute"><span class="fixed">-config <pathname></span> </dd>
+ <dd class="value">Specifies the pathname of the SHAR's configuration
+ file. Defaults to <span class="fixed">\opt\shibboleth\etc\shibboleth\shibboleth.ini</span>
+ or the value of the <span class="fixed">SHIBCONFIG</span> environment
+ variable, if it is set.</dd>
+ <dd class="attribute"><span class="fixed">-install <servicename></span></dd>
+ <dd class="value">Installs the SHAR as a named service in the Windows
+ service database. A name should be provided if multiple instances of the
+ SHAR need to be run on different ports, and thus installed separately.
+ The <span class="fixed">-config</span> option can be provided to include
+ a specific configuration file on the service's command line.</dd>
+ <dd class="attribute"><span class="fixed">-remove <servicename></span></dd>
+ <dd class="value">Removes the named service instance of the SHAR from
+ the Windows service database.</dd>
+ </dl>
+ <h4><br>
+ </h4>
+</blockquote>
+<hr>
+<h3><a name="4."></a>4. Getting Running</h3>
+<h4><a name="4.a."></a>4.a. Configuring <span class="fixed">shibboleth.ini</span></h4>
+<blockquote>
+ <p>Most of the configuration for the SHAR, SHIRE, and RM is stored in the
+ file <span class="fixed">shibboleth.ini</span>. This file is split into
+ several pre-defined sections. The first sections, <span class="fixed">
+ [general]</span>, <span class="fixed">[shire]</span>, and
+ <span class="fixed">[shar]</span>, define the operational parameters for the
+ <span class="fixed">SHIRE</span> and <span class="fixed">SHAR</span>. While
+ not precisely accurate, the <span class="fixed">[shire]</span> section is
+ generally associated with the web server modules and libraries that
+ applications interface with, while the <span class="fixed">[shar]</span>
+ section is associated with the separate SHAR process. The
+ <span class="fixed">[general]</span> section holds global settings, used by
+ all components. The <span class="fixed">[shire]</span> and
+ <span class="fixed">[shar]</span> sections can override the
+ <span class="fixed">[general]</span> tags with SHIRE- or SHAR-specific
+ configuration. For example, if the SHAR is looking for a tag, it will look
+ first in the <span class="fixed">shar</span> section; if it does not find
+ the tag there, it will proceed to look in the <span class="fixed">general</span>
+ section.</p>
+ <p>The following sections, <span class="fixed">[metadata_shire]</span>,
+ <span class="fixed">[metadata_shar]</span>, and <span class="fixed">
+ [policies]</span>, define the trust framework within which the entire system
+ operates. Example configuration files are bundled with the Shibboleth
+ distribution, currently derived from the InQueue staging federation managed
+ by Internet2</p>
+ <p>For Apache (but not IIS), there is also information that must be
+ configured in <span class="fixed">/usr/local/apache/conf/httpd.conf</span>
+ (or equivalent); for more information, refer to <a href="#3.c.2.">3.c</a>.</p>
+ <p>Information in the logging configuration files referenced by
+ <span class="fixed">shibboleth.ini</span> may require additional changes to
+ meet local needs. The logging level can be raised to <span class="fixed">
+ INFO</span> or <span class="fixed">DEBUG</span> if additional detail is
+ needed for testing. It is recommended that after initial installation is
+ completed, the log level in both files be left at either <span class="fixed">
+ INFO</span> or <span class="fixed">WARN</span>.</p>
+ <p>Fields that are purple are optional; grey fields are mandatory. If the
+ option only applies to a specific environment, such as IIS/ISAPI only, then
+ this is indicated.</p>
+ <p><span class="fixed">[general]</span>:</p>
+ <dl>
+ <dd class="attribute"><span class="fixed">logger = <pathname></span></dd>
+ <dd class="value">Specifies the location of the <span class="fixed">
+ log4cpp</span> configuration file for most Shibboleth events. This
+ element may also be optionally specified for each of the components
+ individually (which is the default provided, so this setting is often
+ unused). Default logging settings (using local log files) should
+ suffice. If using a remote syslogd instead, the <span class="fixed">
+ syslog</span> daemon must accept <span class="fixed">UDP:514</span>
+ messages, and on Linux, <span class="fixed">SYSLOGD_OPTIONS</span> must
+ include <span class="fixed">-r</span> to enable logging from remote
+ machines. The logging level is also defined in the logger configuration
+ file. The configuration format and log levels are similar to that of the
+ <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a>
+ package's property format.</dd>
+ <dd class="attribute"><span class="fixed">schemadir = <pathname></span></dd>
+ <dd class="value">Specifies the directory in which the XML schema files
+ are located; defaults to <span class="fixed">
+ /opt/shibboleth/etc/shibboleth/</span>. This should generally be left
+ alone, unless a non-default installation path is used.</dd>
+ <dd class="attribute"><span class="fixed">sharsocket = <pathname> | [IP
+ interface:]port</span></dd>
+ <dd class="value">Specifies the location of the socket the SHAR uses to
+ form connections. Note that if you change this, the SHAR and Apache
+ should both be restarted immediately, since new Apache child processes
+ will use the changed value as soon as they start up.
+ <p>On Unix, this is usually set to a domain socket path, often something
+ in <span class="fixed">/tmp</span>. On Windows, this must be either a
+ TCP port number, or a combination of an IP address and port, with a
+ colon in between. Using an address specifies an IP interface to bind to
+ on multi-homed servers. Using just a port number generally suffices. If
+ this syntax is used on Unix, then the process will use a TCP socket
+ instead of a domain socket. </p>
+ <p><b>Security Note:</b> Using TCP, which is mandatory on Windows, can
+ be insecure if used in certain non-default configurations. If you allow
+ access to the service from other hosts, be sure a firewall is in place
+ to prevent unauthorized access. The <span class="fixed">sharacl</span>
+ setting, described later, provides some minimal filtering, but TCP is
+ still an insecure protocol.</dd>
+ </dl>
+ <p>The rest of the <span class="fixed">[general]</span> configuration
+ section defines global settings that can be overridden by server-specific
+ tags in sections defined by the server name. This is especially applicable
+ for non-Apache configurations. For example, if you have a web server named
+ www.example.edu, you can define a section <span class="fixed">[www.example.edu]</span>
+ and override global tags with tags for that server only.</p>
+ <p>The following table lists the server-specific tags. It is broken into
+ mandatory tags, and optional tags. Tags in the <span class="fixed">[general]</span>
+ section correspond to all servers; to override specific tags on a per-server
+ basis, use <span class="fixed">[<FQDN>]</span> as the header for a section (FQDN
+ means fully-qualified domain name, and corresponds to the name you assign to
+ a virtual host using the Apache ServerName directive, or that you map IIS
+ instance IDs to using the <span class="fixed">[isapi]</span> section.</p>
+ <p><span class="fixed">[<general>]</span>:</p>
+ <dl>
+ <dd class="attribute"><span class="fixed">wayfURL = <absolute url></span></dd>
+ <dd class="value">Specifies the URL of the WAYF service the user is
+ redirected to. Federations will often provide this URL in order to
+ control the way in which sites are presented to users, but a target may
+ provide this function, or it may be set directly to a specific site's
+ Handle Service, effectively rendering the system internal to a single
+ origin site.</dd>
+ <dd class="attribute"><span class="fixed">shireURL = <absolute or
+ relative url></span> ISAPI</dd>
+ <dd class="value">Specifies the URL of the SHIRE POST URL, or assertion
+ consumer service, at which new sessions are initiated. This can be an
+ absolute URL, or a relative path to be prefixed by the base URL of the
+ web site. Using an absolute URL allows a virtual server to funnel SHIRE
+ requests to a fixed location, such as in the case where a non-SSL site
+ wants to handle SHIRE requests over SSL (on a different port).
+ <p>Note that this URL will result in a cookie being set, and this cookie
+ must be returned in subsequent requests, so the virtual server's domain
+ name and port must be consistent with the SHIRE's domain name and port
+ for some browsers to properly return the cookie. If default ports are
+ used (and thus left unspecified), browsers will generally return cookies
+ set via SSL to a non-SSL server. If non-default ports are used, it is
+ recommended that this be a relative URL so that each virtual host
+ handles its own cookie operations.</p>
+ <p>For Shibboleth to function in IIS, the file extension at the end of
+ this URL must match the value configured into IIS and mapped to the
+ ISAPI extension. This causes the request to be serviced properly, even
+ though no file by that name actually exists.</dd>
+ <dd class="attribute"><span class="fixed">cookieName = <string></span></dd>
+ <dd class="value">Defines the name to be assigned to in-memory session
+ cookies.</dd>
+ <dd class="attribute"><span class="fixed">shireError = <pathname></span></dd>
+ <dd class="value">Specifies the location of the template for the error
+ page generated when there is an error re-directing the user to the WAYF
+ or processing a new session sign-on.</dd>
+ <dd class="attribute"><span class="fixed">rmError = <pathname></span></dd>
+ <dd class="value">Specifies the location of the template for the error
+ page generated if internal errors occur in the RM.</dd>
+ <dd class="attribute"><span class="fixed">accessError = <pathname></span></dd>
+ <dd class="value">Specifies the location of the template for the page
+ displayed to users when access to a protected resource is denied by the
+ RM. This is distinct from when errors occur during the evaluation
+ process itself, and indicates a denial of authorization.</dd>
+ <dd class="attributeopt"><span class="fixed">normalizeRequest = <true|false></span></dd>
+ <dd class="valueopt">If true, all redirects and computed request URLs
+ generated by Shibboleth will be created using the virtual server name
+ assigned to the server. If <span class="fixed">false</span>, the
+ browser's supplied URL is sometimes used to compute the information.
+ This sometimes has no effect, depending on the capabilities of the web
+ server, since the correct behavior is almost always to rely on the
+ server's API to report the hostname and ignore the browser.</dd>
+ <dd class="attributeopt"><span class="fixed">checkIPAddress = <true|false></span></dd>
+ <dd class="valueopt">If <span class="fixed">true</span>, Shibboleth will
+ check client addresses for impersonation protection. In most
+ circumstances, this should be enabled to prevent certain attacks
+ concerning stolen cookies, but this can cause problems for users behind
+ proxies or NAT devices. Defaults to <span class="fixed">false</span>.</dd>
+ <dd class="attributeopt"><span class="fixed">shireSSLOnly = <true/false></span></dd>
+ <dd class="valueopt">If <span class="fixed">true</span>, the SHIRE will
+ reject HTTP connections for new session sign-on that are not SSL-protected.
+ This guards the initial session sign-on from the browser, but does not
+ preclude non-SSL content. Use of SSL is strongly recommended; see
+ section <a href="#2.c.">2.c</a> for more information.</dd>
+ <dd class="attributeopt"><span class="fixed">mustContain =
+ <string1>;<string2></span> ISAPI</dd>
+ <dd class="valueopt">Controls what content in IIS to protect with
+ Shibboleth. Multiple values should be separated with a semicolon. Each
+ string is matched directly against the requested URL, and if the URL
+ contains the string, a match is made and Shibboleth applies. No regular
+ expressions are supported, only literal matches. Slashes are matched
+ like other characters, so path components can be surrounded with slashes
+ to match any requests with a particular component in the path. Defaults
+ to protecting everything on a server or site.</dd>
+ <dd class="attributeopt"><span class="fixed">contentSSLOnly = <true|false></span>
+ ISAPI</dd>
+ <dd class="valueopt">If <span class="fixed">true</span>, Shibboleth will
+ insist that any request for protected content is over an SSL connection.
+ Defaults to <span class="fixed">false</span>.</dd>
+ <dd class="attributeopt"><span class="fixed">authLifetime = <seconds></span>
+ ISAPI</dd>
+ <dd class="valueopt">If set, sessions are always terminated after the
+ specified number of seconds, resulting in a new redirect and request for
+ authentication, just as if a new request without a session is received.
+ Defaults to infinite.</dd>
+ <dd class="attributeopt"><span class="fixed">authTimeout = <seconds></span>
+ ISAPI</dd>
+ <dd class="valueopt">If set, sessions are always terminated after the
+ specified number of seconds of inactivity (defined as no requests
+ received in that session), resulting in a new redirect and request for
+ authentication, just as if a new request without a session is received.
+ Defaults to infinite.</dd>
+ <dd class="attributeopt"><span class="fixed">requestAttributes = <attr1>
+ <attr2> <attr3>...</span> </dd>
+ <dd class="valueopt">Specifies a space-delimited list of attributes
+ (named by a designated URI) that the SHAR will request when querying for
+ attributes. By default, the SHAR will ask for and receive all attributes
+ the AA is willing to release to it.</dd>
+ <dd class="attributeopt"><span class="fixed">exportAssertion = <true|false></span>
+ ISAPI</dd>
+ <dd class="valueopt">If set, the SAML attribute assertion received by
+ the SHAR is exported to a CGI request header called Shib-Attributes,
+ encoded in base64. Defaults to <span class="fixed">false</span>. While
+ this does require parsing the raw XML, it also permits an application to
+ see attributes that may have been filtered by an AAP, or to forward the
+ SAML assertion to a third party.</dd>
+ <dd class="attributeopt"><span class="fixed">supportContact = <e-mail></span></dd>
+ <dd class="valueopt">Specifies the local site's support e-mail address,
+ and is used in the generation of error pages.</dd>
+ <dd class="attributeopt"><span class="fixed">logoLocation = <pathname></span></dd>
+ <dd class="valueopt">Specifies the location of the logo used in the
+ generation of error pages. This logo can be in any format that the web
+ browser will understand, and should be a URL (absolute or relative) that
+ will return a valid logo.</dd>
+ </dl>
+ <p><span class="fixed">[shire]</span>:</p>
+ <dl>
+ <dd class="attribute"><span class="fixed">metadata = <section tag></span></dd>
+ <dd class="value">Specifies the tag that defines the section of
+ <span class="fixed">shibboleth.ini</span> the SHIRE should use to
+ acquire its metadata. The SHIRE does not need trust metadata, and so
+ generally it will only need site metadata and attribute acceptance
+ policy to define attributes and enforce policies like scope
+ limitations(e.g. MIT not asserting attributes @brown.edu.)</dd>
+ <dd class="attributeopt"><span class="fixed">logger = <pathname></span></dd>
+ <dd class="valueopt">Specifies the location of the <span class="fixed">
+ log4cpp</span> configuration file for Shibboleth events produced by the
+ web server modules and libraries. Refer to the global setting for more
+ information.</dd>
+ <dd class="attributeopt"><span class="fixed">aap-uri = <uri></span>
+ DEPRECATED</dd>
+ <dd class="valueopt">Specifies the URI of an attribute acceptance policy
+ XML file. This command has been replaced with a new metadata provider
+ type for attribute policy that should be provided to both the SHIRE and
+ SHAR components. To replace this command, add lines to both metadata
+ sections of this form:
+ <blockquote class="fixed">
+ <p>edu.internet2.middleware.shibboleth.target.AAP.XML=<uri></p>
+ </blockquote>
+ <p>For more information, refer to section <a href="#4.e.">4.e</a>. This
+ command will be removed in future releases.</dd>
+ </dl>
+ <p><span class="fixed">[shar]</span>:</p>
+ <dl>
+ <dd class="attribute"><span class="fixed">metadata = <tag></span></dd>
+ <dd class="value">Specifies the tag that defines the section of
+ <span class="fixed">shibboleth.ini</span> the SHAR&n
projects / java-idp.git / commitdiff