IAMUCLA
Child pages
  • InstallShibSPOnLinuxApache
Skip to end of metadata
Go to start of metadata

IShibboleth SP 1.3 Install & Configuration For Linux/Apache

Audience: System/Application Administrators
Category: Technical Guides
Version/Platform: Shibboleth SP 1.3 / Linux-Apache

This guide describes the process of installing and configuring a Shibboleth Service Provider module 1.3 for this environment:
_OS: Redhat 4
_Web Server: Apache/Tomcat

Internet2 Wiki provides most of the material. The document below is only a supplement.

Below instruction is for configuring Shibboleth SP to work with UCLA IdP test instance. Production configuration varies slightly.

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 servers (Apache, IIS, etc).
  • Basic understanding of SSL, including how to generate a key and CSR.
  • Basic understanding of XML.
  • Familiarity with 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.

Before you start

Simple JSP page

Before you install Shibboleth SP software, create a simple web application to display HTTP header attributes. This could be a PHP script, Ruby application, or a JSP page.

Make sure you can access the page using a host name, for ex, http://myapp.ucla.edu/testapp/default.jsp.
You can then install and configure Shibboleth SP to protect this resource.

Sample jsp code to display HTTP headers:

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

Shibboleth Glossary

If some of the Shibboleth terms are confusing you can visit the Shibboleth Glossary.

Obtaining Metadata and Certificates.

To test with IdP test instance you will need a Certificate. Details on obtaining test certificate described in this document. Once you have obtained the certs and metadata please make sure they are on the server.

Install Guide

Detailed Configuration.

To install Shibboleth you will need to obtain the rpm from the Shibboleth site (Please note that the files can be changed on the internet2 site). Then you will start installing the files by following the dependency chain for the files. The chain goes as follows from 1st to last.

  • log4shib*.rpm
  • xerces*.rpm
  • xml-security*.rpm
  • opensaml*.rpm
  • shibboleth*.rpm

The location of the following configuration files will vary depending on which Shibboleth installation package you used. The most common locations are:

For RedHat Linux: /etc/shibboleth
For other UNIX systems: /opt/shibboleth-sp/etc/shibboleth

For Linux/Apache setups we assume an installation into /etc/shibboleth. This is the path used in our shibboleth environment. You will need to configure shibboleth.xml, copy the metadata information to your server, and get a certificate for your server.

Once you have Shibboleth installed, you'll need to configure it to point to the "test" instance of Shibboleth IdP at UCLA.

You can use curl and rpm commands in Linux to download and install rpms. Please choose the correct url(rpm version) from the download site.

Caution: The commands below are just examples. They may not apply to all distributions of Linux. Please go to the download site to pick up the latest binaries for your environment and modify the curl and rpm commands as necessary

curl -O http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/RPMS/i386/RHE/4/log4shib-1.0-1.i386.rpm \
     -O http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/RPMS/i386/RHE/4/xerces-c-2.8.0-1.i386.rpm \
     -O http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/RPMS/i386/RHE/4/xml-security-c-1.4.0-1.i386.rpm \
     -O http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/RPMS/i386/RHE/4/opensaml-1.1.1-2.i386.rpm \
     -O http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/RPMS/i386/RHE/4/shibboleth-1.3.1-2.i386.rpm

rpm -ivh log4shib-1.0-1.i386.rpm \
    xerces-c-2.8.0-1.i386.rpm \
    xml-security-c-1.4.0-1.i386.rpm \
    opensaml-1.1.1-2.i386.rpm \
    shibboleth-1.3.1-2.i386.rpm

Apache configuration/httpd.conf

  • Note: Assumes shibboleth root directory is "/etc/shibboleth" (adjust accordingly)
  • Note: Name of mod_shib file (used in LoadModule below) varies depending on the version of Apache/Shibboleth. Commented are the other possible file names.
  • Note: If you are running Tomcat and your application is also root level please read this guide as well.
LoadModule mod_shib /usr/libexec/mod_shib_20.so
#LoadModule mod_shib /usr/libexec/mod_shib_13.so
#LoadModule mod_shib /usr/libexec/mod_shib_22.so

ShibSchemaDir /usr/share/xml/shibboleth
ShibConfig /etc/shibboleth/shibboleth.xml

<IfModule mod_alias.c>
  <Location /shibboleth-sp>
    Allow from all
  </Location>
  Alias /shibboleth-sp/main.css /usr/share/doc/shibboleth-1.3/main.css
  Alias /shibboleth-sp/logo.jpg /usr/share/doc/shibboleth-1.3/logo.jpg
</IfModule>

<Location /myapp>
  AuthType shibboleth
  ShibRequireSession On
  require shibboleth
  require valid-user
</Location>
<Files *.sso>
SetHandler shib-handler
</Files>

Place the code above at the end of your httpd.conf file. You will have to change the Location element above to the path that you want to protect. Please also make a change to the Location element and reference the path to your application.

Configuring shibboleth.xml

This configuration is for a fairly simple and basic Shibboleth SP setup. It sets up the SP for one application. However more advanced configuration can be used. You can visit the Internet2 configuration page or you can view our Advance shibboleth.xml configuration.

This is the main configuration file for Shibboleth SP. It includes Port Shibboleth deamon runs on, Resources to protect, SSL certificates to use (for attribute exchange with IdP), and how your application identifies itself to the IdP.

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.

