Open-Xchange Authentication & Session Handling Table of Contents 1.Introduction...3 2.System overview/implementation...4 2.1.Overview... 4 2.1.1.Access to IMAP back end services...4 2.1.2.Basic Implementation Rules...5 2.2.Authentication and Session Tokens...6 2.2.1.SessionID...6 2.2.2.Session-Secret...6 2.2.3.Random-Token... 6 2.3.Cookie Handling...6 2.3.1.Only one cookie per client session type... 6 2.3.2.Multiple clients with the same cookie store... 7 2.3.3.Naming of cookies... 7 2.3.4.Lifetime of cookies... 7 2.4.IP Check... 7 2.5.Access via web browser with user credentials... 7 2.6.Access via web browser after authentication with an external system...9 3.Implementation Details...11 3.1.Authentication via JSON interface...11 3.1.1.Example Authentication:... 11 3.2.Session data transfer via URL... 12 3.2.1.Example Login with Random... 12 3.2.2.Redirection... 13
Copyright 2010, Open-Xchange GmbH - 2 -
1. Introduction This paper describes Open-Xchange'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). - 3 -
2. System overview/implementation 2.1. Overview The Open-Xchange Server web front end is implemented in JavaScript and uses the AJAX paradigm (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 server. The complete user front end is rendered and displayed in the browser. Based on HTTP/S, data is 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 requests by issuing matching GET/POST calls. Instead, another abstraction is exclusively used to transfer data from the web front end to the server and vice versa. The Open-Xchange Server includes a session daemon (sessiond) that keeps track of users. If the user was successfully authenticated, the information kept in the session is sufficient for accessing the Open-Xchange Server. 2.1.1. 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 external system, i. e. the session object has to contain the password for accessing the external system in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password. Copyright 2010, Open-Xchange GmbH - 4 -
(There are two exceptions: either one master password is used for all IMAP accounts, or a very special implementation of MAL is used, which does not need a password.) 2.1.2. Basic Implementation Rules It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when session information is being passed on by an external system. A session must not be verified by only a SessionID, but has to be verified with at least two different pieces of information, 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 part of a response. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, ) can not lead to wrong sessions. One information is passed to the front end in the headers of the response, the other in the body. Headers are automatically processed by the browser while the body is processed by the client application. To enhance security, the Session-Secret and SessionID are transferred as different parts of a request as well. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as a 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. No attempts to recover will be made. In memory data (SessionID) of the web front end must never be changed during a valid session. All relevant information regarding session management must always be written to log files. The whole mechanism is only secure when being used via an encrypted connection. ATTENTION: If persistent auto-login is activated for the system and a user decides 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. - 5 -
2.2. Authentication and Session Tokens Following tokens are used for the session management: 2.2.1. SessionID The SessionID is used to identify every session. It is a unique UUID without dashes, generated as a random UUID. It is written into the OX log files 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. 2.2.2. Session-Secret The Session-Secret is used to verify every session. It is a unique UUID, generated as a random UUID. Only accesses, with the Session-Secret matching the one stored in the SessionD for the given SessionID are valid. Mismatches lead to immediate session termination. 2.2.3. Random-Token The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3 rd party applications or websites. It is a unique UUID, generated as a random UUID. 2.3. Cookie Handling In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply. 2.3.1. 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 sent to the browser, the original one will be overwritten. With the next client access the SessionID and the Session-Secret do not match anymore and the invalid session is terminated. Copyright 2010, Open-Xchange GmbH - 6 -
2.3.2. Multiple clients with the 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 plug-in session. Therefore the cookie name needs to contain information about the client. 2.3.3. 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 hash built from the clientid and the User-Agent and is used to identify the client. Other parameters to be taken into consideration can be added through a configuration file. 2.3.4. Lifetime of cookies Normally, cookies are session cookies, which are invalidated/deleted when the browser is shut down. Using the persistent auto-login, the cookies are persistent cookies, with a configurable lifetime. The default lifetime is one week. All cookies are deleted when a logout is performed. 2.4. 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 applied, when a session is reactivated following the persistent auto-login process. 2.5. 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: - 7 -
The user does not use the persistent auto-login. The session is only valid as long, as the browser is open. 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 initial 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 must not be passed to the server but it triggers a separate request to store the SessionID as a cookie. 5. The server authenticates the user and sends the following data back to the browser via JSON (all this information is also saved in the session object in sessiond) 1. SessionID, as part of the JSON object 2. Random token for initial login, as part of the JSON object (required for SSO login) 3. Cookie with JSESSIONID for load balancing 4. Cookie with Session-Secret 6. AJAX front end saves the SessionID in memory. AJAX front end ignores the random token. 7. AJAX front end sends the initial data request via JSON to the Open- Xchange Server and provides the following data: 1. SessionID as URL parameter 2. Open-Xchange Server processes this data request and uses the browser cookie with the Session-Secret. 8. Open-Xchange Server checks: 1. SessionID is known by sessiond 2. Session-Secret from cookie is the same as the one stored for this session in sessiond 9. Request is successfully verified and is answered. Copyright 2010, Open-Xchange GmbH - 8 -
10. Random token is discarded after timeout from sessiond. 11. If persistent auto-login is selected, the web front end sends a specific request to the backend: 1. Cookie with SessionID is sent to the browser. The cookie is configured with the relevant type and lifetime 12. Repeat 7. - 10. until end of session. 2.6. Access via web browser after authentication with an external system The goal is to authenticate a user with the Open-Xchange system, from 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 retrieves 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 the user and responds to the external tool with the following data via JSON (all this information is also stored in the session object in sessiond) 1. SessionID, as part of the JSON object 2. Random token for initial login, as part of the JSON object (required for SSO login) 3. Cookie with Session-Secret is not set 3. External tool starts a browser and points it to a special URL, that contains at least following data: 1. Random token for initial login 2. JSESSIONID separated with a semicolon for loadbalancing - 9 -
4. Open-Xchange Server verifies: 1. Random token for validity in sessiond 5. Open-Xchange Server sends to the browser: 1. SessionID, as part of the JSON object 2. Cookie with JSESSIONID for loadbalancing 3. Cookie with the Session-Secret 6. Open-Xchange removes the random token from sessiond. Then the process continues as described in the section above. The session is from then on verified using the SessionID and Session-Secret. Copyright 2010, Open-Xchange GmbH - 10 -
3. Implementation Details The following sections define in detail the required requests and data types for connecting an external system to the Open-Xchange Server. 3.1. 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 used: action provides the login value name the username password the password This request can be answered with 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 can only be used for 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. 3.1.1. Example Authentication: Connected to localhost. GET /ajax/login?action=login&name=<user>&password=<password> HTTP/1.0 HTTP/1.1 200 OK Date: Wed, 28 Jul 2010 10:09:56 GMT Expires: Sat, 06 May 1995 12:00:00 GMT Content-Type: text/javascript; charset=utf-8-11 -
Pragma: no-cache Cache-Control: no-store, no-cache, must-revalidate,post-check=0, pre-check=0 Set-Cookie: JSESSIONID=c070a5b658ae4362b31bb5e0b29ed2b0.OX1; path=/ Set-Cookie: open-xchange-secretwhwm18d0z1d4epe252gg=baae10ef3dab4c489e5e295e31bb9dab; path=/ Connection: close {"session":"c7a3c6e9de024a6caf8d55214f1cff49","random":"c0c36ba4016e4be58dfc d4d00325a12c"} Connection closed by foreign host. 3.2. Session data transfer via URL If the SessionID and the random token are requested by 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> 3.2.1. Example Login with Random Connected to localhost. Escape character is '^]'. GET /ajax/login;jsessionid=1157370816112.ox1? action=redirect&random=176200f5423f4bd899282bce2618efde HTTP/1.0 HTTP/1.1 302 Found Date: Wed, 28 Jul 2010 10:21:20 GMT Expires: Sat, 06 May 1995 12:00:00 GMT Location: /ox6/index.html#session=b40ca3c255b540a49ae9a5f3b17a1409 Pragma: no-cache Cache-Control: no-store, no-cache, must-revalidate,post-check=0, pre-check=0 Set-Cookie: JSESSIONID=222b3916050145c7aa303b352952d10f.OX1; path=/ Copyright 2010, Open-Xchange GmbH - 12 -
Set-Cookie: open-xchange-secretwhwm18d0z1d4epe252gg=8beb2e450f3d482fbda35e1a532a9a96; path=/ Content-Length: 0 Connection: close Content-Type: text/plain 3.2.2. Redirection When initializing the browser with the random token, the cookie with the secret is sent to the browser and the browser is redirected to load the web front end. The URL for loading the GUI looks like this: https://<open-xchange.server>/index.html#session=<random-token> The AJAX GUI has to be located under the respective URL. - 13 -