Configuring the Shibboleth Shim Servlet Filter

Each application using Shibboleth must be listed in the federation metadata, but not using its own URL. If the Shibboleth Shim server is running on

    https://serverhost.example.edu/shibshim/ACS

and the application context is at

    https://myapp.example.edu/myapp

then the application name so far as Shibboleth is concerned is

    https://serverhost.example.edu/shibshim/ACS/https/myapp.example.edu/myapp

In this fashion separate Attribute Release Policies (ARPs) and WAYF sites can be configured for each application.

The application implementer customizes the ShibShimFilter class using a properties file specified in the web.xml file for the application. See the Configuration section for a list of parameters and attributes.

A sample web.xml file might look like the following:

    <!DOCTYPE web-app 
        PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
        "http://java.sun.com/dtd/web-app_2_3.dtd">

    <web-app>
        <!-- Register the name "ShibShimFilter" for ShibShimFilter. -->
        <filter>
            <filter-name>ShibShimFilter</filter-name>
            <filter-class>org.kathrynhuxtable.middleware.shibshim.filter.ShibShimFilter</filter-class>
            <init-param>
                <param-name>ShibShimFilterPropertiesFile</param-name>
                <param-value>/shibshimfilter.properties</param-value>
            </init-param>
        </filter>

        <!-- Apply ShibShimFilter to local ACS -->
        <filter-mapping>
            <filter-name>ShibShimFilter</filter-name>
            <url-pattern>/localACS</url-pattern>
        </filter-mapping>

        <!-- Apply ShibShimFilter to non-images. -->
        <filter-mapping>
            <filter-name>ShibShimFilter</filter-name>
            <url-pattern>*.html</url-pattern>
        </filter-mapping>
        <filter-mapping>
            <filter-name>ShibShimFilter</filter-name>
            <url-pattern>*.jsp</url-pattern>
        </filter-mapping>
        <filter-mapping>
            <filter-name>ShibShimFilter</filter-name>
            <url-pattern>/myservlet</url-pattern>
        </filter-mapping>

        <!-- Define servlet and URL mapping -->
        <servlet>
            <servlet-name>MyServlet</servlet-name>
            <servlet-class>mypackage.myservlet</servlet-class>
        </servlet>
        <servlet-mapping>
            <servlet-name>MyServlet</servlet-name>
            <url-pattern>/myservlet</url-pattern>
        </servlet-mapping>
    </web-app>

When a user is logged in, the mapped user attributes will be delivered as HTTP headers. Headers ignore case.

Configuration

You must specify a properties file in the web.xml in the filter section as above, using the ShibShimFilterPropertiesFile param. You may specify a URL or you may specify a file relative to the class path. The example above would be satisfied by a file in the WEB-INF/classes directory.

The properties file contains data used to configure the application.

A sample properties file follows:

acsUrl=https://cmidtst.cc.ku.edu/shibshim/ACS
certFile=/shibshimcert.crt
localAcsPath=/localACS
sessionAttribute=org.kathrynhuxtable.middleware.shibshim.userAttributes

attributeMap.shib-ep-affiliation=shib-affiliation
attributeMap.shib-ep-edupersonprincipalname=shib-edupersonprincipalname
attributeMap.shib-ep-entitlement=shib-edupersonentitlement
attributeMap.shib-inetorgperson-displayname=shib-displayname
attributeMap.shib-inetorgperson-mail=shib-mail
attributeMap.shib-targetedid=shib-targetedid

remoteUserAttribute=shib-edupersonprincipalname

Required properties

acsUrl

The URL of the Shibboleth Shim Server Assertion Consumer Service.

attributeMap.*

A list of properties mapping incoming Shibboleth attribute names to the internal names that will be delivered as HTTP headers and stored in the session attribute. Only attributes listed here will be delivered. Others will be ignored.

certFile

The file containing the public certificate for the key that the Shibboleth Shim server uses to sign assertions.

localAcsPath

The path for the Shibboleth Shim Filter Assertion Consumer Service.

sessionAttribute

The name for the session object containing the attributes. It is suggested that package-style naming be used to avoid potential conflicts with the protected application, e.g.

org.kathrynhuxtable.middleware.shibshim.userAttributes

The object will be of the type org.kathrynhuxtable.middleware.shibshim.filter.UserAttributes.

Optional properties

application

The name of the Shibboleth application being protected.

It defaults to https://host/context (or https://host:port/context if the port is not 443). This is usually the desired value.

loginRedirectPath

An optional path in the context which will check login status.

The default value is null, which is only useful with the default true value of sessionRequired.

If this is set and the path is protected by the filter, the path will be intercepted by the filter and the browser will be redirected to the login page.

If the target query parameter is specified, that will be treated as a return URL. Otherwise the default page for the context will be used.

remoteUserAttribute

The name of the principal attribute that will be returned as the remote user.

The default value is null, which does not deliver any attributes to remote user, but which will pass through any remote user from the servlet container.

If this property is specified and the attribute is not returned to this application, then the remote user will be null.

sessionRequired

Set to false if the application does not require a session initially.

The default is true, meaning that the user will be prompted to log in if not already logged into Argus.

If false, then the filter returns session information if logged in. The application is responsible for forcing a session to be established if one is needed.