For now please grab the shibboleth.xml file at this link. You can then either make the changes now and move them to the server or move them to the server and then make changes. This shibboleth.xml file is a trimmed down version of the one that comes installed. It is a bit easier to read and navigate through.

<!--  Shibboleth deamon listener port 
Changes maybe be needed to be made here
-->
<TCPListener address="127.0.0.1" port="1600" acl="127.0.0.1"/>

Shibboleth deamon listens on this port for requests coming from the web server. Leave it as is. This port should not be open to public.

<!-- Host name configuration 
Changes need to be made here
-->
<Host name="myhost.ucla.edu">
     <Path name="myapp" applicationId="myapp" authType="shibboleth" requireSession="true" exportAssertion="true"/>
</Host>

The name of the server/VM host your SP is residing on. Replace yourhost.ucla.edu with the host name of the site that your shibboleth SP is installed on. Do not include http, https, www, etc.

Path is for individual applications within the same host. You may use the same configuration for all applications or configure them differently.

<!-- Application ID Configuration 
     Changes need to be made here
-->
<Applications id="default" providerId="https://myhost.ucla.edu/shibboleth/testshib/sp" homeURL="https://myhost.ucla.edu">
	<Sessions lifetime="7200" timeout="3600" checkAddress="false" consistentAddress="true" handlerURL="/Shibboleth.sso" handlerSSL="true" cookieProps="; path=/; secure" idpHistory="true" idpHistoryDays="7">

The providerID is your applications URI. This is how IdP identifies your SP. This should be unique within a federation. When you registered for testshib your Entity ID will be your providerID. homeURL is the default page of the application.

If your application is running on the root (for ex, http://myhost.ucla.edu) handlerURL would be /Shibboleth.sso. If your application is running as a separate context inside the host (for ex, http://myhost.ucla.edu/myapp) handlerURL would be /myapp/Shibboleth.sso. This will also depend on your entity Id/Provider Id you used to register your application in testshib.

<!-- SessionInitiator configuration 
     Changes need to be made here
-->		
<SessionInitiator isDefault="true" id="myapp" Location="/WAYF/idp.example.org"
	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"/>

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) .

<!-- Error Message Configuration 
     Changes need to be made here
-->
	<Errors session="/etc/shibboleth/sessionError.html"
		metadata="/etc/shibboleth/metadataError.html"
		rm="/etc/shibboleth/rmError.html"
		access="/etc/shibboleth/accessError.html"
		ssl="/etc/shibboleth/sslError.html"
		supportContact="root@localhost.com"
		logoLocation="/shibboleth-sp/logo.jpg"
		styleSheet="/shibboleth-sp/main.css"/>

User will see this error page if there is an error in Shibboleth processing. Customize this page to show a more friendly message. Change root@localhost to a proper support contact e-mail.

<!--  Credential Configuration 
      Changes need to be made here
-->
<CredentialUse TLS="myapp_creds" Signing="myapp_creds"/>

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

<!-- AAP Configuration 
     Changes need to be made here
-->
<AAPProvider type="edu.internet2.middleware.shibboleth.aap.provider.XMLAAP" uri="/etc/shibboleth/AAP.xml"/>

Configure location of AAP.xml

	
<!-- Metadata Configuration 
    Changes need to be made here
-->
	<MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata"
		uri="/etc/shibboleth/testshib-metadata.xml"/>

Configure location of metadata.xml

<!-- Credential Location Configuration 
      Changes need to be made here
-->
<CredentialsProvider type="edu.internet2.middleware.shibboleth.common.Credentials">
	<Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
		<FileResolver Id="myapp_creds">
			<Key>
				<Path>/etc/shibboleth/myapp.testshib.key</Path>
			</Key>
			<Certificate>
				<Path>/etc/shibboleth/myapp.test.shib.crt</Path>
			</Certificate>
		</FileResolver>
		
		</Credentials>
</CredentialsProvider>

Change the path of key, certificate files. The FileResolver id is the id you used in the Credential Configuration

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 (Apache) can write to it. If you are testing you may want to use DEBUG level which dumps lot of diagnostic information.

native.logger

Similar to shibd.logger. Contains generic Web Server information rather than the shibd daemon. Please note that proper privileges need to be made, so that native.logger can log in the proper directory.

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.

<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>

Attributes

You can visit the Available Attributes 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:

http vs https

Most of 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 will want to revisit this when you move to Production.

Test Run

Open the AAP.xml file in your shibboleth directory and edit the element that looks like the code below. Remove the element "Scope" and then save the file.

<AttributeRule Name="urn:mace:dir:attribute-def:eduPersonTargetedID" Scope="true" Header="Shib-TargetedID" Alias="targeted_id">

Now that you completed above configuration changes run the Shibboleth daemon and restart Apache.

You can use the command "shibd -t" to check if you have any minor errors.

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 IdP will confirm if its been set up & configured properly.

Contact the IdP(AIS) and verify SP has been configured properly at the IdP. Access the protected resource. If you see a http header Shib-TargetedID end-to-end testing is successful. Good luck!

Additional Resources

Shibboleth Wiki - The Shibboleth Wiki 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

1 Comment

  1. user-2d79d

    add cookiespath edit
    add /demo/Shibboleth.sso edit