Introduction: This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).
The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.
(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)
Following tokens are used for the session management:
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated. Multiple clients with same cookie store.
On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.
The cookies are named following this schema:
open-xchange-session-<<name token>>=<<SessionID>> open-xchange-secret-<<name token>>=<<Session-Secret>>
Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down. Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.
Cookies can be configured in different ways to be secure. For further information visit OXSessionSecurityFeatures
All cookies get deleted when a logout is performed.
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process. There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges. For further information on the configuration see configuration properties.
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:
If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.
For any details on the requests and responses please visit the Technical Documentation
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.
The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See OXSessionFormLogin for details.
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session. This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
For further information on the session see OXSessionLifecycle.
For further information on HTTP API visit the Technical Documentation