How do I create a custom or external login interface for WebMail?

You desire complete control over login to Kerio Connect, including a custom web page, or a page hosted on a different server. Other reasons include:

  • Corporate branding: putting a company’s name and logo on the login screen
  • Providing additional content, such as company’s email usage policy
  • Integration with company’s web portal, including fully automated login

NOTE

The solution in this article applies to all Kerio Connect versions. The solution is supported since Kerio MailServer 6.1.2., any version older than Kerio Connect version may need small modifications of URL path to login scripts as the location may differ. Kerio Connect 9.x and newer introduce new security option preventing clickjacking attack. This option is stored in mailserver.cfg and prevents the Kerio Connect client to be referenced from other locations. See Security section for more details at the end of this article.

Kerio Connect provides a method allowing organizations to customize the login process to the WebMail interface. Typically organizations want to do it for reasons such as:

The login process to Kerio Connect is controlled by a script residing on the server and available on the following URL:

  • Kerio Connect 7.4.0 and newer - https://<server>/webmail/login/dologin
  • Kerio Connect 7.0.x - 7.3.x - https://<server>/webmail/default/dologin.php
  • Kerio MailServer 6.x - https://<server>/default/dologin.php

Following variables must be submitted to this script by custom login page via a POST method:

  • kerio_username - User’s login name
  • kerio_password - User’s password

Example of a minimum login page:

<html> <head><title>my login page</title></head> <body> <p>Login to kerio mailserver webmail:</p> <form action="https://my.kerio.server/webmail/login/dologin" method="post"> username: <input name="kerio_username"><br /> password: <input name="kerio_password" type="password"><br /> <!-- advanced features may be put here - > <input type="submit" value="log in"> </form> </body> </html>

Kerio Connect can be used to host the login page, if external location like company's web portal is not desirable. In this case the file should be placed in <install path>/web/custom/index.html. Access the login page using https://<server.address>/custom.

Advanced features

More advanced control of WebMail's behavior can be achieved by providing optional variables. They can be predefined in the login page as hidden form fields, or offered to the user as form options to select from.

WebMail mode

kerio_mode

Possible values: full, mini, pda

Default: full

Mode Description
full full-featured version; requires one of following browsers: Microsoft Internet Explorer 6.0 or higher, Safari 1.2 or higher, Mozilla 1.7 or higher, Firefox 1.0 or higher
mini light version which works well on any browser and on slow connection
pda optimized for PDA devices, such as iPhone or iPad.

Full mode

If the mode is set to full, WebMail will check for browser capabilities and if the browser is not suitable, it will be redirected to mini mode with an explanatory warning.

Mode selection:

Select WebMail mode:<br /> <input name="kerio_mode" type="radio" value="full" checked> Full-featured (for fast/LAN connections)<br /> <input name="kerio_mode" type="radio" value="mini"> Simplified (for slow connections)<br />

PDA mode

<input name="kerio_mode" type="hidden" value="pda">

Start folder

kerio_start Folder

Folder to display after login.

Possible values: folder name or //today for "Today" page

Examples: Calendar, Public Folders/Contacts

This option allows to specify a folder, which will be loaded after the user logs in. If specified, it will override user's setting for displaying "Today" page or Inbox.

Full mode is required to display "Today" page, calendar folders and task folders.

Example: <input name="kerio_startFolder" type="hidden" value="Calendar">

The value should be set to original English name of the folder, not the localized one (e.g. Inbox is localized to Posteingang for German users of WebMail). The original name can be easily found out by switching WebMail to English.

If there are any national (non-Ascii) characters in folder name, charset of the login page should be set to utf-8. This can be achieved e.g. by using the following tag:

<head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> ...

Fully automatic login

External web application may create and submit login form automatically, if username and password are known to it. User then will be logged into WebMail by a single mouse click.

Following example shows autologin script for linking from corporate Intranet to its address book. In this case user publicContactsUser with password publicContactsPassword has to be created for such purpose.

The publicContactsUser account should not be allowed to send emails to other domains and it should have the 0 quota set. It cause this account can't be used as the email account.

Corporate address book

<html> <head> <title>WebMail Autologin</title> </head> <body onLoad="document.forms[0].submit()"> <form action="https://my.kerio.server/webmail/login/dologin" method="post"> <input name="kerio_username" type="hidden" value="publicContactsUser"> <input name="kerio_password" type="hidden" value="publicContactsPassword"> <input name="kerio_startFolder" type="hidden" value="Public Folders/Contacts"> </form> </body> </html>

Security considerations

  1. It is strongly recommended to call the login script dologin.php using https, so that passwords are not sent over the network unencrypted. However, http is still available, if it is not disabled by Kerio Connect administrator.
  2. Kerio Connect 9.x and newer introduce new security option preventing clickjacking attack. This option is stored in mailserver.cfg and prevents the Kerio Connect client to be referenced from other locations. This is done using special HTTP header called X-Frame-Options, which supports following options:
  • DENY, which prevents any domain from framing the content. The "DENY" setting is recommended unless a specific need has been identified for framing.
  • SAMEORIGIN, which only allows the current site to frame the content. This is default option.
  • ALLOW-FROM uri, which permits the specified 'uri' to frame this page. (e.g., ALLOW-FROM http://www.example.com) This will fail open if the browser does not support it.

You can change this behavior in Kerio Connect configuration file. To do so follow these instructions:

  1. Stop Kerio Connect service.
  2. Open mailserver.cfg file using text editor of your choice.
  3. Locate the table "Http", option AppendHeaderXFrameOptions withing the configuration file and change its value to "ALLOW-FROM https://example.com/", where the URL is according to the site linking the login dialog. eg.:

<table name="Http"> ... <variable name="AppendHeaderXFrameOptions">ALLOW-FROM https://example.com/</variable> ...

  1. Save mailserver.cfg file and start the Kerio Connect service.

NOTE

Any customizations not explicitly mentioned in the manual are not supported.

  • 1 Users Found This Useful
Was this answer helpful?

Related Articles

How do I convert the Webmail / WebAdmin into my language?

IMPORTANT This article applies to versions 7 and prior. For current instructions with Kerio...

Authentication to Webmail or through email client fails

Kerio Connect supports several types of authentication methods. You can manage the...