Note

This documentation is for the new OMERO 5.1. version. See the latest OMERO 5.0.x version or the previous versions page to find documentation for the OMERO version you are using if you have not upgraded yet.

OMERO sessions

Beginning with OMERO-3.0-Beta3, the OMERO server has unified the handling of login sessions among both the JBoss and the OMERO.blitz servers. Previously JBoss logins were handled via the standard JAAS mechanisms, using a modified DatabaseLoginModule. This proved problematic for several reasons:

1. Exceptions thrown during login could not easily be caught or specified.
2. Passwords were sent in the clear on every invocation.
3. Sql queries on every invocation caused significant overhead.

Blitz did not suffer from these problems, but the login functionality was largely outside of the core server code and sessions were more volatile: a loss of an Ice connection caused all resources to be lost. With OMERO sessions, both login systems have been brought together and simplified.

In short:

• Sessions are a replacement for the standard JavaEE security infrastructure.
• Sessions unify the Blitz and RMI session handling, making working with Java RMI more like Blitz (since the JavaEE interaction is essentially “conversationless”).
• Sessions provide the ability (especially in Blitz) to quit a session and rejoin it later as long as it has not timed out, possibly useful for moving from one machine to another.
• Sessions provide the ability to share the same space. Two users/clients attached to the same session would experience the same life-cycle.
• Sessions provide a scratch space to which any data can be written for and by job/script executions.
• Sessions act as a global cache (in memory or on disk) to speed up various server tasks, including login. With further extensions like http://terracotta.org/, sessions could serve as a “distributed” cache.
• Sessions prevent sending passwords in plain text or any other form. After that, all session interactions take place via a shared secret key.

Design

All services other than ISession, assume that a user is logging in with a username equal to session uuid. Whereas previously one logged in with:

ome.system.Principal p = new ome.system.Principal("josh","user","User");

behind the scenes, now the “josh” value is replaced by the UUID of a ome.model.meta.Session instance.

The session is acquired by a call to:

ome.api.ISession.createSession(Principal princpal, String credentials);

and carries information related to the current user’s session.

Session session;
session.getUuid();       // Unique identifier; functions as a temporary password. DO NOT SHARE IT.
session.getTimeToIdle(); // Number of milliseconds which the user can idle without session timeout
session.getTimeToLive(); // Total number of milliseconds for which the session can live
session.getStarted();    // Start of session
session.getClosed();     // if != null, then session is closed

These properties cannot be modified.

Other properties are for use by clients:

session.getMessage();            // General purpose message statement
session.getAgent();              // Can be used to specify which program the user is using
session.getDefaultEventType();   // Default event type (the third argument "User" to Principal above)
session.getDefaultPermissions(); // String representation of umask (e.g. "rw----")

After changing a property on the session returned by createSession() it is possible to save them to the server via:

ome.api.ISession.updateSession(Session);

Finally, when finished, to conserve resources it is possible to destroy the session via:

ome.api.ISession.closeSession(Session);

Existing sessions

In OMERO.blitz, once the connection to a ServiceFactoryPrx (a Glacier2.Session subclass) was lost, it was not possible to reconnect to any of the services created using that connection. Now it is possible to reacquire the session if it is still active, by passing the previous session UUID as your password (User principal is ignored).

client = omero.client()
servicefactory = client.createSession()
iadmin = servicefactory.getAdminService()
olduuid = iadmin.getEventContext().sessionUuid

// lose connection

client = omero.client()
servicefactory = client.createSession(omero.sys.Principal(), olduuid)
// now reattached

Backwards compatibility

In the short-term, there is no need for any change to client code to make use of the new sessions.

ome.system.ServiceFactory has been modified to automatically acquire a session before the first service call is made. Eventually, clients will want to make use of the session API and catch session exceptions to have a finer control of the client lifecycle.

Similarly, no changes are needed in OMERO.blitz client code since Glacier2 sessions now delegate to OMERO sessions. Clients can access the ISession service when necessary. Exceptions thrown are still Ice-based.

See also

Server security and firewalls