How To Integrate elmr into Your Service

Using elmr in your Service

Overview

elmr is a small service for container-based services that require Shibboleth authentication, but cannot have Shibboleth running inside their own container. Instead, elmr is part of a composition of services that include Apache and Shibboleth (shibd). Its job is to save and destroy data in an external data store. The data is user session data (Shibboleth attributes) that would otherwise be read in the application.

Session Data Store

elmr tries to connect to an external instance of Redis (see configuration of the serlvet context parameters in README). If the connection attempt fails, elmr falls back to an in-memory store rather than crashing. You will need to set the host name and port in the context.xml file or set the appropriate system properties before starting elmr as described in the README.

elmr does not retrieve data for your application. Your application will have to connect to the Redis store and retrieve it. It will also have to clean up its data (see below).

Configuring Apache to Use Shibboleth and elmr

Make sure you configure Apache to use Shibboleth authentication for /elmr/session and /elmr/config.

A Simple Java Example

Java web applications that are Shibboleth protected are assumed to be fronted by an Apache web server running mod_shib and mod_jk. Shibboleth and Apache are configured so that Shibboleth attributes would be part of the 'environment' of the web server. A request to the AJP-connected web application server (Tomcat in this case) would read Shibboleth attributes in a Servlet as follows:

package my.servlet;

// imports...

@WebServlet("/protected")
class ProtectedServlet extends HttpServlet {

  // serialVersionUID...

  protected doGet(HttpServletRequest req, HttpServletResponse) 
    throws ServletException, IOException {
    
    // UID is an example Shibboleth attribute.
    String uid = (String) req.getAttribute("uid");
    // do useful application stuff
    ...
  }
}

Other platforms and frameworks would have a similar approach to reading these attributes.

elmr at a Glance

The best part about elmr is that you don't have to change your application code directly becuase your platform will have an API for filtering HTTP requests (such as Servlet Filters in the case of Java). You would write one of these filters and execute it before your web application code. The sequence diagram below shows a very high-level interaction with elmr from your web application request filter.

Writing your own Authentication Filter

When writing your own filter to use elmr in your service, you will need to set it up to handle logging in and out.

Logging In

1. Check for the presence of a cookie named __edu.illinois.techservices.elmr.servlets.sessionKey.
2. If not found, set a cookie named __edu.illinois.techservices.elmr.serviceUrl with the original request's URL and redirect to /elmr/session. This will return the cookie named above with a value for your session key and redirect back to your application code with the URL set in the cookie described in this step.
3. If the cookie is found, use the value of it to read data from the session store. When the data is retrieved, you can populate your request as Shibboleth would and then continue to your application code (for example, a Java Servlet Filter would set requeest attributes on the HttpServletRequest before continuing to execute the servlet filter chain).

Reading The Session Data

Your application must read the session data from the session data store (Redis) using a GET command. Then your application should cache the session data value in your appication if you do not expect it to change during the life of your session to save calls back to the session data store.

Logging Out

As part of your logout routine, do the following:

1. Perform your application's logout routine.
2. Redirect to /elmr/session?mode=logout. This will delete the session data in the session data store, delete the __edu.illinois.techservices.elmr.servlets.sessionKey cookie, and delete the __edu.illinois.techservices.elmr.serviceUrl cookie. The request will then be redirected to your SSO's (Shibboleth) logout routine.