Note

This documentation is for OMERO 5.2. This version is now in maintenance mode and will only be updated in the event of critical bugs or security concerns. OMERO 5.3 is expected before the end of 2016.

OMERO sessions

OMERO sessions simplifies the handling of login sessions for OMERO.blitz.

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, 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

See also

Server security and firewalls