Shibbolizing An Application

In this guide, we will write a Java Server Page (JSP) application that will be protected by Shibboleth. The JSP is a simply "reflector" that will echo back attributes that was sent over by the Shibboleth IdP. This is to demonstrate how an actual application that is to be shibbolized can be modified in the same way. The attributes that it obtains via Shibboleth, can then be used by the application for AuthZ^? decisions.

Prerequisites

• You have installed on an IdP following the instructions here.
• You have installed a Shibboleth Service Provider following the instructions here. This is the machine where we will deploy our JSP application.
• Java 1.5.x with JAVA_HOME environment set up to point to this location.

Install Tomcat 5

• Download Tomcat 5
  • Tomcat 5.0.28: jakarta-tomcat-5.0.28.tar.gz
• Unpack the above package into /usr/local and setup the variable TOMCAT_HOME to point to the top level of tomcat.

  • $tar xzvf jakarta-tomcat-5.0.28.tar.gz

  • $mv jakarta-tomcat-5.0.28 /usr/local/.

  • ln -s /usr/local/jakarta-tomcat-5.0.28 /usr/local/tomcat

  • $export TOMCAT_HOME=/usr/local/tomcat

Configuring Tomcat JK2 Connector

• Install the JK2 connector for Apache 2

  • $apt-get install libapache2-mod-jk2

• Create a file called, jk2.load, in the directory /etc/apache2/mods-available, with the following content:

  • LoadModule jk2_module /usr/lib/apache2/modules/mod_jk2.so

• Create the configuration file for jk2 called jk2.conf also in the same directory, /etc/apache2/mods-available, with the following content:

  • JkSet config.file /etc/apache2/workers2.properties

• Make the symbolic links to enable the jk2 module in Apache 2:

  • $ln -s /etc/apache2/mods-available/jk2.load /etc/apache2/mods-enabled/.

  • $ln -s /etc/apache2/mods-enabled/jk2.conf /etc/apache2/mods-enabled/.

• Create a new workers2.properties file in /etc/apache2 directory with the following:

      [logger]
      info=Native logger
      level=ERROR

      [config:]
      file=/etc/apache2/workers2.properties
      debug=0
      debugEnv=0

      [uriMap:]
      info=Maps the requests.
      debug=0

      [shm:]
      info=Scoreboard. Required for reconfiguration and status with multiprocess servers
      file=anonymous
      debug=0

      [workerEnv:]
      info=Global server options
      timing=0
      debug=0

      [lb:lb]
      info=Default load balancer.
      debug=0

      [channel.socket:localhost:8009]
      info=Ajp13 forwarding over socket
      debug=0
      tomcatId=localhost:8009

      #define the worker
      [ajp13:localhost:8009]
      channel=channel.socket:localhost:8009


      [uri:/jsp-examples/*]
      info=JSP 2.0 Examples.
      debug=0

      [uri:/servlets-examples/*]
      info=Servlet 2.4 Examples.
      debug=0

• Start up Tomcat 5:

  • $$TOMCAT_HOME/bin/startup.sh

• Go to $TOMCAT_HOME/conf and edit the server.xml file. Make sure that the following block is added or uncommented:

        <Connector port="8009" address="127.0.0.1" request.tomcatAuthentication="false"
            enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />

• Make sure that any Coyote Connector defined for port 8009 is commented out
• Stop and restart Tomcat 5 and Apache 2 by executing the scripts:

  • $$TOMCAT_HOME/bin/shutdown.sh

  • $$TOMCAT_HOME/bin/startup.sh

  • $/etc/init.d/apache 2 restart

• Test that the Tomcat connector is working by pointing your browser to "https://MY_DNS/jsp-examples/index.html". You should see a page where you can try out all the JSP examples that came with Tomcat 5.

Deploy Demo JSP application

• Download the attached demo.jsp.txt file, rename it to "demo.jsp" and place it in "$TOMCAT_HOME/webapps/jsp-examples" directory

  • $mv demo.jsp.txt $TOMCAT_HOME/webapps/jsp-examples/demo.jsp

• The JSP application reflects attributes and values passed via Shibboleth, and has three service levels:
  • Bronze service requires release of “eduPersonAffiliation” attribute only.
  • Silver service requires release of “eduPersonAffiliation” and “eduPersonNickname” attributes.
  • Gold service requires release of “eduPersonAffiliation”, “eduPersonNickname” and “sn” attributes.

• The relevant part of the code in the JSP page where it retrieves the value from the HTTP RequestHeaders^? is:

         String surname = request.getHeader("Shib-Person-surname");
         String affiliation = request.getHeader("Shib-EP-UnscopedAffiliation");
         String nickname = request.getHeader("Shib-EP-Nickname");

• To understand how the values are set in the header, please consult the Resolver, ARP, AAP guides.

Protect the JSP Application with Shibboleth

• Edit the default virtual host, "/etc/apache2/sites-available/default" file. Just before the closing VirtualHost^? element, add the following block:

        <Location /jsp-examples/demo.jsp>
                AuthType shibboleth
                ShibRequireSession On
                require valid-user
        </Location>

• Test your newly installed Shibboleth SP application by opening a browser from you local computer and point it to the URL "http://MY_DNS/jsp-examples/demo.jsp". When redirected to the WAYF, select your IdP, log in with your credentials and you should then see the reflector page indicating the attributes being sent from the IdP to the SP and then onto your application.

-- ChiNguyen - 19 Feb 2006
to top