Provisioning Steps

html: Security restricted macro is not allowed. An edit restriction is required that matches the macro authorization list.

<#comment></#comment>

<TITLE>MIT IS&T: MIT Touchstone, enabling an application</TITLE>

<#comment></#comment>

<#comment></#comment>
<META content="Paul Hill" name="Author"></META>
<META content="authentication, Shibboleth, InCommon, certificates, Touchstone, webauth, account, accounts, kerberos, username, FAQ, answers, help, registering, registration" name="keywords"></META>
<META content="MIT Touchstone home page includes links for information about MIT Touchstone, web authentication, Shibboleth, InCommon, developer support, integration support, and more" name="description"></META>

<MCE:SCRIPT language="JavaScript" mce_src="http://web.mit.edu/ist/scripts/rollover.js" src="http://web.mit.edu/ist/scripts/rollover.js" type="text/javascript"></MCE:SCRIPT>

<#comment></#comment>

<#comment></#comment>

<#comment></#comment>

<A class="topnav" href="http://web.mit.edu/ist/about/index.html" mce_href="http://web.mit.edu/ist/about/index.html" title="about IS&T, and our contact info">About

IS&T</A><IMG alt height="8" mce_src="http://web.mit.edu/ist/images/spacer.gif" src="http://web.mit.edu/ist/images/spacer.gif" width="5"></IMG> <A accesskey="0" class="topnav" href="http://web.mit.edu/ist/contact.html" mce_href="http://web.mit.edu/ist/contact.html" title="Access Key: Alt (or control) + 0">Contact IS&T</A><IMG alt height="8" mce_src="http://web.mit.edu/ist/images/spacer.gif" src="http://web.mit.edu/ist/images/spacer.gif" width="5"></IMG> <A accesskey="6" class="topnav" href="http://web.mit.edu/ist/sitemap.html" mce_href="http://web.mit.edu/ist/sitemap.html" title="Access Key: Alt (or control) + 6">Site Map</A><IMG alt height="8" mce_src="http://web.mit.edu/ist/images/spacer.gif" src="http://web.mit.edu/ist/images/spacer.gif" width="15"></IMG></TD>

<#comment></#comment>

<SPAN class="search">Search</SPAN>

<A accesskey="5" class="topnav" href="http://web.mit.edu/ist/search/" mce_href="http://web.mit.edu/ist/search/" title="Access Key: Alt (or control) + 5">Advanced Search</A>

<#comment></#comment>

</TR>

<TR>

</TR>

</TBODY>

</FORM></TABLE>

<#comment></#comment>

<#comment></#comment>

<TD height="40">
<H1><IMG alt height="35" mce_src="http://web.mit.edu/ist/images/spacer.gif" src="http://web.mit.edu/ist/images/spacer.gif" width="13"></IMG>
<A id="startcontent" name="startcontent"></A>MIT Touchstone: enabling an application

</H1>

</TR>

</TBODY></TABLE></TD>

</TR>

</TBODY></TABLE></TD>

</TR>

</TBODY></TABLE>

<#comment></#comment>

<#comment></#comment>

<TD valign="top" width="160">
<P><A href="http://mit.edu/touchstone/" mce_href="http://mit.edu/touchstone/"><B>MIT Touchstone</B></A></P>
<P><A href="http://shibboleth.internet2.edu/" mce_href="http://shibboleth.internet2.edu/"><B>Shibboleth® at Internet 2</B></A></P>
</TD>

</TR>

</TBODY></TABLE></TD>

<#comment></#comment>

<P>In order to make your application use MIT Touchstone, or Shibboleth, for authentication, several steps have to be performed.
MIT Information Services offers consulting services to make this process easier. However, many people at MIT are able to perform
each of these simple steps with minimal intervention from IS&T.
</P>

<P>
The boxes below are intended to help guide you through your configuration.
</P>

<TD class="subjectheads" height="22" nowrap="nowrap" width="100%">
Installing, or building, the Shibboleth SP software for your system
</TD>

<#comment></#comment>

</TR>

<P><B>
Shibboleth SP version information
</B></P>
<P>
IS&T is currently supporting customers intending to use Shibboleth 1.3x. We expect to start supporting Shibboleth 2.x based SPs
in the late Spring of 2009.
</P>

<P><B>Using installers:</B></P>

