$Id: README,v 1.18 2003/07/15 10:34:21 maxcooper Exp $
$Revision: 1.18 $
$Date: 2003/07/15 10:34:21 $


Security Filter v2.0
======================================
http://securityfilter.sourceforge.net/


What is SecurityFilter?
-----------------------
SecurityFilter is a Java Servlet Filter that mimics container-based security. It
looks just like container-based security to your app, as you can call
request.getRemoteUser(), request.isUserInRole(), and request.getUserPrincipal()
and get valid responses. However, it can be deployed within your web app, so you
do not need to set the realm in the server configuration, or put any classes in
the server classpath. The realm interface for SecurityFilter is proprietary, but
it is very simple (2 methods) and should be easy to implement for your project.
The other main advantage over container-based security is that users can submit
login form without being forced to the login page by the security mechanism.


License Information
-------------------
Securityfilter is available under the SecurityFilter Software License, Version
1.1. This license is derived from and fully compatible with the Apache Software
License. See the LICENSE file for details.

This product includes software developed by the Apache Software Foundation
(http://www.apache.org/).


What's in this package?
-----------------------
Three example apps demonstrate securityfilter in action:

1. securityfilter-example.war - Simple securityfilter app using native
securityfilter realm implementation and FORM authentication.

2. securityfilter-catalina-example.war - Same as securityfilter-example app with
Tomcat (Catalina) realm implementation and realm adapter class.

3. securityfilter-basic.war - Simple securityfilter app using native
securityfilter realm implementation and BASIC authentication.

A securityfilter-blank.war example app is also provided as a skeleton to use to
start a new securityfilter application, or integrate into an existing
application. Source code and JavaDocs are also included. For installation
instructions, see the INSTALL file.


How to use SecurityFilter
-------------------------
To use the SecurityFilter for your application, you need to do these things:

1. Declare the SecurityFilter filter in your web.xml file, and map all requests
to it (with a url pattern like '/*' -- for examples, see web.xml in the example
apps).

2. Create a SecurityRealmInterface implementation (from scratch, or by extending
SimpleSecurityRealmBase). You can also use a Tomcat (Catalina) realm with the
CatalinaRealmAdapter (see securityfilter-catalina-example app for details). If
you create your own realm adapter class, be sure to include a setRealm(Object
realm) method so the filter can properly nest your realms at run time. Only the
first realm specified in the config file (described below) need implement the
SecurityRealmInterface interface -- there are no type restrictions for realms
that will be adapted.

3. Declare your security preferences in WEB-INF/securityfilter-config.xml. The
format for security preferences closely mimics the web.xml standard (so you can
cut and paste if you have been using container-managed security). In addition to
the web.xml syntax, you can also specify a form-default-page to send users to if
they spontaneously issue a login request without being forced there by the
security mechanism. You will also need to specify your realm (or realms, if you
are using a realm adapter or decorator class). Realm properties can be set with
the realm-param tag.

4. Specify either BASIC or FORM authentication scheme in auth-method tag of
securityfilter-config.xml. If you specify the FORM authentication scheme you will
need to specify your form-login-page, form-error-page, and form-default-page.

The example apps include web.xml and securityfilter-config.xml file examples.


Future Direction / Current Issues
---------------------------------
SecurityFilter is ready for use and should support everything needed for many
apps. Compliance with the servlet 2.3 spec is a top priority for the project,
but it is not 100% compliant yet. There are a few things that are not yet
supported that may be important to you:

1. user-data-constraint tags can be included in the config file, but they are
not yet supported (and thus are ignored)

The following extended features are planned for a future release, but are not
yet available in current releases:

1. "Remember me" functionality -- a persistent cookie will be used to provide
persistent login functionality. Currently, a user will be logged out when their
session expires or if they close their current browser session. By using a
persistent cookie, a user will be automatically authenticated when they return
to a site, even if their session expired or if they close their browser in between
accesses.

2. Application-specific processing at authentication time -- this will allow
application developers to write code that will be executed when a user is
authenticated. This is useful for populating the session with user profile
informtaiton, etc.


Contributors
------------
1. Max Cooper maintains the project and wrote most of the code.

2. Torgeir Veimo contributed the initial version of the Digester-based
securityfilter-config.xml reader and improved the supporting data structures.

3. Daya Sharma implemented the BASIC authentication feature.

4. The members of the securityfilter-user email list have provided bug
reports, code patches, user support and feature suggestions for the
SecurityFilter project.

5. The Apache Jakarta Struts project directory structure and build files were
used as a model for this project, and the struts-user email list members have
provided useful feedback and motivation for the project.

6. Prakash Malani and Steve Ditlinger provided initial feedback and/or helped
with the Ant build files.


Feedback
--------
Let us know what your priorities are, and if there is anything else you would
like to see. Please use the SourceForge facilities to seek support, report bugs,
and make feature requests: http://sourceforge.net/projects/securityfilter/


Thank you,
The SecurityFilter Team
