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).
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 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.
Security of a cookie
Cookies can be configured in different ways to be secure. For further information visit OXSessionSecurityFeatures
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 validity of the session after the authentication:
- The browser sends initial request to the Open-Xchange server. The client represented by the application:
- is not authenticated yet
- has no cookie
- has no session ID.
- Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
- The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see OXSessionAutologin. With the precondition form 1. the auto-login try will be denied.
- The user enters username and password in the front-end.
- The 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.
- The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
- Session ID via JSON object
- (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
- Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
- Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
- Cookie containing the public identifier.
- The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
- If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
- The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
- The Open-Xchange server processes this data request and compares:
- Session ID for validity in sessiond
- Session-Secret from the cookie for validity with session
- The request is correctly authenticated and is answered by the server.
- (Optional) Random token is discarded after timeout from sessiond.
- Repeat 9. - 11. until end of session
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
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.
- External tool sends initial JSON request directly to Open-Xchange Server
- not authenticated yet
- no cookie
- no SessionID
- 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)
- SessionID in JSON object
- Random token for initial login via JSON object (required for SSO login)
- Cookie with Session-Secret is not set
- External tool starts browser with special URL, that contains at least following data:
- Random token for initial login
- Open-Xchange Server compares:
- Random token for validity in sessiond
- Open-Xchange Server sends to the browser:
- SessionID in JSON object
- Cookie with JSESSIONID for loadbalancing is set to the browser
- The second part of the tokens is delivered in a separate request
- 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
- 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.
Token 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. See OXSessionFormLogin for details.
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.
Authentication against other services
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: