org.jsecurity.session
Interface SessionFactory

All Known Subinterfaces:

SecurityManager

All Known Implementing Classes:

AuthenticatingSecurityManager, AuthorizingSecurityManager, CachingSecurityManager, DefaultSecurityManager, DefaultWebSecurityManager, RealmSecurityManager, SessionsSecurityManager

public interface SessionFactory

A SessionFactory is responsible for starting new Sessions and acquiring existing Sessions.

Since:

0.1

Author:

Les Hazlewood

Method Summary

Session	getSession(Serializable sessionId) Acquires a handle to the session identified by the specified sessionId.
Session	start(InetAddress hostAddress) Starts a new session within the system for the host with the specified originating IP address.

Method Detail

start

Session start(InetAddress hostAddress)
              throws HostUnauthorizedException,
                     IllegalArgumentException

Starts a new session within the system for the host with the specified originating IP address.

An implementation of this interface may be configured to allow a null argument, thereby indicating the originating IP is either unknown or has been explicitly omitted by the caller. However, if the implementation is configured to require a valid hostAddress and the argument is null, an IllegalArgumentException will be thrown.

In web-based systems, this InetAddress can be inferred from the javax.servlet.ServletRequest.getRemoteAddr() method, or in socket-based systems, it can be obtained via inspecting the socket initiator's host IP.

Most secure environments should require that a valid, non-null hostAddress be specified, since knowing the hostAddress allows for more flexibility when securing a system: by requiring an InetAddress, access control policies can also ensure access is restricted to specific client locations in addition to user principals, if so desired.

Caveat - if clients to your system are on a public network (as would be the case for a public web site), odds are high the clients can be behind a NAT (Network Address Translation) router or HTTP proxy server. If so, all clients accessing your system behind that router or proxy will have the same originating IP address. If your system is configured to allow only one session per IP, then the next request from a different NAT or proxy client will fail and access will be deny for that client. Just be aware that ip-based security policies are best utilized in LAN or private WAN environments when you can be ensure clients will not share IPs or be behind such NAT routers or proxy servers.

Parameters:

hostAddress - the originating host InetAddress of the external party (user, 3rd party product, etc) that is attempting to interact with the system.

Returns:

a handle to the newly created session.

Throws:

HostUnauthorizedException - if the system access control policy restricts access based on client location/IP and the specified hostAddress hasn't been enabled.

IllegalArgumentException - if the system is configured to require a valid, non-null argument and the specified hostAddress is null.

getSession

Session getSession(Serializable sessionId)
                   throws InvalidSessionException,
                          AuthorizationException

Acquires a handle to the session identified by the specified sessionId.

Although simple, this method finally enables behavior absent in Java for years:

the ability to participate in a server-side session across clients of different mediums, such as web appliations, Java applets, standalone C# clients over XMLRPC and/or SOAP, and many others. This is a huge benefit in heterogeneous enterprise applications.

To maintain session integrity across client mediums, the sessionId must be transmitted to all client mediums securely (e.g. over SSL) to prevent man-in-the-middle attacks. This is nothing new - all web applications are susceptible to the same problem when transmitting Cookies or when using URL rewriting. As long as the sessionId is transmitted securely, session integrity can be maintained.

Parameters:

sessionId - the id of the session to acquire.

Returns:

a handle to the session identified by sessionId

Throws:

InvalidSessionException - if the session identified by sessionId has been stopped, expired, or doesn't exist.

AuthorizationException - if the executor of this method is not allowed to acquire (i.e. join) the session identified by sessionId. The reason for the exception is implementation specific and could be for any number of reasons. A common reason in many systems would be if one host tried to acquire/join a session that originated on an entirely different host (although it is not a JSecurity requirement this scenario is disallowed - its just an example that may throw an Exception in many systems).

See Also:

HostUnauthorizedException