edu.ku.middleware.argus.resource
Class ArgusFilter

java.lang.Object
  edu.ku.middleware.argus.resource.ArgusFilter

All Implemented Interfaces:

javax.servlet.Filter

public final class ArgusFilter

extends java.lang.Object

implements javax.servlet.Filter

The ArgusFilter class provides authentication service using KU's Argus login protocol. See http://www.aims.ku.edu/argus for more information.

If the Filter decides that the request requires an Argus Session (attributes), then it redirects the Browser to the Argus login page, having made up a session ID (called a cache ID in Argus terminology).

When the Browser returns, the Filter fetches the attributes and stores them in the Java Servlet Session object.

For this and subsequent requests, the Filter wraps the Request object in a wrapper class that creates HTTP headers based on the Argus Session.

Also Note: This version of the filter may be loaded from a library that is shared across all applications on a Web Server. In Tomcat, the JAR file could be placed in {tomcat}/shared/lib. Or it could be placed in a lib directory only accessible by one application, e.g. in that application's WEB-INF/lib directory.

Each application using Argus must be registered with the Argus administrator. The implementers must state what information is needed for each user. If this involves the use of personal or student data, it must be approved by the data custodians.

Each application must also have an SSL certificate to use to identify itself to the login server. If all the users on a web server are in the same unit and can share information, the server's own cert can be used, if accessible, but if a group of independent users share a server, each application may need its own SSL cert. In this case, certs signed by the Argus certificate authority can be issued.

All pages using Argus must use SSL.

The application implementer customizes the ArgusFilter class using filter-param values specified in the web.xml file for the application. See the Field Detail for a list of parameters.

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 "ArgusFilter" for ArgusFilter. -->
     <filter>
         <filter-name>ArgusFilter</filter-name>
         <filter-class>edu.ku.middleware.argus.resource.ArgusFilter</filter-class>
         <init-param>
             <param-name>logoutRedirectPath</param-name>
             <param-value>/ArgusLogout</param-value>
         </init-param>
     </filter>

     <!-- Apply ArgusFilter to Argus logout -->
     <filter-mapping>
         <filter-name>ArgusFilter</filter-name>
         <url-pattern>/ArgusLogout</url-pattern>
     </filter-mapping>

     <!-- Apply ArgusFilter to non-images. -->
     <filter-mapping>
         <filter-name>ArgusFilter</filter-name>
         <url-pattern>*.html</url-pattern>
     </filter-mapping>
     <filter-mapping>
         <filter-name>ArgusFilter</filter-name>
         <url-pattern>*.jsp</url-pattern>
     </filter-mapping>
     <filter-mapping>
         <filter-name>ArgusFilter</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 registered user attributes will be delivered as HTTP headers with "argus-" at the beginning, e.g. the header for the kuPersonAffiliation attribute would be argus-kupersonaffiliation. Headers ignore case.

In addition, a few configuration parameters from the filter are passed as HTTP headers with "argus-config-" at the beginning. These are:

config-application

A String containing the Argus application name

config-currenttime

A String containing the current date and time.

config-lasttime

A String containing date and time page was last loaded in this session.

config-sessionid

A String containing the session ID identifying the session in this application. This will be the JSESSIONID cookie value for your Java session.

config-sessiontime

A String containing date and time user last entered authentication credentials.

config-verifytime

A String containing date and time user was last verified against the login server.

Author:

Kathryn Huxtable <khuxtable@ku.edu>, Ashwin Pulijala <ashwin@ku.edu>

Nested Class Summary

(package private) static class	ArgusFilter.PrincipalAttributes
(package private) static class	ArgusFilter.UserInfoException
(package private) class	ArgusFilter.Wrapper

Field Summary

protected java.lang.String	application A String containing the name of the Argus application being protected.
protected java.lang.String	attributeURL A String value specifying the URL of the Argus attribute server.
protected java.lang.String	keypass A String containing the password for the private key in the keystore file.
protected java.lang.String	keystoreFile A String containing the name of the file with the X509 certificate and private key with which to authenticate to Argus.
protected java.lang.String	keystorePass A String containing the password for the keystore file.
protected java.lang.String	keystoreType A String containing the type of the keystore file.
protected java.lang.String	loginRedirectPath A String indicating a path in the context which will check login status.
protected java.lang.String	loginURL A String value specifying the URL of the Argus login page.
protected java.lang.String	logoutRedirectPath A String indicating a path in the context which will force a logout.
protected java.lang.String	remoteUserAttribute A String containing the name of the principal attribute that will be returned as the remote user.
protected boolean	requireSession A boolean value indicating whether the application requires login.
protected java.lang.String	sessionAttribute A String containing the name of the session object containing the attributes.
protected java.lang.String	sslProtocol A String containing the SSL protocol.
protected long	timeout A long value, giving the verification timeout (in seconds).
protected java.lang.String	x509algorithm A String containing the X509 algorithm.

