Login variations

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).

System overview/Implementation

Overview

The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate the respective front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

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.

Access to IMAP Back-End services

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.)

Basic Implementation Rules

• It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
• A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
• Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
• To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
• It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
• If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
• In memory data (SessionID) of the browser GUI must never be changed during a valid session
• All relevant information regarding session management must always be written to the relevant logfiles
• The whole mechanism is only secure when being used via encrypted connection
• ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store. 
This means, that the security of the whole system depends on the level of security of the browsers cookie store

Authentication and Session Tokens

Following tokens are used for the session management:

SessionID

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.

Session-Secret

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.

Public Session

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).

Random

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.

Cookie Handling

In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

Only one cookie per client session type

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.

Naming of cookies

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.

Lifetime of cookies

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.

All cookies get deleted when a logout is performed.

IP Check

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.

Access via web browser with user credentials

When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the valid session after the authentication:

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.

1. Browser sends initial request to the Open-Xchange Server
   1. not authenticated yet
   2. no cookie
   3. no SessionID
2. Open-Xchange Server sends AJAX application to browser
it is loaded, no data is exchanged
3. User enters username and password in the front-end
4. Username and password are sent to the server via JSON (SSL)
If the user activated persistent auto-login on the login screen, this information is passed with the same request
5. The server authenticates and sends following data back to the browser via JSON (the data are all saved in the session object in sessiond)
   1. SessionID in JSON object
   2. Random token for initial login via JSON object
(required for SSO login)
   3. Cookie with JSESSIONID for loadbalancing is set to the browser
6. The second part of the tokens is delivered in a separate request
   1. Cookie with Session-Secret is set to the browser
If persistent auto-login is selected, the cookie is configured with the relevant type and validity
7. AJAX front-end saves the SessionID in memory
AJAX front-end ignores random token
8. AJAX sends initial data request via JSON to the Open-Xchange Server and provides following data:
   1. SessionID in JSON object
   2. Open-Xchange Server processes this data request and requests from browser the cookie with Session-Secret
9. Open-Xchange Server compares:
   1. SessionID for validity in sessiond
   2. Session-Secret from Cookie for validity with sessiond
10. Request is correctly authenticated and is answered
11. Random token is discarded after timeout from sessiond
12. If persistent auto-login is selected
    1. Cookie with SessionID is set to the browser
The cookie is configured with the relevant type and validity
13. Repeat 7. - 10. until end of session

Access via web browser after authentication with external system

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.

1. External tool sends initial JSON request directly to Open-Xchange Server
   1. not authenticated yet
   2. no cookie
   3. no SessionID
2. The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
   1. SessionID in JSON object
   2. Random token for initial login via JSON object
(required for SSO login)
   3. Cookie with Session-Secret is not set
3. External tool starts browser with special URL, that contains at least following data:
   1. Random token for initial login
4. Open-Xchange Server compares:
   1. Random token for validity in sessiond
5. Open-Xchange Server sends to the browser:
   1. SessionID in JSON object
   2. Cookie with JSESSIONID for loadbalancing is set to the browser
6. The second part of the tokens is delivered in a separate request
   1. Cookie with Session-Secret is set to the browser
If persistent auto-login is selected, the cookie is configured with the relevant type and validity
7. Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

Tokens Login

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.

Form Login

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.

Redeem Token Login

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.

Implementation Details

The following sections define in detail the required requests and data types for connecting an external system.

Authentication via JSON interface

Authenticating via JSON interface corresponds to a simple HTTP/S request: GET/POST https://<open-xchange.server>/ajax/login?action=login Following parameters are exchanged:

• action – provides the login value
• name – the username
• password – the password

This request can deliver following return values:

• 200 OK – Authentication successful
The body of the reply contains a JavaScript object in JSON format. This object contains the attributes session and random. The session attribute contains a valid SessionID, while the random attribute contains a random value that only allows to process one single request.
• 200 OK – Authentication failed
The body of the reply again contains a JavaScript object in JSON format. But in this case the object only contains the attribute error. The error attribute informs about the reason for the authentication failure. Currently, this attribute returns “Invalid credentials” or “User not found”. Values like “Your account is disabled” are also possible though.

Example Authentication

 Connected to localhost.
 Escape character is '^]'.
 GET /ajax/login?action=login&name=<user>&password=<password> HTTP/1.0
 
 HTTP/1.1 200 OK
 Date: Mon, 04 Sep 2006 11:53:35 GMT
 Server: Apache
 Pragma: no-cache
 Set-Cookie: JSESSIONID=1157370816112.OX1; path=/
 Set-Cookie: open-xchange-session-1157370816100=1157370816100; path=/
 Cache-Control: post-check=0,pre-check=0
 Expires: Sat,6 May 1995 12:00:00 GMT
 Connection: close
 Content-Type: text/javascript; charset=UTF-8
 
 {"lang":"EN","session":"1157370816100","random":"1157370816111","id":32}
 Connection closed by foreign host.

Session data transfer via URL

If the SessionID and the random token are requested from an external application as described above, the browser will be started with following URL to initialize the browser session once, using the random token. When having an OX server cluster the JSESSIONID too has to be passed on, but it is essential to use the JSESSIONID from the cookie with the identical name:

 https://<open-xchange.server>/ajax/login
 ;jsessionid=<sessiond.jvmRoute>?action=redirect
 &random=random-Token>

Example Login with Random

 Connected to localhost.
 Escape character is '^]'.
 GET /ajax/login;jsessionid=1157370816112.OX1?action=redirect&random=1157370816111 HTTP/1.0

 HTTP/1.1 302 Found
 Date: Mon, 04 Sep 2006 11:54:08 GMT
 Server: Apache
 Location: /index.html#id=1157370816100
 Set-Cookie: JSESSIONID=1157370816112.OX1; path=/
 Set-Cookie: open-xchange-session-1157370816100=1157370816100; Path=/
 Content-Length: 0
 Connection: close
 Content-Type: text/javascript; charset=UTF-8
 
 Connection closed by foreign host.

Redirection

When initializing the browser with the random token the cookie is set with Secret and the browser is redirected to load the AJAX GUI. The URL for loading the GUI looks like follows: !https://<open-xchange.server>/index.html#id=<random-Token> The AJAX GUI has to be located under the above mentioned URL.