Shibboleth Implementation

From GFIPM Implementation Wiki
Revision as of 03:13, 14 January 2011 by Matt.Moyer (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Shibboleth is a freely available, open-source SAML software package for Web single sign-on across or within organizational boundaries. It allows Web sites to make informed authorization decisions regarding user access to protected online resources in a privacy-preserving manner. Shibboleth was developed through the Internet2 initiative.

Hardware Recommendations

This section describes the basic hardware, operating system, Web server, and network requirements for participants who choose to use Shibboleth in their GFIPM federation deployment.

IDPs and SPs each require server-class machines. Both machines must be of contemporary performance specifications. Specifically, the following minimum performance characteristics are recommended for each machine:

  • 3.0 MHz Core2 Duo Pentium-4 (or equivalent) processor
  • 2 GB of memory
  • 160 GB of disk space

If a participant plans to implement multiple IDPs or SPs, additional servers are recommended. Some participants may also wish to implement their servers on virtual machines, in which case appropriate hardware should be chosen.

The only other hardware requirement is that the machines be able to run the participant's chosen operating system. Each participant must choose and install an OS platform on the machines. GTRI strongly recommends that participants choose one of the following OS platforms:

  • Microsoft Windows Server 2003 or later
  • Red Hat Enterprise Linux (AS or ES)

GTRI currently operates a reference implementation of an Identity Provider and a Service Provider on each of these two OS platforms. By using one of these platforms, participants can ensure that GTRI will be able to provide them with the best possible technical assistance.

Each participant must choose and install a Web server on the two machines. GTRI recommends that participants choose one of the following Web servers:

  • Microsoft Internet Information Server (for Windows-based systems)
  • Apache HTTP Server (for Linux-based systems)

GTRI operates a reference implementation of an Identity Provider and a Service Provider on each of these two Web servers. By using one of these Web servers, participants can ensure that GTRI will be able to provide them with the best possible technical assistance.

Participants must configure the Service Provider machine to have a static public IP address, a domain name, and Internet connectivity on port 443 (HTTPS). In addition, port 80 (HTTP) may be used for a public page of the portal or merely as a means to forward incoming connections to port 443. For security purposes, GTRI recommends that all other ports be blocked by a firewall. The Identity Provider machine must be accessible to allow local users to authenticate, but Internet access to the IDP may or may not be provided depending on local needs.

Identity Provider Installation

The Shibboleth Identity Provider (IDP) is a standard Java Web application based on the Servlet 2.4 specification.

The official Shibboleth installation instructions are brief and lacking in some details. They are available from the Shibboleth Web site at:

https://spaces.internet2.edu/display/SHIB2/IdPInstall

You must follow the above instructions to install Shibboleth. Additional Shibboleth installation instructions with more descriptive details are provided below for your convenience. You should follow both sets of instructions simultaneously.

Note that the instructions below make certain assumptions about version numbers for software packages and file names. These version numbers reflect the most recent versions available at the time of this writing. You may need to make minor adjustments during this process, depending on the versions that are available as you work through the installation. UNLESS NOTED OTHERWISE, YOU SHOULD ALWAYS USE THE LATEST VERSION OF EACH SOFTWARE PACKAGE AT THE TIME OF YOUR INSTALLATION.

Download file shibboleth-idp-2.1.2-bin.zip as directed and unzip the file (it will unzip into the directory ./identityprovider). Follow the official Shibboleth installation instructions above and install Shibboleth IDP into the following directory:

/opt/shibboleth-idp-2.1.2 (or a directory of your choice).

The following is the output of running the ANT script to install the files:

  1. ./ant.sh

Buildfile: build.xml

install:

Is this a new installation? Answering yes will overwrite your current configuration. [yes|no]

yes

Where should the Shibboleth Identity Provider software be installed? [default: /opt/shibboleth-idp-2.1.2]

What is the hostname of the Shibboleth Identity Provider server? [default: idp.example.org]

idp.cisanet.net

A keystore is about to be generated for you. Please enter a password that will be used to protect it.

XXXXXXXX

Updating property file: /home/gtri/downloads2/identityprovider/install.properties

Created dir: /opt/shibboleth-idp-2.1.2/bin

Created dir: /opt/shibboleth-idp-2.1.2/conf

Created dir: /opt/shibboleth-idp-2.1.2/credentials

Created dir: /opt/shibboleth-idp-2.1.2/lib

Created dir: /opt/shibboleth-idp-2.1.2/lib/endorsed

Created dir: /opt/shibboleth-idp-2.1.2/logs

Created dir: /opt/shibboleth-idp-2.1.2/metadata

Created dir: /opt/shibboleth-idp-2.1.2/war

Generating signing and encryption key, certificate, and keystore.

Copying 5 files to /opt/shibboleth-idp-2.1.2/bin

Copying 8 files to /opt/shibboleth-idp-2.1.2/conf

Copying 1 file to /opt/shibboleth-idp-2.1.2/metadata

Copying 38 files to /opt/shibboleth-idp-2.1.2/lib

Copying 4 files to /opt/shibboleth-idp-2.1.2/lib/endorsed

Copying 1 file to /home/gtri/downloads2/identityprovider/build/WEB-INF

JARs are never empty, they contain at least a manifest file

Building jar: /opt/shibboleth-idp-2.1.2/war/idp.war

BUILD SUCCESSFUL

After the installation, further configuration operations are required as follows.

Note: Some file names contain a version number (2.0.2 or 1.5, etc.). In some cases, you may find files with a later version than listed here. Unless otherwise noted, you should use the later versions.

Create required link: 

cd /opt

ln -s shibboleth-idp-2.1.2 shib-idp

Edit file /opt/ shib-idp/conf/relying-party.xml:

  • Modify MetadataProvider of type FileBackedHTTPMetadataProvider to retrieve the metadata from http://gfipm.net/metadata/gfipm-signed-metadata.xml.
  • Modify security:Credential to refer to the correct key and crt files.
  • Uncomment and modify security:TrustEngine to refer to the correct GFIPM CA crt file.

Edit file conf/attribute-filter.xml:

  • Add <AttributeFilterPolicy id="releaseGFIPM"> ... for GFIPMAssertion-1.0.

Edit file conf/attribute-resolver.xml:

  • Get a new, slimmer version from GTRI and edit it.
  • Modify resolver:DataConnector to use CISA's LDAP directory.

Create file gfipm/dsml2gfipm_cisanet.xsl.

Create all files in gfipm/xsd.

Take the following files from Conn2.0.2b.zip and copy them to /opt/shib-idp/lib:

  • castor-1.0.jar
  • castor-1.0-srcgen-ant-task.jar
  • castor-1.0-xml.jar

Take the following file (33298 bytes, dated Feb 20, 2008 15:56) and copy it to /opt/shib-idp/lib:

  • gfipm-shib-trunk-jdk-1.5.jar

Note that the above four files also need to be copied to directory /opt/tomcat5/CISAIDP/Webapps/idp/WEB-INF/lib

Additionally, files in ./credentials and ./metadata need to be configured from certificate files set up during your Web server configuration. If you would like information on how to install or configure an Apache Web server and/or Tomcat servlet engine with Shibboleth, please contact gfipm-support@lists.gatech.edu to request available instructions.

Create directory and change ownership to the tomcat user: 

cd /opt/shib-idp

mkdir users

chown -R tomcat:tomcat.

Testing the IDP

The basic method for testing the Shibboleth IDP is to use the status URL, which is of the form:

https://FQDN/idp/profile/Status

where FQDN is your IDP machine's fully qualified domain name. If it is working, it will show a Web page with a simple

ok

in the Web browser. If it is not working, it will show one of several error messages (and also check the log files as described below).

There are two sets of log files that you can monitor:

  • Tomcat servlet engine log files:

These are typically located in the [Tomcat_Install_Dir]/logs/ directory. There are several log files in this directory, but the main file is usually named catalina.out.

If a different Java servlet container than Tomcat is used, the log files should be in that particular container's log directory.

  • Shibboleth IDP log files:

These are typically located in the [IDP_Install_Directory]/logs/ directory. The file idp-process.log (or similar) is relevant for tracing operations in a minimal IDP installation. The idp-access.log and idp-audit.log files are generally relevant only on fully functional systems.

Service Provider Installation

The Shibboleth Service Provider (SP) is a stand-alone daemon running as a background process.

To read the Shibboleth 2 release announcement, go to:

http://shibboleth.internet2.edu/shib-v2.0.html

To download the necessary software for Shibboleth 2 SP, go to the "Downloads" section. For the Linux RHEL RPMfiles, go down to the RPMS directory.

Note that the instructions below make certain assumptions about version numbers for software packages and file names. These version numbers reflect the most recent versions available at the time of this writing. You may need to make minor adjustments during this process, depending on the versions that are available as you work through the installation. UNLESS NOTED OTHERWISE, YOU SHOULD ALWAYS USE THE LATEST VERSION OF EACH SOFTWARE PACKAGE AT THE TIME OF YOUR INSTALLATION.

Download these files (version numbers may be slightly different):

  1. log4shib-1.0-1.i386.rpm
  2. xerces-c-2.8.0-1.i386.rpm
  3. xml-security-c-1.4.0-1.i386.rpm
  4. xmltooling-1.0-6.i386.rpm
  5. opensaml-2.0-6.i386.rpm
  6. shibboleth-2.0-6.i386.rpm

NOTE: To uninstall an old Shibboleth version, uninstall the above packages in reverse order, as given above. Use the rpm package command to uninstall: 

rpm -e -v <package-name>

Official Shibboleth 2 installation instructions may be found at:

https://spaces.internet2.edu/display/SHIB2/NativeSPLinuxInstall

Follow the above official Shibboleth installation instructions carefully and fully, and then follow the detailed configuration instructions given below.

Edit file /etc/shibboleth/shibboleth2.xml:

  • MetadataProvider- specify the URI to the http/xml metadata file. This file might not yet be available because 1) the metadata doesn't exist until there is at least 1 SP and 1 IDP deployed or 2) the file is not yet globally available. In these cases, either use a local xml file of your IDP metadata (built during the installation of your IDP) or a copy (if available) of the federation metadata file. Its URL is http://gfipm.net/metadata/gfipm-signed-metadata.xml.
  • Change all instances of https://sp.example.org to your SP URL.
  • Change all instances of https://idp.example.org to your IDP URL.
  • Change all instances of https://ds.example.org/DS to your Discovery Service URL (note that your DS host may use http).
  • The CredentialResolver section needs the service provider's certificate and key files added.
  • SignatureMetadataFilter- provide the root certificate for the GFIPM CA.
  • SessionInitiator - remove 'relayState="cookie"' to work around a known bug in v 2.0.