<P>
RPMs are available from Internet2 for <A href="http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/RPMS/i386/RHE/" mce_href="http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/RPMS/i386/RHE/"><B>RHEL 4 and 5</B></A>.
</P>
<P>
You will typically need the 5 main RPMs: log4shib, opensaml, shibboleth, xerces-c, xml-security-c.
</P>
<P>
You should normally skip the -devol, -debug, and -doc RPMs from the Internet2 RPM download site.
</P>
<P>
If your system does not already have curl installed, you will need to install it (via the stock RHEL RPM).
</P>
<P>
An installer for <A href="http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/win32/" mce_href="http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/win32/">IIS</A> is also available from Internet2.
</P>
<P>
Some other Linux distributions also maintain binary installers available from the OS distribution point. If you have questions
about other distributions please contact touchstone-support and indicate what operating distribution and version you are using.
</P>

<P><B>Building from source:</B></P>

<P>
The Touchstone team maintains a
<A href="http://web.mit.edu/touchstone/shibboleth/source/shibboleth-sp-sources.tgz" mce_href="http://web.mit.edu/touchstone/shibboleth/source/shibboleth-sp-sources.tgz">source tarball</A>
of tbe Shibboleth SP, including all of
its immediate prerequisites (curl, log4shib, xerces-c, xml-security-c, and opensaml),
and a script to perform the entire build, in the touchstone locker,
in /mit/touchstone/shibboleth/source/shibboleth-sp-sources.tgz.
</P>
<P>
The script can build the software on Linux and Solaris systems; note that you will to need to have
Apache httpd (preferably 2.x, though 1.3 should also work) and OpenSSL (0.9.7 or higher) installed
on the system, including their development packages. On Solaris systems, you must have the native
Sun C/C++ compiler installed; Athena Solaris machines have this available, via attachandrun scripts
and the sunsoft locker, but this requires that you have AFS tokens for the athena cell. Solaris machines
must also have GNU make (gmake) installed.
</P>
<P>
To build from this, create a build directory, and unpack the source tarball into it; use the build-sp.sh script as follows:
</P>
<B>
</B><PRE><B> # sh build/build-sp.sh [-a &ltapxs_path>] [-p &ltinstall_prefix>] [-s openssl_prefix]<BR></BR> </B></PRE>

<P><BR></BR></P>
<P>
The -a option argument is the path to the Apache apxs executable, e.g. /usr/local/apache2/bin/apxs
(defaults to using the apxs in the PATH). The -p option specifies the install prefix
(defaults to /usr/local/shibboleth). The -s option specifies the install location of the version of
OpenSSL you want to build against, e.g. /usr/local/ssl (defaults to finding OpenSSL in standard system library locations).
</P>
<P>
Once you have built the software successfully, you will need to configure and customize it for use.
</P>

</TD>

</TR>

</TBODY></TABLE>

</TD>

<#comment></#comment>
<TD width="15">
<IMG alt height="1" mce_src="http://web.mit.edu/ist/images/spacer.gif" src="http://web.mit.edu/ist/images/spacer.gif" width="15"></IMG>
</TD>

</TR><TR>

<TD class="subjectheads" nowrap="nowrap" width="100%">
Certificate request and configuration
</TD>

</TR>

<P>
<B>Note:</B>
Before proceeding to "Configuration and customization for use" you should obtain a server certificate.
</P>
<P>
If your server already has a server certificate issued by the MIT Certificate Authority, and it was issued after July 1st, 2008, and
it has not expired, you should be to use it with Shibboleth/MIT Touchstone. If the server certificate was issued prior to July 1st, 2008,
you probably need to obtain a new server certificate.
</P>
<P>
<B>Please make sure that you use lower case servernames in your certificate request. The server name within the certifiacte is case sensitive.</B>
</P>
<P>
Information about how to generate a certificate request and where to send the request can be found in
<A href="https://wikis.mit.edu/confluence/display/WSWG/How+to+acquire+and+verify+a+M.I.T.+x509+Server+Certificate"> https://wikis.mit.edu/confluence/display/WSWG/server+certificates</A>
</P>
<P>
Only section one of the above document is directly applicable to your configuration at this time.
</P>

</TD>

</TD>

</TR>

</TBODY></TABLE>

<TD class="subjectheads" nowrap="nowrap" width="100%">
Configuration and customization for use
</TD>

</TR>

<P>
<B>Note:</B>
The gen-shib.sh procedure described below currently works only on Linux and Solaris systems; it should be portable to other UNIX-based systems without too much effort.
</P>