Constructor Summary

ArgusFilter()

Method Summary

void	destroy() Overrides the destroy method from filter.
void	doFilter(javax.servlet.ServletRequest req, javax.servlet.ServletResponse res, javax.servlet.FilterChain chain) Filters requests to make sure user is logged in.
protected void	generalArgusRedirect(javax.servlet.http.HttpServletResponse response, java.lang.String url) Redirects browser to Argus.
protected java.lang.String	hex_encode(java.lang.String str) Hex encodes string in little-endian order.
void	init(javax.servlet.FilterConfig config) Saves the config object.
protected void	redirectToError(javax.servlet.http.HttpServletResponse response, java.lang.String error) Returns an error page with a message describing the error.
protected void	redirectToForceLogin(javax.servlet.http.HttpServletResponse response, java.lang.String sessionId, java.lang.String returnURL) Redirects browser to standard login page and force login.
protected void	redirectToLogin(javax.servlet.http.HttpServletResponse response, java.lang.String sessionId, java.lang.String returnURL) Redirects browser to standard login page.
protected void	redirectToLogout(javax.servlet.http.HttpServletResponse response, java.lang.String returnURL) Redirects browser to standard logout page.
protected java.lang.String[]	retrieveUserInfo(java.lang.String sessionId) Retrieves user authentication and indentification information from the Argus authentication system based on session ID.
protected javax.net.ssl.SSLSocketFactory	setupFactory() Sets up a key manager for client authentication.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

application

protected java.lang.String application

A String containing the name of the Argus application being protected.

Set by <init-param>application</init-param> in the WEB-INF/web.xml file for the context.

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

requireSession

protected boolean requireSession

A boolean value indicating whether the application requires login. Set by <init-param>requireSession</init-param> in the WEB-INF/web.xml file for the context.

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.

timeout

protected long timeout

A long value, giving the verification timeout (in seconds).

Set by <init-param>timeout</init-param> in the WEB-INF/web.xml file for the context.

The default value is 60 seconds.

This is the amount of time between checks for Argus login server session validity. Since Argus doesn't force logouts on all the applications using it, this is the amount of time that a session may still be considered valid after the user logs out of a different application.

loginURL

protected java.lang.String loginURL

A String value specifying the URL of the Argus login page.

Set by <init-param>loginURL</init-param> in the WEB-INF/web.xml file for the context.

The default value is the production location.

attributeURL

protected java.lang.String attributeURL

A String value specifying the URL of the Argus attribute server.

Set by <init-param>attributeURL</init-param> in the WEB-INF/web.xml file for the context.

The default value is the production location.

loginRedirectPath

protected java.lang.String loginRedirectPath

A String indicating a path in the context which will check login status.

Set by <init-param>loginRedirectPath</init-param> in the WEB-INF/web.xml file for the context.

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

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.

If the force query parameter is specified and is true, then a login prompt will be forced. The default is to accept an existing Argus login.

logoutRedirectPath

protected java.lang.String logoutRedirectPath

A String indicating a path in the context which will force a logout.

Set by <init-param>logoutRedirectPath</init-param> in the WEB-INF/web.xml file for the context.

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

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 logout page.

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

sessionAttribute

protected java.lang.String sessionAttribute

A String containing the name of the session object containing the attributes.

Set by <init-param>sessionAttribute</init-param> in the WEB-INF/web.xml file for the context.

The default value is edu.ku.middleware.argus.principalAttributes.

remoteUserAttribute

protected java.lang.String remoteUserAttribute

A String containing the name of the principal attribute that will be returned as the remote user.

Set by <init-param>remoteUserAttribute</init-param> in the WEB-INF/web.xml file for the context.

The default value is argus-uid, which contains the KU Online ID for the user.

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

keystoreFile

protected java.lang.String keystoreFile

A String containing the name of the file with the X509 certificate and private key with which to authenticate to Argus.

Set by <init-param>keystoreFile</init-param> in the WEB-INF/web.xml file for the context.

The default value is conf/argus.jks, which is relative to the tomcat root.

keystorePass

protected java.lang.String keystorePass

A String containing the password for the keystore file.

Set by <init-param>keystorePass</init-param> in the WEB-INF/web.xml file for the context.

The default value is changeit.

keypass

protected java.lang.String keypass

A String containing the password for the private key in the keystore file.

Set by <init-param>keypass</init-param> in the WEB-INF/web.xml file for the context.

