Creating Custom Login Interface for WebMail

Overview

Users may need to have control over the Kerio Connect login page for various reasons. The following are some of the reasons:

To create a custom webpage
To host a Page on a different server
To add the company's name and logo on the login screen for corporate branding
To provide additional content, such as company’s email usage policy
To integrate with the company’s web portal, including fully automated login

This article provides detailed information for creating a custom or external login interface for WebMail.

Environment

All versions of Kerio Connect since Kerio MailServer 6.1.2. Older versions may need small modifications of URL path to login scripts as the location may differ.

Kerio Connect 9.x and newer have introduced new security options for preventing clickjacking attacks. This option is stored in mailserver.cfg and prevents the Kerio Connect client to be referenced from other locations. For further details, refer to the Security section.

Information

The Kerio Connect login process 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

The 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 an external location like the company's web portal is not desirable. In this case, the file should be placed in <install path>/web/custom/index.html and you can 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 value: full

Mode	Description
full	This is a full-featured version. It requires one of the following browsers: Internet Explorer 6.0 or higher, Safari 1.2 or higher, Firefox 1.0 or higher 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.
mini	This is the light version that works well on any browser and on a slow connection.
pda	This version is optimized for PDA devices, such as iPhone or iPad.

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 />
   <input name="kerio_mode" type="hidden" value="pda"> PDA mode
  <br />

Start folder

kerio_start Folder

Possible values: <folder name> or //today for Today page

Examples: Calendar, Public Folders/Contacts

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

Full mode is required to display Today page, Calendar folders, and Task folders. For example:
```
<input name="kerio_startFolder" type="hidden" value="Calendar">
```
The value should be set to the 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 the folder name, charset of the login page should be set to utf-8. This can be achieved by using the following tag:
```
<head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> ...
```

Fully Automatic Login

The external web application may create and submit a login form automatically if a username and password are known to it. In this case, the user will be logged in to WebMail by a single mouse click.

The following example shows an autologin script for linking from corporate Intranet to its address book. A user publicContactsUser with password publicContactsPassword must be created for such a purpose.

Note: The publicContactsUser account should not be allowed to send emails to other domains and it should have the 0 quota set. It causes this account to not be used as an 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

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 the Kerio Connect administrator.
Kerio Connect 9.x and newer have introduced new security options preventing clickjacking attacks. This option is stored in mailserver.cfg and prevents the Kerio Connect client to be referenced from other locations. This is done using a special HTTP header called X-Frame-Options that supports the following options:
- DENY: It prevents any domain from framing the content. This setting is recommended unless a specific need has been identified for framing.
- SAMEORIGIN: It only allows the current site to frame the content. This is the default option.
- ALLOW-FROM <URL>: It permits the specified URL to frame this page and will fail to open if the browser does not support it.
Follow the instructions below to change this behavior in the Kerio Connect configuration file:
1. Stop the Kerio Connect service.
2. Open the mailserver.cfg file using a text editor of your choice.
3. Locate the table Http and the option AppendHeaderXFrameOptions within the configuration file.
4. Change its value to ALLOW-FROM <https://example.com/>, where the URL is according to the site linking the login dialog. For example:
```
<table name="Http">
 ... 
<variable name="AppendHeaderXFrameOptions">ALLOW-FROM <https://example.com/></variable>
 ...
```
5. Save the mailserver.cfg file.
6. Start the Kerio Connect service.

Choose files or drag and drop files

Tags:

Was this article helpful?

Yes

Priyanka Bhotika
Posted
Updated

Comments

Please sign in to comment