<P>
When you have successfully built and installed the Shibboleth SP, you will need to configure
things to work against our test and pilot IdPs. We have some template files and a script in
AFS (the touchstone locker) to generate the needed config files from the templates: cd to
shibboleth's etc directory ($prefix/etc/shibboleth), and copy in the following files
from /mit/touchstone/shibboleth/config/shibboleth-sp/ (or just copy all files from the directory):
</P>

<UL>
<LI>AAP.xml.in</LI>
<LI>shibboleth.xml.in</LI>
<LI>MIT-metadata.xml</LI>

<P>
Note: If you do not have AFS installed on your server, then you can access the above files via http, either from a browser or using wget.
The URL is <A href="http://web.mit.edu/touchstone/shibboleth/config/shibboleth-sp/" mce_href="http://web.mit.edu/touchstone/shibboleth/config/shibboleth-sp/">http://web.mit.edu/touchstone/shibboleth/config/shibboleth-sp/</A>
</P>
<P>
On Solaris, also copy:
</P>

<UL>
<LI>shibd.in </LI>
<LI>shibd-wrapper.in</LI>
</UL>

<P>
Then run the gen-shib.sh script:
</P>

<P>
and answer its prompts, which will hopefully be clear. <B>Remember that the certificate it wants should be
enabled for client as well as server use.</B> Any MIT server certificates that have been created after July of 2008
will be enabled for client as well as server use.
</P>
<P>
The $prefix/etc/shibboleth directory will contain apache.config, apache2.config, and apache22.config, which contain needed
and example directives for Apache 1.3, Apache 2.0, and Apache 2.2, respectively; copy and/or include the appropriate file
in your Apache config, and customize as needed. The directory also contains a shibd init script for Red Hat (shibd-redhat)
and Debian (shibd-debian) systems. On Red Hat machines, copy shibd-redhat to /etc/init.d/shibd, make sure it is executable,
add it as a managed service with "chkconfig --add shibd", and enable it for run levels 3, 4, and 5 ("chkconfig --level 345 shibd on").
On Solaris machines, the gen-shib.sh script will generate a shibd init script (from shibd.in); this should be installed
into /etc/init.d, and configured to start at boot time, <B>after</B> httpd has started.
</P>

<P>
<B>NOTE:</B>
shibd is a daemon that must be running, so make sure it is started at boot time, after Apache httpd has been started.
</P>

<P>
The Shibboleth Apache module logs by default to $prefix/var/log/httpd/native.log. <B>This file must be writable by Apache</B>,
which may require that you set its directory's ownership and/or permissions to allow write access by the user Apache is
configured to run under. You may also choose to change the location of the file, by modifying the log4j.appender.native_log.fileName
setting in $prefix/etc/shibboleth/native.logger.
</P>

<P>
For information on configuring Shibboleth to protect content, see
the <A href="https://spaces.internet2.edu/display/SHIB/SPProtectionConfig" mce_href="https://spaces.internet2.edu/display/SHIB/SPProtectionConfig">Shibboleth wiki</A> at Internet2, as well as
the information in the sections below.
</P>

<P>
You will probably also want to customize the error pages and support contact information listed in the Errors element
in $prefix/etc/shibboleth/shibboleth.xml (search for "You should customize these pages!"), e.g.:
</P>

<BLOCKQUOTE>
<P>
&ltErrors session="/usr/local/shibboleth/etc/shibboleth/sessionError.html"
metadata="/usr/local/shibboleth/etc/shibboleth/metadataError.html"
rm="/usr/local/shibboleth/etc/shibboleth/rmError.html"
access="/usr/local/shibboleth/etc/shibboleth/accessError.html"
ssl="/usr/local/shibboleth/etc/shibboleth/sslError.html"
supportContact="root@localhost"
logoLocation="/shibboleth-sp/logo.jpg"
styleSheet="/shibboleth-sp/main.css"/>

</P><P>
The pages are used as follows:
</P>

<UL>
<LI>
session
<P>
displayed if a session cannot be created after successful authentication,
for example if shibd is not running. In a standard configuration, you can
force this page to be displayed by visiting the server's /Shibboleth.sso location, e.g.:
<B>https://my-sp.mit.edu/Shibboleth.sso</B>
</P><P>

