Carnegie Mellon University Website Home Page
 

Installing Shibboleth v2.5: Apache or Windows

Information included on this page will help you to install and use Web Login (Shibboleth) for authentication on an Apache or Windows server.

  • For more information on configuring Shibboleth to work with Carnegie Mellon identity providers, please contact weblogin@andrew.cmu.edu.
  • For general information on configuring Shibboleth, including advanced configuration options, please consult the Internet2 Shibboleth documentation.

Step 1: Set Up Apache or Windows with SSL

Follow these steps to set up Apache or Windows with SSL:

Note: When configuring an Apache server, we recommend RedHat 5, CentOS 5, SUSE 11 or OpenSUSE 11 for use with Shibboleth. Other distributions may work, but will require additional steps beyond what is documented here.

  1. To set up and configure Apache or Windows with SSL encryption, refer to your distribution's instructions.
  2. Shibboleth protected web pages should also be protected with TLS/SSL encrypted connections; for this you need an SSL certificate. To request a certificate using the CMU CA please visit the Certificate Authority web page.
    Note: Shibboleth utilizes a self-signed certificate internally. This is different from the TLS/SSL web server certificate and is created by Shibboleth software itself.
  3. Follow your system's installation instructions to install the certificate received from the Certificate Authority for the web server.
  4. To connect to the Apache or Windows server on your computer, visit http://HOSTNAME/ (where HOSTNAME is your server name).
  5. To obtain an encrypted connection, visit https://HOSTNAME/.
    Note: Be sure to use "https" and not "http". You must establish an encrypted connection to your server in order to continue.

Step 2: Install Shibboleth

Depending on your system support style, follow the appropriate links to install Shibboleth and download necessary files. Once you've finished, return to this page and continue with Step 3 (below):

RPM-based system OR Compile from Source
  1. Installation steps Wiki Shibboleth (Linux)
  2. Download CMU Shibboleth configuration template cmu-linux-25-shibboleth2.xml
  3. Download InCommon metadata signing certificate incommon.pem and store it to /etc/shibboleth/incommon.pem
