Installation and Configuration

The first step is to install the Shibboleth SP and if neccessary the HTTP and Application servers.  This section covers how to install the Shibboleth SP and how to configure to work on the UCSD network.

Note: the configuration tools and subsequent instructions on this page apply only to the UC San Diego Shibboleth environment. Please consult the Shibboleth wiki for more general configuration instructions.

Installation

The Shibboleth Service Provider software is available for various platforms at the shibboleth web site. Installation instructions are available here. Once installed, please follow the configuration instructions below for your specific platform.

Configuration

UCSD has a tool which will generate a set of config files for the Shibboleth SP.  The zip file produced by the tool has the latest config files for the UCSD network, including attribute mappings, meta-data and Shibboleth configuration.

Review and Update Configuration Files

  1. Download and extract the compressed package into a temporary directory.
  2. Familiarize your self with the shibboleth2.xml file and verify your:
  3. Locate the Shibboleth configuration directory containing configuration files. Depending on the package you selected, most common paths are:
    Windows Server c:\opt\shibboleth-sp\etc\shibboleth\
    RedHat or Ubuntu distribution of Linux /etc/shibboleth/
    Mac OSX Server and other distributions of Unix /opt/shibboleth-sp/etc/shibboleth/
  4. Copy all configuration files into your shibboleth configuration directory.
  5. By default, most common affiliates attributes are already mapped to HTTP header variables for you. Verify the mappings in attribute-map.xml file and modify it to limit the scope of attributes being fetched. Make note of any missing attributes you may need. Please refer to the page located at https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute for more information.
  6. Finally, restart your Shibboleth service.

Server Configuration: Apache

  1. Tell apache to use shibboleth.
    1. In apache's httpd.conf file reference the file generated by the Shibboleth SP install. For example:
      # Shibboleth
      Include C:\opt\shibboleth-sp\etc\shibboleth\apache22.config
      
    2. At the end of the apache22.config file, adjust the secured Location element.
      <Location /[your_secure_directory]>
        AuthType shibboleth
        ShibRequestSetting requireSession 1
        require valid-user
      </Location>
      
    3. Restart both Shibboleth and Apache.
  2. Test Shibboleth & Apache setup. Browse to http://[your_web_server].ucsd.edu/[your_secure_directory].
    • The port should be apache's port (80 / 443) and the secure directory is specified in the Shibboleth2.xml file.
    • You should be redirected to the test idP, which simulates logging in by asking you to pick a pre defined usesr.
    • You will then be returned to Apache, which will return 404.
  3. Integrate Apache & Tomcat. In apache's httpd.conf:
    1. Enable mod proxy with ajp support by uncommenting these lines.
      LoadModule proxy_module modules/mod_proxy.so
      LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
      LoadModule proxy_http_module modules/mod_proxy_http.so
      
    2. Configure mod_proxy to not forward anything intended for the SP:
      ProxyPass /Shibboleth.sso !
      
      This must come before any other mod_proxy statements.
    3. Configure mod_proxy to forward anything else to tomcat.
      ProxyPass / ajp://localhost/
      
    4. Verify that tomcat's server.xml has the ajp connector enabled.
      <Connector port="8009" enableLookups="false" redirectPort="8443" protocol="AJP/1.3"/>
      
    5. Restart Tomcat and Apache.
    6. Browse to http://[your_web_server].ucsd.edu/[your_secure_directory] again. This time you should "login" then be redirected to your web app.

Configuration Alternatives

Both shibboleth2.xml and apache22.config declare which resources should be protected. This can lead to confusion when they are out of sync. It is possible to set one to require shibboleth for all requests and rely exclusively on the other.

  • Apache forward everything to Shibboleth; Shibboleth selectively requires a session.
    <Location />
      AuthType shibboleth
      ShibRequestSetting requireSession 1
      require valid-user
    </Location>
    
    # Ensures handler will be accessible.
    <Location /Shibboleth.sso>
      Satisfy Any
      Allow from all
    </Location>
    
  • Shibboleth requres a session for everything that Apache chose to forward
    <RequestMapper type="Native" authType="shibboleth" requireSession="true" />
    

Currently we've seen how to secure resources and everything else is unsecured. Alternativly we can secure everything and selectivly unsecure resources.

  • Apache version:
    #Require Shibboleth Authentication for everything by default.
    <Location />
      AuthType shibboleth
      ShibRequestSetting requireSession 1
      require valid-user
    </Location>
    
    # Ensures handler will be accessible.
    <Location /Shibboleth.sso>
      Satisfy Any
      Allow from all
    </Location>
    
    # Example of allowing access to a url without shibboleth authentication
    <Location /myApp/unsecureFiles>
      Satisfy Any
      Allow from all
    </Location>
    
  • Shibboleth Version:
    <RequestMap authType="shibboleth" requireSession="true" >
        <Host name="act-lzelus.ad.ucsd.edu">
            <Path name="unsecure" requireSession="false" />
        </Host>
    </RequestMap>