Carnegie Mellon University

Install Shibboleth: 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 general information on configuring Shibboleth, including advanced configuration options, please consult the Internet2 Shibboleth documentation.

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. Shibboleth protected web pages should also be protected with TLS/SSL encrypted connections; for this you need an SSL certificate. Request a certificate using the CMU CA.
    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.
  2. Follow your system's installation instructions to install the certificate received from the Certificate Authority for the web server.
  3. To connect to the Apache or Windows server on your computer, visit http://HOSTNAME/ (where HOSTNAME is your server name).
  4. 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.

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

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.

It is desirable 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.

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-idp-only.xml" backingFilePath="incommon-metadata.xml" reloadInterval="7200">
      <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
      <MetadataFilter type="Signature" certificate="incommon.pem"/>
      <TransportOption provider="CURL" option="10004">proxy.andrew.cmu.edu:3128</TransportOption>
      </MetadataProvider>
    • If your service provider is directly on the Internet, uncomment the following block:
      <MetadataProvider type="XML" uri="http://md.incommon.org/InCommon/InCommon-metadata-idp-only.xml" backingFilePath="incommon-metadata.xml" reloadInterval="7200">
      <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
      <MetadataFilter type="Signature" certificate="incommon.pem"/>
      </MetadataProvider>

      The InCommon metadata 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.

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 accept only username@andrew.cmu.edu addresses.
  4. Copy contents of the sp-cert.pem file into the body of the message.

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

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

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:

The following optional elements may be used. Be sure to include them in your registration email message:

SP Description - A brief description (140 characters or less) of the service may be provided.

SP Information URL - Used to create a link to a service information page. The content of this page should expand on the content of the SP Description field.

SP Privacy Statement URL - Used to create a link to a Privacy Statement targeted at end users.

SP Logo URL - A service logo for building graphical user interfaces; must meet the following requirements:

  • transparent background
  • landscape orientation (width > height)
  • minimum width of 100 pixels
  • minimum height of 75 pixels and a maximum height of 150 pixels (or the application will scale it proportionally)