Windows
  1. Installation steps Wiki Shibboleth (Windows)
  2. Download CMU Shibboleth configuration template cmu-windows-25-shibboleth2.xml
  3. Download InCommon metadata signing certificate incommon.pem and store it to C:/opt/shibboleth-sp /etc/shibboleth/incommon.pem
    Note: If you receive the error "No MetadataProvider available," open the incommon.pem file and make sure there are no trailing carriage return/line feeds (CR/LF's).

Step 3: Signature Verification

Federation metadata is signed for integrity and authenticity. Participants are strongly encouraged to verify the XML signature on the metadata file before use; failure to do so will seriously compromise the security of your SAML deployment.

To verify the XML signature on the metadata file before use, review the Metadata Refresh Policy.

Step 4: Create/Rollover Certificate and Key files

It is desireable to preserve old and recreate service provider certificates in the following situations:

  • the default installation creates a certificate that does not contain a ten year lifetime
  • the default installation creates a certificate for the hostname rather than the service name you are using
  • you want to refresh an old certificate (Note: Be sure to save the old certificate and private key for Key Rollover)

Based on your system type, follow the appropriate steps below to preserve and recreate service provider certificates:

  • RPM-based system OR Compile from Source, enter the following:
    cd /etc/shibboleth
    mv sp-cert.pem sp-cert.pem.old
    mv sp-key.pem sp-key.pem.old

    sh keygen.sh -u shibd -g shibd -h servicename -y 10
  • Windows systems, enter the following:
    cd c:/opt/shibboleth-sp/etc/shibboleth
    ren sp-cert.pem sp-cert.old
    ren sp-key.pem sp-key.old
    keygen.bat -h servicename -y 10
Note: In both examples, sp-cert.pem is the existing certificate that you want to replace and servicename is the new certificate name that matches your servicename. The -y 10 specifies the lifetime of the certificate to be created.

Step 5: Configure the Shibboleth Service

Most of the configuration for a Shibboleth service provider is in the /etc/shibboleth/shibboleth2.xml file. Note the following:

  • Linux systems:
    Copy the shibboleth2.xml file that you downloaded in Step 2 to /etc/shibboleth/shibboleth2.xml.
  • Windows systems:
    Copy the shibboleth2.xml file that you downloaded in Step 2 to C:/opt/shibboleth-sp/etc/shibboleth/shibboleth2.xml

Edit the /etc/shibboleth/shibboleth2.xml file as follows:

  1. UPDATE THE ENTITYID TO REFLECT YOUR HOSTNAME.
    Remember to use the same hostname that was used with your certificate generation.
    <ApplicationDefaults entityID="https://sp.example.org/shibboleth "REMOTE_USER="eppn persistent-id targeted-id">
  2. UPDATE THE SUPPORT CONTACT INFORMATION.
    The email address provided will be used when displaying error message pages or the logout page.
    <Errors supportContact="root@localhost" logoLocation="/shibboleth-sp/logo.jpg" styleSheet="/shibboleth-sp/main.css"/>
  3. ENABLE FETCHING: InCOMMON METADATA
    Metadata is the information used to locate and establish trust between service provider and identity providers that use shibboleth. Carnegie Mellon identity and service providers are part of the InCommon Federation. To fetch the metadata from the InCommon Federation, one of the XML configuration blocks in shibboleth2.xml must be uncommented. Do one of the following:
    • If your service is within SII,  uncomment the following block: <MetadataProvider type="XML" uri="http://md.incommon.org/InCommon/InCommon-metadata.xml" backingFilePath="incommon-metadata.xml" reloadInterval="7200"> <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/> <MetadataFilter type="Signature" certificate="incommon.pem"/> <TransportOption provider="CURL" option="10004">sii proxy.iso.cmu.edu:3128</TransportOption>
    • If your service provider is directly on the Internet, uncomment the following block:<MetadataProvider type="XML" uri="http://md.incommon.org/InCommon/InCommon-metadata.xml" backingFilePath="incommon-metadata.xml" reloadInterval="7200"> <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/><MetadataFilter type="Signature" certificate="incommon.pem"/>

      The InCommon metatdata will be periodically fetched, its signature verified, and your service provider's metadata configuration will be updated automatically.
  4. SELECT THE DISCOVERY SERVICE OR A SINGLE IDENTITY PROVIDER
    Shibboleth allows the use of a discovery service, which permits a user to select which identity provided they will use for authentication. Alternatively, the service provider may configure one static identity provider to use. Do one of the following:
    • To use the InCommon Discovery Service:
      • Uncomment the following block: <SSOdiscoveryProtocol="SAMLDS" discoveryURL="https://wayf.incommonfederation.org/DS/WAYF"<https://wayf.incommonfederation.org/DS/WAYF%22>> SAML2 SAML1 </SSO>
    • To use only the Carnegie Mellon identity provider:
      • Uncomment the following block: <SSO entityID="https://login.cmu.edu/idp/shibboleth"<https://login.cmu.edu/idp/shibboleth%22>> SAML2 SAML1 </SSO>
      • InCommon registration will allow individuals from other institutions to authenticate to your service. If you want to limit your web server to only Carnegie Mellon, you must configure your web server/application to verify that the userid is @andrew.cmu.edu. See the Advanced Topics page for steps.

Step 6: Registering Your Service Provider with InCommon

At this point your system should have a properly configured shibboleth; however, it will NOT work until it is registered with InCommon Federation. To register, send an email message as follows:

Mail to: shibboleth-team@andrew.cmu.edu
Subject: New Registration
Body:

Include the following in the message body:

  1. SP Host Name -This name should be the fully qualified DNS name that your audience will use to access your web service.
  2. SP Display Name -Include a user-friendly name for your service; please limit this to a few words.
  3. Registrants -List the name(s) and Andrew userID(s) of the people who you wish to register and their respective roles. Typically, the technical support person is registered, but you may also register administrative and support personnel as well. Note: We will only accept username@andrew.cmu.edu addresses.
  4. Copy contents of the sp-cert.pem file into the body of the message.


Optional: To include additional elements, please see Optional Interface Elements.

You will be contacted once the registration is complete; you should allow two business days.

Step 7: Testing Your Service Providers Configuration

  1. Using a web browser on your service provider, visit: https://HOSTNAME/Shibboleth.sso/Status. Information about your service provider should be displayed.
  2. Access https://HOSTNAME/secure. This will redirect your browser to either a discovery service or identity provider permitting you to log in.   
    Note: If you do not have a secure directory configured in apache, access will fail.  If you host multiple IP addresses, add the non-default IP address to your /etc/shibboleth/shibboleth2.xml file: <Handler type="Status" Location="/Status" acl="128.2.xxx.xxx ::1"/>

Step 8: Protect Your Pages

Once you have completed all steps to install and configure Shibboleth, you can use it to protect a directory on your web server. Depending on your system support style, follow the appropriate steps below:

Last Updated: 10/7/14