Edit the file conf/attribute-map.xml so that it exports all GFIPM user attributes required by your Service Provider. For example: 

<Attribute name="gfipm:2.0:user:LocalId" id="GfipmLocalId">
  <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="true"/>
</Attribute>
<Attribute name="gfipm:2.0:user:GivenName" id="GfipmGivenName">
  <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="true"/>
</Attribute>
<Attribute name="gfipm:2.0:user:SurName" id="GfipmSurName">
  <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="true"/>
</Attribute>
<Attribute name="gfipm:2.0:user:EmailAddressText" id="GfipmEmailAddress">
  <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="true"/>
</Attribute> ...  <!-Snipped for brevity, but all relevant attributes would be included typically -->

Failure to make this modification will cause the SP to receive no metadata, even though both the IDP and SP seem to be working (no error messages).

Add participant SP public and private key certificates to /etc/shibboleth/ssl/.

  • cisanetsp.crt
  • cisanetsp.key
  • Also specify these filenames in file shibboleth2.xml in section CredentialResolver.

Verify that file /etc/init.d/shibd looks correct (generally, it is correct as is).

Logging output:

  • To get more details in the log output, modify file shibd.logger: (on line 2)
    • change: log4j.rootCategory=INFO, shibd_log
    • to: log4j.rootCategory=DEBUG, shibd_log
  • By default, log files are written to directory /var/log/shibboleth.

To get the Shibboleth SP metadata file (to send to GTRI), use a browser to go to the following:

Save to sp-metadata.xml and send to GTRI to incorporate into the GFIPM entities metadata.

The installation should be complete at this point.

To start or stop the Shibboleth process, use the script /etc/init.d/shibd:

/etc/init.d/shibd start

/etc/init.d/shibd stop

Known Issues

The Shibboleth SP is typically installed on the Tomcat application server [Tomcat], which may be running behind the Apache httpd Web server. A connector is required to connect Apache and Tomcat.

Retrieved from "https://impl.gfipm.net/mwiki/index.php?title=Shibboleth_Implementation&oldid=57"