</P></LI><LI>
metadata
<P>
displayed in certain cases where there is no valid metadata
for an identity provider. This should not happen using our
standard configuration; it should only be possible when
using the Artifact profile, or "lazy sessions", and there
is a configuration problem. You can force the page to be
displayed by visiting:
<B>https://my-sp.mit.edu/Shibboleth.sso?providerId=NoSuchIdP</B>
</P>
</LI>
<LI>
rm
<P>
displayed when an exception occurs when exporting assertions into
request headers. This indicates a software problem, and should
not happen.
</P>
</LI>
<LI>
access
<P>
displayed for access control failures. This should only
happen if you have access control directives in the Apache
configuration for your Shibboleth-protected content. You
can force the page to be displayed by adding an access
control directive that is certain to fail, for example
"require NoSuchAlias" (remember to remove this configuration
when you have completed testing).
</P>
</LI>
<LI>
ssl
<P>
displayed when a POST is attempted using http instead of https,
and RedirectToSSL is in effect. This should not happen on a
properly configured server.
</P>
</LI>
</UL>

</TD>

</TD>

</TR>

</TBODY></TABLE>

<TD class="subjectheads" nowrap="nowrap" width="100%">
Letting the IdP know about your application
</TD>

</TR>

<P>
Until the MIT Identity Providers know about your application, they won't release information about an authenticated user to your server. Each
Touchstone enabled application running on a server needs to be registered with the IdPs.
</P>
<P>
To register your application server with the MIT IdPs sendmail to touchstone-support with the following information:
</P><UL>
<LI>
A <B>contact email address</B>. We strongly recommend that this be an email list rather than an indivdual's persoanl email address.
</LI>
<LI>
The <B>server or host name</B>. If you have multiple applications installed on the same server, you will actually need to register each
application's provider ID. See below for more details.
</LI>
<LI>
<B>Organization name</B>. This is typically the name of the MIT department, lab, or center running the application.
</LI>
<LI>
<B>Organization URL</B>. The URL that provides some basic information about your department, lab, or center.
</LI>
</UL>
<P></P>
<P>
We also encourage you to send the following optional information with your registration information:
</P><UL>
<LI>
The application URL. The actual URL which will be used to access your application.
</LI>
<LI>
Your server platform. (RHEL 4, RHEL 5, Windows, Debian, Solaris, ...)
</LI>
</UL>

<P></P>
<P>
The IdP doesn't really need to know your hostname. It does need to know the Provider ID that uniquely identifies your application.
Typical MIT installations that use the gen-shib.sh script (see above) hide this detail from you so that we simply need the hostname.
If you want to learn more about provder ID naming please see <A href="https://spaces.internet2.edu/display/SHIB/EntityNaming" mce_href="https://spaces.internet2.edu/display/SHIB/EntityNaming"> <B>EntityNaming</B> </A>
at the Internet2 wiki site.
</P>
<P>
A single Shibboleth SP installation is designed to support multiple applications installed on that server, but there are different
deployment and configuration strategies to support multiple applications. At MIT we recommend that each application be configured to use
a separate Apache vhost, in addtion to simply creating additional ProviderIDs for each application.
More information is available here: <A href="https://spaces.internet2.edu/display/SHIB/AddSeparateApplication" mce_href="https://spaces.internet2.edu/display/SHIB/AddSeparateApplication"><B>Shib 1.3 Add Separate Application</B></A>.
</P>

<P>
You should ensure that your SP's copy of the MIT metadata is kept up to date. The current metadata is available in <A href="http://web.mit.edu/touchstone/shibboleth/config/metadata/MIT-metadata.xml" mce_href="http://web.mit.edu/touchstone/shibboleth/config/metadata/MIT-metadata.xml"> http://web.mit.edu/touchstone/shibboleth/config/metadata/MIT-metadata.xml</A>.
</P>
<P>
The easiest way to maintain the metadata is via a cron job which runs a script to download and install the latest metadata. A sample of such a script is available in <A href="http://web.mit.edu/touchstone/shibboleth/config/metadata/update-metadata.sh-example" mce_href="http://web.mit.edu/touchstone/shibboleth/config/metadata/update-metadata.sh-example"> http://web.mit.edu/touchstone/shibboleth/config/metadata/update-metadata.sh-example</A>.
Adjust it as necessary for your installation; in particular, if you did not install from the stock RPMs from Internet2, you will need to adjust the setting for the Shibboleth etc directory at the top of the script.
</P>
<P>
The Shibboleth SP software detects and loads the updated metadata automatically; there is no need to restart the web server or shibd.

</P>

</TD>

</TD>

</TR>