The default value is the keystorePass value.

keystoreType

protected java.lang.String keystoreType

A String containing the type of the keystore file.

Set by <init-param>keystoreType</init-param> in the WEB-INF/web.xml file for the context.

The default value is JKS.

The values supported are JKS and PKCS12.

sslProtocol

protected java.lang.String sslProtocol

A String containing the SSL protocol.

Set by <init-param>sslProtocol</init-param> in the WEB-INF/web.xml file for the context.

The default value is TLS.

x509algorithm

protected java.lang.String x509algorithm

A String containing the X509 algorithm.

Set by <init-param>x509algorithm</init-param> in the WEB-INF/web.xml file for the context.

The default value is SunX509.

Constructor Detail

ArgusFilter

public ArgusFilter()

Method Detail

init

public void init(javax.servlet.FilterConfig config)
          throws javax.servlet.ServletException

Saves the config object. Initializes any private attributes from init-param values.

Specified by:

init in interface javax.servlet.Filter

Parameters:

config - the configuration object for this filter.

Throws:

javax.servlet.ServletException

destroy

public void destroy()

Overrides the destroy method from filter.

Specified by:

destroy in interface javax.servlet.Filter

doFilter

public void doFilter(javax.servlet.ServletRequest req,
                     javax.servlet.ServletResponse res,
                     javax.servlet.FilterChain chain)
              throws java.io.IOException,
                     javax.servlet.ServletException

Filters requests to make sure user is logged in. If not, redirects to standard login page. If logged in, fills in some principal attributes that can be used by the filtered servlet.

Note: The Filter will throw a Servlet Exception only in one catastrophic case, where it is not running in a Web Server?!? It doesn't generate other exceptions, but will pass on exceptions generated by other Filters or the Servlet farther down the chain.

Specified by:

doFilter in interface javax.servlet.Filter

Parameters:

req - the servlet request object.

res - the servlet response object.

chain - the chain of servlets to run if we are logged in.

Throws:

java.io.IOException

javax.servlet.ServletException

redirectToLogin

protected void redirectToLogin(javax.servlet.http.HttpServletResponse response,
                               java.lang.String sessionId,
                               java.lang.String returnURL)

Redirects browser to standard login page.

Parameters:

response - the servlet response object. Used to do the redirect.

sessionId - the session ID to invalidate on logout.

returnURL - the URL to redirect to after login/out.

redirectToForceLogin

protected void redirectToForceLogin(javax.servlet.http.HttpServletResponse response,
                                    java.lang.String sessionId,
                                    java.lang.String returnURL)

Redirects browser to standard login page and force login.

Parameters:

response - the servlet response object. Used to do the redirect.

sessionId - the session ID to invalidate on logout.

returnURL - the URL to redirect to after login/out.

redirectToLogout

protected void redirectToLogout(javax.servlet.http.HttpServletResponse response,
                                java.lang.String returnURL)

Redirects browser to standard logout page.

Parameters:

response - the servlet response object. Used to do the redirect.

returnURL - the URL to redirect to after login/out.

redirectToError

protected void redirectToError(javax.servlet.http.HttpServletResponse response,
                               java.lang.String error)

Returns an error page with a message describing the error.

Parameters:

response - the response object. Used to redirect to error page.

error - the error message to be displayed.

generalArgusRedirect

protected void generalArgusRedirect(javax.servlet.http.HttpServletResponse response,
                                    java.lang.String url)

Redirects browser to Argus. Used by the other redirect methods.

Parameters:

response - the servlet response object. Used to do the redirect.

url - the URL to redirect to after login/out.

hex_encode

protected java.lang.String hex_encode(java.lang.String str)

Hex encodes string in little-endian order.

Parameters:

str - the string to encode.

Returns:

a hex encoded string.

retrieveUserInfo

protected java.lang.String[] retrieveUserInfo(java.lang.String sessionId)
                                       throws javax.servlet.ServletException,
                                              ArgusFilter.UserInfoException

Retrieves user authentication and indentification information from the Argus authentication system based on session ID. Uses a client X.509 certificate to verify itself to Argus.

The last time the user presented authentication credentials, and the user attributes are returned as elements of a String array.

Parameters:

sessionId - the session ID string. Used to uniquely identify a session.

Throws:

javax.servlet.ServletException

ArgusFilter.UserInfoException

setupFactory

protected javax.net.ssl.SSLSocketFactory setupFactory()
                                               throws java.io.IOException,
                                                      ArgusFilter.UserInfoException

Sets up a key manager for client authentication. Use the implementation's default TrustStore and secureRandom routines.

Throws:

java.io.IOException

ArgusFilter.UserInfoException