Page History

h2. Install and Configure Shibboleth SP service on Windows/Apache

This guide describes the process of installing and configuring a Shibboleth SP module *v1.3* for this environment:
_OS: Windows 2000/2003 server_
_Web Server: Apache_

[Internet2 Wiki|https://spaces.internet2.edu/display/SHIB/WebHome] provides most of the material. The document below is only a supplement.

Below instruction is for configuring Shibboleth SP to work with UCLA {nl:IdP} test instance. [Production configuration|https://spaces.ais.ucla.edu/display/isis/ShibbolethSPMigration2Production] varies slightly.

h3. Intended Audience

This document is intended for developers and system administrators who will be installing and maintaining a Shibboleth Service Provider server at UCLA. The audience is expected to have following skills:
* Familiarity with the local operating system, including how to install software.
* Install and Configure web server (Apache).
* Basic understanding of SSL, including how to generate a key and CSR.
* Basic understanding of XML.
* University Policy

This document covers only the technical aspects of running a Shibboleth SP software. What is equally important and one that is not covered here is the policy requirements of accessing the user data. Depending on the data(attributes) requirements, you need appropriate permission from data owners i.e Registrar's office for Student date, HR for staff and faculty. Until this request is made and approved, no production data will be released to your application. You will have to plan for data approval from respective data owners and begin to use those data according to your business needs.

h3. Before you start

Before you install Shibboleth SP software, create a simple web application to display HTTP header attributes. 
Sample JSP code to display HTTP headers:

{code:xml}
<% java.util.Enumeration names = request.getHeaderNames();
   while(names.hasMoreElements()){
        String headerName = (String) names.nextElement();
        out.println(headerName + ":" + request.getHeader(name));
   }
%>
{code}

Make sure you can access the page from a browser (for ex, http://yourhost.ucla.edu/yourapp/DisplayHttpHeaders.jsp). This page does not require Authentication yet. You will probably see a bunch of http headers information.
The idea here is to display http headers before and after shibboleth installation and compare the difference to see what shibboleth delivers. If shibboleth successfully installed you will see all http headers you saw before plus attributes delivered by shibboleth

h3. Download & Install 

Download Shibboleth SP software from Internet2 website. The site also offers documentation for installing Shibboleth on various platforms. Follow the appropriate Service Provider Installation instructions for your platform. 

Please note the site is maintained by internet2, and may have moved. If you can't locate appropriate version for your environment please contact AIS. Download is at http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/win32. 

Download the .msi Shibboleth SP installer from the download site. Run the installer. The installer will prompt for an install path, change default configuration files as appropriate for Windows, and set various environment variables for you. A service by the name shibd is also installed.

Reboot the server for the changes to take effect. You have to make several configuration changes to make it work.


h2. Configuration

h3. Include the below in Apache httpd.conf file

*Assuming a Shibboleth root directory at C:/opt/shibboleth-sp
*Name of the mod_shib file (used in {nl:LoadModule} below) varies depending on the version of Apache & Shibboleth. Note carefully.
*This is for Apache 2.0; Configuration for other version may vary slightly.

{code:xml}
LoadModule mod_shib "C:/opt/shibboleth-sp/libexec/mod_shib_20.so"

ShibSchemaDir C:/opt/shibboleth-sp/share/xml/shibboleth
ShibConfig C:/opt/shibboleth-sp/etc/shibboleth/shibboleth.xml

<IfModule mod_alias.c>
  <Location /shibboleth-sp>
    Allow from all
  </Location>
  Alias /shibboleth-sp/main.css C:/opt/shibboleth-sp/doc/shibboleth/main.css
  Alias /shibboleth-sp/logo.jpg C:/opt/shibboleth-sp/doc/shibboleth/logo.jpg
</IfModule>

<Location />
  AuthType shibboleth
  ShibRequireSession On
  require valid-user
</Location>

<Files *.sso>
SetHandler shib-handler
</Files>
{code}

<Location> block indicates all directories(paths) for this host will be protected. It means a _shibboleth_ session is required to access resources under http://somehost.ucla.edu/yourapp. If you want to protect distinct directories instead of everything under the host, you can do  in shibboleth.xml which is explained below.
 
The location of the following configuration files may vary depending on which Shibboleth installation package you used. The most common location for Windows is C:\opt\shibboleth-sp\etc\shibboleth


h3. Apache redirection 

If you are using a connector (mod_jk for Tomcat) configure them as usual 

h3. shibboleth.xml

This is the main configuration file for Shibboleth SP. It includes configuration items such as the port Shibboleth deamon runs on, Resources to protect, SSL certificates to use, providerId etc.

Eventually we will have a form where you can fill out the values specific to your application and have a custom shibboleth.xml generated for you. But for now, change the following variables specific to your SP.

You may grab a trimmed version of shibboleth.xml file at [this link|https://spaces.ais.ucla.edu/download/attachments/8224874/iis.shibboleth.xml]. It is a bit easier to read and navigate through.

{code:xml}
<TCPListener address="127.0.0.1" port="1600" acl="127.0.0.1" />
{code}
Shibboleth daemon listens on this port for requests coming from the web server. Make sure this port is available. This port should not be open to public.

{code:xml}
<Host name="yourhost.ucla.edu">
<Path name="yourapp" applicationId="yourapp" authType="shibboleth" requireSession="true" exportAssertion="true"/>
</Host>
{code}
The name of the server/VM instance host your SP is residing on. Replace _yourhost.ucla.edu_ with the actual host name of the site that your shibboleth SP is installed on. Do not include http, https etc.

Path is for individual applications within the same host. You may configure multiple applications using multiple <path>. For simplicity configure just one application.

We chose the application name _yourapp_ for demo purpose only. Use a meaningful application name.

{builder-hide}
<!--<Host name="yourhost.ucla.edu" applicationId="default" authType="shibboleth" requireSession="true">-->
</Host>
Most SP installs will only include one application on the server - if this is the case then you can ignore the second occurrence of {{Host name}}. {{<Host name="yourhost.ucla.edu" }} is commented out by default, if you do have a second application on that server then you should add in its information and un-comment the line.
{builder-hide}

{code:xml}
<ISAPI normalizeRequest="true">
   <Site id="1" name="yourhost.ucla.edu">
		<Alias>yourhost.ucla.edu</Alias>
   </Site>
{code}
This section is applicable for IIS only. Ignore this for Apache.

{code:xml}
<Applications id="default" providerId="https://yourhost.ucla.edu/shibboleth/sp" homeURL="https://yourhost.ucla.edu/index.htm">
              <Sessions lifetime="7200" timeout="3600" checkAddress="false" consistentAddress="true" handlerURL="/Shibboleth.sso" handlerSSL="false" cookieProps="; path=/;" idpHistory="true" idpHistoryDays="7">
{code}

providerId: The providerId is an identifier for SP. This is how SP identifies itself to the IdP or other federation members. You may choose an arbitrary string, we recommend the above URL convention. 
homeURL: homeURL is where the SP redirects the user to, when there is nothing else that can be done with a request. It should be set to a application home page or index page.
handlerURL: If your application is running on the root (for ex, {nl:http://yourhost.ucla.edu}) handlerURL would be /Shibboleth.sso. If your application is running as a separate application context inside the host (for ex, {nl:http://yourhost.ucla.edu/yourapp}) handlerURL would be /yourapp/Shibboleth.sso.
{builder-hide}cookieProps: Add application context to cookieProps property (for ex, _cookieProps="; path=/; yourapp"_).{builder-hide}
handlerSSL: For test or development this is usually set to false. If user can get to your application  with https URL instead of http, then set to true.

{code:xml}
<Errors session="$SHIB-HOME/etc/shibboleth/sessionError.html"
supportContact="support-contact-email-address@ucla.edu"/>
{code}

User will see this error page if there is an error during Shibboleth processing. Customize this html page to show a more friendly message. Include a proper support contact e-mail.

{code:xml}
<SessionInitiator isDefault="true"  Location="/yourapp/DisplayHttpHeaders.aspx" Binding="urn:mace:shibboleth:sp:1.3:SessionInit" wayfURL="https://shb1.ais.ucla.edu/shibboleth-idp/SSO" wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest" />
{code}
{nl:SessionInitiators} handle session requests for applications and relay them to a Single Sign On service of IdP. If a Shibboleth session is not yet established, it redirects to wayfURL to request for an Authentication session for the user.
In the above configuration wayfURL points to Single Sign On of UCLA IdP's Test instance.

{code:xml}
<CredentialUse TLS="shib_credentials" Signing="shib_credentails">
</CredentialUse>
{code}

{nl:CredentialUse} describes credentials that SP uses when communicating with various {nl:IdPs}. _sp_credentials_ above is just a placeholder; Actual credentials details (certificate & key) described further down in {nl:FileResolver} section.

{code:xml}
<Application id="yourapp" providerId="https://yourhost.ucla.edu/shibboleth/sp">
<Sessions lifetime="7200" timeout="3600" checkAddress="true" consistentAddress="true"
handlerURL="/yourapp/Shibboleth.sso" handlerSSL="false" cookieProps="; path=/;"/>
</Application>
{code}
You can customize the behavior of specific applications here. The default elements inside the
outer <Applications> element generally have to be overridden in an all or nothing fashion.
Note that single SP instance can support multiple applications which can be configured differently. 

{code:xml}
<CredentialsProvider type="edu.internet2.middleware.shibboleth.common.Credentials">
   <Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
   <FileResolver Id="sp_credentials">
   	<Key>
   		<Path>$SHIB-HOME/etc/shibboleth/testshib.key</Path>
   	</Key>
   	<Certificate>
   		<Path>$SHIB-HOME/etc/shibboleth/testshib.crt</Path>
   	</Certificate>
   </FileResolver>
{code}
Change the location of key and certificate files.

h3. shibd.logger

This is a configuration file for logging. Configure location of log file, log to a file or database, level of logging (verbose or errors only). Make sure your Web Server (IIS) can write to it. If you are testing you may want to use DEBUG level which dumps lot of diagnostic information.

h4. native.logger

Similar to shibd.logger. Contains generic Web Server information rather than the shibd daemon.

h3. Certificate and Metadata

To test with {nl:IdP} test instance you will need a Certificate and Key. Details on obtaining test certificate described in this [document|iamucla:TestshibFederation]

h3. AAP.xml

IdP delivers attributes using standard naming convention. Map them to custom http header names (or Alias) that your application expects. Your application will not receive any attributes unless they are configured in AAP.xml with a Header name.
Verify attribute names with the attribute provider (IdP). 

AIS always releases at least one attribute in test urn:mace:dir:attribute-def:eduPersonTargetedID. Rest of the attributes are released on request. 

You may use the simple rules below to replace the default AAP.xml. If you expect more than the below 3 attributes, code additional <AttributeRule>.
If you don't see the attributes you expect, perhaps IdP is not releasing them. Check with IdP.

{code:xml}
<AttributeAcceptancePolicy xmlns="urn:mace:shibboleth:1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mace:shibboleth:1.0 /usr/share/xml/shibboleth/shibboleth.xsd">

<AttributeRule Name="urn:mace:dir:attribute-def:eduPersonTargetedID" Header="SHIB-TargetedID" Alias="targetedId">
 <AnySite>
  <AnyValue />
  </AnySite>
  </AttributeRule>

<AttributeRule Name="urn:mace:ucla.edu:edimi:attributes:uclaUniversityID" CaseSensitive="false" Header="SHIB-UID" Alias="uid">
 <AnySite>
  <AnyValue />
  </AnySite>
  </AttributeRule>

 <AttributeRule Name="urn:mace:dir:attribute-def:mail" CaseSensitive="false" Header="SHIB-EMAIL" Alias="affiliation">
 <AnySite>
  <AnyValue />
  </AnySite>
  </AttributeRule>

</AttributeAcceptancePolicy>
{code}

h3. Attributes 

Visit [Available Attributes|AvailableEDAttributes] page for more attributes and the usage of these attributes within the AAP.xml.

Attributes will be released to SPs as appropriate. For ex,
_urn:mace:dir:attribute-def:displayName_    Joe Bruin
_urn:mace:dir:attribute-def:eduPersonPrincipalName_  jbruin@ucla.edu
_urn:mace:ucla.edu:edimi:attributes:uclaUniversityID_    676767676

Note the naming convention. Standard eduPerson attributes defined by MACE start with _urn:mace:dir:attribute-def:_ ; Custom attributes specific to UCLA start with _urn:mace:ucla.edu:edimi:attributes:_


h3. http vs https

Most of the development/test servers don't have SSL certs to protect the web content. Change your shibboleth.xml configuration for this. Set handlerSSL="false" and remove the parameter redirectToSSL="443". You may want to revisit this when you move to Production.


h3. Test Run

Make sure the xml file shibboleth.xml is well-formed. Typos are common errors. Opening this file in IE indicates any structural errors.

Now that you completed above configuration changes run the Shibboleth daemon. From command line run
_$SHIB-HOME/sbin/shibd  -console  -check_

Check the console and log files (native.log & shibd.log). If you see no errors you got the basics right. Not all problems can be detected this way. Only an end-to-end testing involving the {nl:IdP} will confirm if its been set up & configured properly.

h3. Restart IIS and Shibboleth daemon

Now access the same sample page, {nl:http://yourhost.ucla.edu/yourapp/DisplayHttpHeaders.aspx}. You will see same http headers you saw earlier plus some Shibboleth attributes like {nl:eduPersonTargetedID}. If you saw Shibboleth attributes, end-to-end testing is successful. 

Attribute name you see on the page depends on how you mapped in AAP.xml. 

If you saw errors on page, or didn't see the attributes check the logs first (shibd.log). Contact the {nl:IdP}(AIS) and verify SP has been configured properly at the {nl:IdP}. 


h3. Additional Resources

Shibboleth Wiki - The [Shibboleth Wiki|https://spaces.internet2.edu/display/SHIB/WebHome] is the primary source of documentation for all aspects of installing and configuring Shibboleth.

Internet2 Mailing Lists - the Shibboleth project maintains three mailing lists to announce news and discuss Shibboleth development and deployment. You are strongly encouraged to join shibboleth-users if you have any trouble installing or configuring Shibboleth. Subscription details are available at [http://shibboleth.internet2.edu/support.html#lists]

For a list of common errors visit https://spaces.internet2.edu/display/SHIB/CPPSPCommonErrors