</TBODY></TABLE>

<TD align="left" class="subjectheads" nowrap="nowrap" valign="middle" width="100%">
Example code and configuration information for third party applications
</TD>

<#comment></#comment>

</TR>

</TD>

<P>
We have some pointers to example code written in various lanaguages. We do expect the examples to increase
over time. We are also creating some local documentation that covers the configuration of third party software.
However, users are encouraged to look at resources outside of MIT as well. If you do find useful information please
do bring it to our attention.
</P>

<P>
Some simple examples:
</P><UL>
<LI>
<A href="http://wikis.mit.edu/confluence/display/TOUCHSTONE/Sample+Source+Code+The+SAML+Assertion" mce_href="http://wikis.mit.edu/confluence/display/TOUCHSTONE/Sample+Source+Code+The+SAML+Assertion">Display</A> the results of the SAML assertion in various languages.
</LI>
</UL>
<P></P>

<P>
Third party applications:
</P><UL>
<LI>
<A href="https://wikis.mit.edu/confluence/display/TOUCHSTONE/Drupal" mce_href="../../../../../../../../../display/TOUCHSTONE/Drupal">Drupal</A>
</LI>
</UL>
<P></P>

</TD>

</TD>

</TR>

</TBODY></TABLE>

<TD align="left" class="subjectheads" nowrap="nowrap" valign="middle" width="100%">
Support Resources
</TD>

<#comment></#comment>

</TR>

</TD>

<TD class="border-b"> <P><B>Consulting Services:</B></P>

<P>
Consulting service may be arranged by sending mail to touchstone-support. This will open an RT case
and a person will be assigned to work with you.
</P>

<P><B>Training:</B></P>

<P>We are intending to offer some hands on training during <A href="http://student.mit.edu/iap/nsis.html" mce_href="http://student.mit.edu/iap/nsis.html">IAP 2009</A>.
Space will be limited to 18 participants. The hands-on lab is scheduled for January 20th, 1:30-3:30pm. There will also be session talking about
configuration options on January 16th, from 2:30-4:00pm.
</P>

<P><B>Who to Contact:</B></P>

<P>

Web: <A href="http://mit.edu/touchstone" mce_href="http://mit.edu/touchstone">MIT Touchstone</A><BR></BR>

Email: <A href="mailto:touchstone-support@mit.edu" mce_href="mailto:touchstone-support@mit.edu">touchstone-support@mit.edu<BR></BR>

</A></P>

</TD>

</TR>

</TBODY></TABLE></TD>

</TR>

</TBODY></TABLE></TD>

</TR>

</TBODY></TABLE>

<#comment></#comment>

</TR>

<TD><SMALL><A accesskey="2" href="http://web.mit.edu/ist/index.html" mce_href="http://web.mit.edu/ist/index.html" title="Access Key: Alt (or control) + 2">Home</A> | <A href="http://web.mit.edu/ist/start/index.html" mce_href="http://web.mit.edu/ist/start/index.html" title="learn the basics of computing and communications">Getting Started</A> | <A href="http://web.mit.edu/ist/services/index.html" mce_href="http://web.mit.edu/ist/services/index.html" title="find information, products, and services">Getting Services</A> | <A accesskey="8" href="http://web.mit.edu/ist/help/index.html" mce_href="http://web.mit.edu/ist/help/index.html" title="Access Key: Alt (or control) + 8">Getting Help</A> | <A href="http://web.mit.edu/ist/about/index.html" mce_href="http://web.mit.edu/ist/about/index.html" title="about IS&T, and our contact info">About IS&T</A>

<A accesskey="7" href="http://web.mit.edu/ist/accessibility.html" mce_href="http://web.mit.edu/ist/accessibility.html" title="Access Key: Alt (or control) + 7">Accessibility</A><BR></BR>

Ask a <A href="http://web.mit.edu/ist/help/index.html" mce_href="http://web.mit.edu/ist/help/index.html">technology question</A> or send a <A accesskey="0" href="http://web.mit.edu/ist/contact.html" mce_href="http://web.mit.edu/ist/contact.html" title="Access Key: Alt (or control) + 0">comment about this web page.</A><A accesskey="0" href="http://web.mit.edu/ist/accessibility.html" mce_href="http://web.mit.edu/ist/accessibility.html"></A></SMALL></TD>

</TR>

</TBODY></TABLE>

<#comment></#comment>

<#comment></#comment>

Child pages

Provisioning Steps